mirror of
https://github.com/infiniflow/ragflow.git
synced 2026-07-30 20:49:21 +08:00
dcadd8d837
### Summary Adds a `tenki` sandbox provider that runs each agent code execution in a disposable Tenki (https://tenki.cloud) microVM (create → exec → destroy, no volumes or snapshots). Registration mirrors PR #15039, configure `api_key` and `project_id` in Admin > Sandbox Settings. Both runtimes are covered: - Python: `agent/sandbox/providers/tenki.py` (structured results + artifact collection). - Go: `internal/agent/sandbox/tenki.go`, mirroring the e2b provider and wired into the provider manager. `tenki-sandbox` is an optional dependency (it requires `protobuf>=6.31`, which differs from RAGFlow's pinned gRPC stack), lazily imported with a clear error when missing; installation is documented in the sandbox quickstart. Unit tests cover execution, structured results, artifacts (symlink/size/extension limits), non-zero exit, timeout, error mapping, and idempotent destroy. --------- Co-authored-by: yiming.wang <yiming.wang@luxor.com>
240 lines
8.1 KiB
Markdown
240 lines
8.1 KiB
Markdown
---
|
|
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`, `e2b`, and `tenki`: Cloud providers.
|
|
|
|
<img width="2547" height="1475" alt="admin-sandbox-settings" src="https://github.com/user-attachments/assets/59ab948e-b98a-45a8-9db4-f1afbf6c3685" />
|
|
|
|
## 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](https://tenki.cloud) microVM. See [Tenki](#tenki) 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-sandbox` 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-sandbox
|
|
```
|
|
|
|
Configure it in **Admin > Sandbox Settings**:
|
|
|
|
- `api_key` (required): Tenki API key. Create one at [app.tenki.cloud](https://app.tenki.cloud) under **API Keys**.
|
|
- `project_id` (required): the Tenki project that sandboxes are created under.
|
|
- `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.
|
|
|
|
## 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
|
|
```
|