ContextQMD
Back to Ragflow

Sandbox Quickstart

docs/guides/agent/agent_quickstarts/sandbox_quickstart.md

0.27.19.3 KB
Original Source

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, e2b, tenki, and ucloud_agent_sandbox: Cloud providers.

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.
  • tenki: Cloud-hosted provider that runs each execution in a disposable Tenki microVM. See Tenki below.
  • ucloud_agent_sandbox: Cloud-hosted provider that runs each execution in a disposable UCloud Agent Sandbox. See UCloud Agent Sandbox below.

Tenki

tenki runs each code execution in a fresh Tenki microVM and destroys it afterwards. It is cloud-hosted, so it needs no local sandbox services, gVisor, or Docker base images — only outbound network access and an API key.

The tenki SDK is an optional dependency (it requires protobuf>=6.31, which differs from RAGFlow's default gRPC stack), so it is not installed by default. Install it into the RAGFlow runtime before selecting this provider:

bash
pip install tenki

Configure it in Admin > Sandbox Settings:

  • api_key (required): Tenki API key. Create one at app.tenki.cloud under API Keys.
  • base_url (optional): override the Tenki API endpoint.
  • image (optional): sandbox base image. Leave empty to use the Tenki default image, which includes python3 and node.
  • allow_outbound (optional, security-relevant): whether the sandbox may make outbound network connections. Defaults to false so sandboxed code has no network access; set it to true when code needs the network (for example, to install packages).
  • timeout, max_lifetime, cpu_cores, memory_mb, disk_size_gb, and the output/artifact limits have sensible defaults and can be tuned in the same page.

Notes:

  • Supported languages are Python and JavaScript.
  • Files written to the artifacts/ directory of the working directory are returned as run artifacts.
  • The provider uses only Tenki's create/exec/destroy operations; it does not use volumes or snapshots.

UCloud Agent Sandbox

ucloud_agent_sandbox uses UCloud's native Sandbox SDK to create one disposable sandbox for each CodeExec run. No local sandbox service or Docker runtime is required.

Configure it in Admin > Sandbox Settings:

  • api_key (required): obtain one from UCloud ModelVerse API Keys.
  • region: defaults to cn-wlcb; us-ca is also supported.
  • domain and api_url: optional endpoint overrides for private or custom deployments.
  • template: defaults to base, which includes Python and Node.js runtimes.
  • allow_internet_access: defaults to false; enable it only when sandboxed code needs outbound network access.
  • timeout, sandbox_timeout, and the output/artifact limits can be tuned for the workload.

Notes:

  • Supported languages are Python and JavaScript.
  • RAGFlow uses HTTPS with TLS certificate verification. The insecure_http option is intended only for trusted test deployments.
  • Files written to the execution workspace's artifacts/ directory are returned as run artifacts.
  • The Python runtime dependency is installed with RAGFlow. The Go runtime uses UCloud's native Go SDK.

See UCloud Agent Sandbox prerequisites and regions.

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.

  1. 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

  2. Start the RAGFlow service as usual.

  3. Open Admin > Sandbox Settings.

  4. Select a provider.

  5. Fill in the required fields.

  6. Click Save.

  7. 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