ragflow/docs/guides/agent/agent_quickstarts/sandbox_quickstart.md

---
sidebar_position: 20
slug: /sandbox_quickstart
sidebar_custom_props: {
  categoryIcon: LucideCodesandbox
}
---
# Sandbox quickstart

A secure, pluggable code execution backend designed for RAGFlow and other applications requiring isolated code execution environments.

RAGFlow's `CodeExec` agent component depends on a sandbox provider to run Python and JavaScript code. Configure one of the providers below before using `CodeExec`.

## Features: 

- Seamless RAGFlow Integration — Works out-of-the-box with the code component of RAGFlow.
- High Security — Uses gVisor for syscall-level sandboxing to isolate execution.
- Customisable Sandboxing — Modify seccomp profiles easily to tailor syscall restrictions.
- Pluggable Runtime Support — Extendable to support any programming language runtime.
- Developer Friendly — Quick setup with a convenient Makefile.

## Architecture

The architecture consists of isolated Docker base images for each supported language runtime, managed by the executor manager service. The executor manager orchestrates sandboxed code execution using gVisor for syscall interception and optional seccomp profiles for enhanced syscall filtering.

## Provider options

RAGFlow supports two sandbox provider types:

- `self_managed`: Runs code inside Docker-managed sandbox containers. Use this for the standard RAGFlow sandbox deployment.
- `local`: Runs code as local Python or Node.js subprocesses. Use this only in trusted development environments.

## 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`.
- Set `SANDBOX_PROVIDER_TYPE=self_managed` or `SANDBOX_PROVIDER_TYPE=local`.
- For `self_managed`, include `sandbox` in `COMPOSE_PROFILES`.
- For `local`, uncomment and adjust the `SANDBOX_LOCAL_*` variables.

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.

## Environment variables

The variables in `docker/.env` are grouped by scope.

### Shared variables

These variables apply to sandbox support in general:

- `SANDBOX_ENABLED`: Enables sandbox support in RAGFlow.
- `SANDBOX_PROVIDER_TYPE`: Selects the active provider. Supported values are `self_managed` and `local`.
- `SANDBOX_HOST`: The executor manager host used by the self-managed provider and the legacy HTTP fallback.
- `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 variables

These variables apply when `SANDBOX_PROVIDER_TYPE=self_managed`:

- `COMPOSE_PROFILES`: Must include `sandbox` to start `sandbox-executor-manager` with RAGFlow.
- `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.

### Local variables

These variables apply when `SANDBOX_PROVIDER_TYPE=local`:

- `SANDBOX_LOCAL_ENABLED`: Explicitly enables local code execution.
- `SANDBOX_LOCAL_PYTHON_BIN`: Python executable used by local execution.
- `SANDBOX_LOCAL_NODE_BIN`: Node.js executable used by local execution.
- `SANDBOX_LOCAL_WORK_DIR`: Working directory for local execution files and artifacts.
- `SANDBOX_LOCAL_TIMEOUT`: Maximum local execution time in seconds.
- `SANDBOX_LOCAL_MAX_MEMORY_MB`: Address-space memory limit for local child processes.
- `SANDBOX_LOCAL_MAX_OUTPUT_BYTES`: Maximum stdout and stderr size.
- `SANDBOX_LOCAL_MAX_ARTIFACTS`: Maximum number of artifacts collected after execution.
- `SANDBOX_LOCAL_MAX_ARTIFACT_BYTES`: Maximum size for each artifact.
- `OPENBLAS_NUM_THREADS`, `OMP_NUM_THREADS`, `MKL_NUM_THREADS`, `NUMEXPR_NUM_THREADS`, `BLIS_NUM_THREADS`, `VECLIB_MAXIMUM_THREADS`: Optional native math library thread limits for local Python subprocesses.

## 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
```