--- sidebar_position: 20 slug: /sandbox_quickstart sidebar_custom_props: { categoryIcon: LucideCodesandbox } --- # Sandbox quickstart RAGFlow's `CodeExec` agent component needs a sandbox provider to run Python and JavaScript code. The simplest setup flow is: 1. Start the required sandbox services. 2. Open the RAGFlow admin page. 3. Go to **Admin > Sandbox Settings**. 4. Choose a provider and save the configuration. 5. Test the connection in the same page. ## Admin page Configure sandbox providers from the admin page: - `self_managed`: Uses the executor manager service. - `local`: Runs code on the current machine. - `ssh`: Runs code on a remote machine over SSH. - `aliyun_codeinterpreter` and `e2b`: Cloud providers. admin-sandbox-settings ## Provider options RAGFlow supports multiple sandbox providers. Configure the active provider in Admin > Sandbox Settings after the services are up. - `self_managed`: Runs code inside Docker-managed sandbox containers. This is the default provider. - `local`: Runs code as local Python or Node.js subprocesses. Use this only in trusted development environments. - `ssh`: Runs code on a remote machine over SSH. - `aliyun_codeinterpreter` and `e2b`: Cloud-hosted providers that remain available in the admin provider list. ## Prerequisites - Linux distribution compatible with gVisor. - gVisor installed and configured. - Docker version 25.0 or higher (API 1.44+). Ensure your executor manager image ships with Docker CLI `29.1.0` or higher to stay compatible with the latest Docker daemons. - Docker Compose version 2.26.1 or higher (similar to RAGFlow requirements). - uv package and project manager installed. - (Optional) GNU Make for simplified command-line management. :::tip NOTE The error message `client version 1.43 is too old. Minimum supported API version is 1.44` indicates that your executor manager image's built-in Docker CLI version is lower than `29.1.0` required by the Docker daemon in use. ::: ## Build Docker base images The sandbox uses isolated base images for secure containerized execution environments. ### Option 1: Build from source Build the runtime base images: ```bash docker build -t sandbox-base-python:latest ./sandbox_base_image/python docker build -t sandbox-base-nodejs:latest ./sandbox_base_image/nodejs ``` Alternatively, build all base images at once using the Makefile: ```bash make build ``` Build the executor manager image: ```bash docker build -t sandbox-executor-manager:latest ./executor_manager ``` ### Option 2: Pull base images from Docker Hub If you do not need to customize runtime dependencies, pull the published base images and tag them with the names used by standalone Docker Compose: ```bash docker pull infiniflow/sandbox-base-python:latest docker pull infiniflow/sandbox-base-nodejs:latest docker tag infiniflow/sandbox-base-python:latest sandbox-base-python:latest docker tag infiniflow/sandbox-base-nodejs:latest sandbox-base-nodejs:latest ``` Then restart the standalone sandbox services: ```bash docker compose -f docker-compose.yml down docker compose -f docker-compose.yml up -d ``` ## Running with RAGFlow 1. Verify that gVisor is properly installed and operational. 2. Configure the .env file located at docker/.env: - Set `SANDBOX_ENABLED=1`. - Include `sandbox` in `COMPOSE_PROFILES` if you want the default `self_managed` executor-manager service. - Keep the self-managed deployment defaults in `.env` if you need to change the sandbox-executor-manager image, pool size, base images, seccomp, memory, or timeout. 3. Add the following entry to your /etc/hosts file to resolve the executor manager service: ```bash 127.0.0.1 es01 infinity mysql minio redis sandbox-executor-manager ``` 4. Start the RAGFlow service as usual. 5. Open **Admin > Sandbox Settings**. 6. Select a provider. 7. Fill in the required fields. 8. Click **Save**. 9. Click **Test Connection** if needed. ## Environment variables The variables in `docker/.env` are grouped by scope. ### System-level variables These variables apply to sandbox support in general: - `SANDBOX_ENABLED`: Enables sandbox support in RAGFlow. - `COMPOSE_PROFILES`: Include `sandbox` to start the default self-managed executor-manager service. - `SANDBOX_ARTIFACT_BUCKET`: MinIO bucket used for files generated by sandbox code. - `SANDBOX_ARTIFACT_EXPIRE_DAYS`: Number of days before sandbox artifacts expire. ### Self-managed deployment defaults These variables are shown in Admin as deployment defaults for `self_managed`. Changing them requires restarting `sandbox-executor-manager`. - `SANDBOX_EXECUTOR_MANAGER_IMAGE`: Docker image for the executor manager service. - `SANDBOX_EXECUTOR_MANAGER_POOL_SIZE`: Number of Python and Node.js sandbox containers kept in the pool. - `SANDBOX_BASE_PYTHON_IMAGE`: Python runtime image used by executor-managed containers. - `SANDBOX_BASE_NODEJS_IMAGE`: Node.js runtime image used by executor-managed containers. - `SANDBOX_EXECUTOR_MANAGER_PORT`: Host port exposed by the executor manager. - `SANDBOX_ENABLE_SECCOMP`: Enables the optional seccomp profile for sandbox containers. - `SANDBOX_MAX_MEMORY`: Memory limit for each sandbox runtime container. - `SANDBOX_TIMEOUT`: Default execution timeout. ### Admin-managed runtime settings Provider selection and runtime settings are configured in **Admin > Sandbox Settings**. Examples: - Choose the active provider - Configure `self_managed` runtime settings - Configure all `local` settings - Configure all `ssh` settings For `self_managed`: - Runtime settings are editable in Admin - Deployment defaults come from `.env` and are shown as read-only values ## Running standalone ### Manual setup 1. Initialize the environment variables: ```bash cp .env.example .env ``` 2. Launch the sandbox services with Docker Compose: ```bash docker compose -f docker-compose.yml up ``` 3. Test the sandbox setup: ```bash source .venv/bin/activate export PYTHONPATH=$(pwd) uv pip install -r executor_manager/requirements.txt uv run tests/sandbox_security_tests_full.py ``` ### Using Makefile Run all setup, build, launch, and tests with a single command: ```bash make ``` ### Monitoring To follow logs of the executor manager container: ```bash docker logs -f sandbox-executor-manager ``` Or use the Makefile shortcut: ```bash make logs ```