RAGFlow is an agent-native database: a Retrieval-Augmented Generation (RAG) engine that grew into context infrastructure.
Go agent-harnessagent-native-databaseagentic-aiagentic-retrievalagentic-searchaiai-agentscontext-enginecontext-engineeringcontext-managementharness-engineeringknowledge-compilationragretrieval-augmented-generationretrieval-harnesssearch-harness
docs(sandbox): correct external deployment guidance (#20810)
Sbaaoui Idrisscb3dc4047e38
diff --git a/docker/.env b/docker/.envindex d57c47c996..4e8f90d193 100644--- a/docker/.env+++ b/docker/.env@@ -413,20 +413,16 @@ ENABLE_REGISTER=1# Sandbox provider type and runtime settings are configured in Admin > Sandbox# Settings.-# Enable sandbox support.-# SANDBOX_ENABLED=1+# Start the optional published-image executor manager.# COMPOSE_PROFILES=${COMPOSE_PROFILES},sandbox# Shared sandbox settings# The MinIO bucket name for storing sandbox-generated artifacts.# SANDBOX_ARTIFACT_BUCKET=sandbox-artifacts-# Number of days before sandbox artifacts are automatically deleted.-# SANDBOX_ARTIFACT_EXPIRE_DAYS=7-# Self-managed deployment defaults-# These values are used by the `sandbox` compose profile and shown in Admin as-# deployment defaults for the self-managed provider.+# These values configure the optional `sandbox` Compose service, not the+# RAGFlow client. Build and security guidance: https://github.com/infiniflow/sandbox# Pull the required base images before running:# docker pull infiniflow/sandbox-base-nodejs:latest# docker pull infiniflow/sandbox-base-python:latest@@ -443,9 +439,9 @@ ENABLE_REGISTER=1# SANDBOX_TIMEOUT=10s # s, m, 1m30s# Shared secret required by sandbox-executor-manager's /run endpoint-# (Authorization: Bearer or X-Sandbox-Token). Strongly recommended; the same-# value is injected into the ragflow service. Leave unset for backwards-# compatibility (the executor manager then logs a security warning).+# (Authorization: Bearer or X-Sandbox-Token). The same value is injected into+# RAGFlow. Current Sandbox source rejects /run without configured authentication;+# verify the behavior of the published image version you deploy.# Generate one with: openssl rand -hex 32# SANDBOX_EXECUTOR_MANAGER_API_TOKEN=diff --git a/docker/docker-compose-base.yml b/docker/docker-compose-base.ymlindex 7cdd7e7f5d..2db694e1bc 100644--- a/docker/docker-compose-base.yml+++ b/docker/docker-compose-base.yml@@ -239,8 +239,8 @@ services:- SANDBOX_MAX_MEMORY=${SANDBOX_MAX_MEMORY:-256m}- SANDBOX_TIMEOUT=${SANDBOX_TIMEOUT:-10s}# Shared secret for the /run API. Set it in .env (same value is passed- # to the ragflow service); when empty the API stays open (backwards- # compatible) but a warning is logged.+ # to the ragflow service). Current Sandbox source rejects unconfigured+ # authentication; verify the behavior of the deployed image version.- SANDBOX_EXECUTOR_MANAGER_API_TOKEN=${SANDBOX_EXECUTOR_MANAGER_API_TOKEN:-}# Sandbox runner containers get no external network by default.- SANDBOX_CONTAINER_NETWORK=${SANDBOX_CONTAINER_NETWORK:-none}diff --git a/docs/administrator/admin/admin_ui/configure_code_execution_sandbox.md b/docs/administrator/admin/admin_ui/configure_code_execution_sandbox.mdindex 55b4c30e56..8baf005eab 100644--- a/docs/administrator/admin/admin_ui/configure_code_execution_sandbox.md+++ b/docs/administrator/admin/admin_ui/configure_code_execution_sandbox.md@@ -14,7 +14,7 @@ The current page supports the following `Provider` options:| Provider | Description || --- | --- |-| `Self-Managed` | Use Daytona or Docker for localized deployment. |+| `Self-Managed` | Connect to the external [Sandbox executor manager](https://github.com/infiniflow/sandbox). || `SSH` | Execute code on a remote machine through SSH. || `AliyunCodeInterpreter` | Use Alibaba Cloud Function Compute Code Interpreter. || `E2B` | Use E2B Cloud Code Execution Sandboxes. |@@ -48,11 +48,12 @@ When configuring a sandbox, first fill in the connection information and runtime| Parameter | Description | Recommendation || --- | --- | --- || `Executor Manager Endpoint` | Access address of the `SandboxExecutorManager` service. | Enter the HTTP address of the code execution service, such as `http://sandbox-executor-manager:9385` or `http://<SERVER_IP>:9385`. Make sure RAGFlow can access this address. |+| `Executor Manager API Token` | Shared secret authenticating RAGFlow to the executor manager. | Set the same strong token on the service; a blank field falls back to `SANDBOX_EXECUTOR_MANAGER_API_TOKEN`. || `Request Timeout (seconds)` | Timeout for requests to the code execution service. | Configure according to the network environment and code execution duration. The default 30 seconds is sufficient for most cases; increase it for large tasks. |`Executor Manager Endpoint` must be the address of a deployed and normally running `SandboxExecutorManager` service.-`Deployment Defaults` displays the current default deployment parameters of `SandboxExecutorManager`.+The standalone Sandbox repository owns runtime images, pool sizing, isolation, and execution limits. RAGFlow's optional Compose profile runs a published image; it does not build it. Admin settings do not reconfigure or report the state of an independently hosted service. See [Sandbox quickstart](../../configurations/sandbox_quickstart.md).## SSH Configurationdiff --git a/docs/administrator/configurations/sandbox_quickstart.md b/docs/administrator/configurations/sandbox_quickstart.mdindex 877c2b48d5..e2292f3aeb 100644--- a/docs/administrator/configurations/sandbox_quickstart.md+++ b/docs/administrator/configurations/sandbox_quickstart.md@@ -55,174 +55,52 @@ Notes:- 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.-## Self-Managed prerequisites+## Self-managed architecture-The following prerequisites apply only when you use the `self_managed` provider:+RAGFlow is a client of the external executor-manager service. The [Standalone Sandbox repository](https://github.com/infiniflow/sandbox) owns its implementation, Python and Node.js runtime images, Dockerfiles, image builds, container lifecycle, dependencies, and security configuration.-- 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.+Follow that repository's installation and build instructions on the **sandbox service host**. RAGFlow does not build sandbox images. A separately hosted sandbox does not require Docker or gVisor on the RAGFlow host; RAGFlow needs network access to its endpoint.-:::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.-:::+## Connect RAGFlow to an external sandbox-## Build Docker base images+In **Admin > Sandbox Settings**, select `self_managed` and configure:-The sandbox uses isolated base images for secure containerized execution environments.+| Setting | Purpose |+| --- | --- |+| `endpoint` | Executor-manager HTTP address reachable from RAGFlow, such as `http://sandbox-host:9385`. |+| `api_token` | Shared authentication token; use the same value on the service. A blank value falls back to `SANDBOX_EXECUTOR_MANAGER_API_TOKEN`. |+| `timeout` | HTTP request timeout in seconds, default `30`. This does not configure the service's execution timeout. |-### Option 1: Build from source+Save the configuration and click **Test Connection**. This executes a small Python program; a successful `/healthz` response alone does not establish that code execution is available.-Build the runtime base images:+Without saved settings, the client uses `SANDBOX_PROVIDER_TYPE` (default `self_managed`), `SANDBOX_EXECUTOR_MANAGER_URL` (default `http://sandbox-executor-manager:9385`), and `SANDBOX_EXECUTOR_MANAGER_TIMEOUT` (a duration such as `30s`). Saved connection settings take precedence.-```bash-docker build -t sandbox-base-python:latest ./sandbox_base_image/python-docker build -t sandbox-base-nodejs:latest ./sandbox_base_image/nodejs-```+Current [Sandbox authentication source](https://github.com/infiniflow/sandbox/blob/main/executor_manager/services/auth.py) rejects `/run` with HTTP 503 when no token is configured, unless the service operator explicitly enables unauthenticated access. Configure a strong shared token. Published image tags may differ from current source; verify the authentication behavior of the version you deploy.-Alternatively, build all base images at once using the Makefile:+The existing `base_python_image` and `base_nodejs_image` settings send an optional `base_image` request field for custom managers. The current reference service does not apply that field: configure its runtime images on the service host instead.-```bash-make build-```+## Optional published-image deployment with RAGFlow-Build the executor manager image:+The `sandbox` Compose profile can start a published executor-manager image alongside RAGFlow. It pulls/runs the image and does not build it. Its runtime containers and isolation still belong to the external service.-```bash-docker build -t sandbox-executor-manager:latest ./executor_manager-```+In `docker/.env`:-### Option 2: Pull base images from Docker Hub+- Include `sandbox` in `COMPOSE_PROFILES`.+- Set `SANDBOX_EXECUTOR_MANAGER_API_TOKEN` to the shared secret passed to both services.+- Pull the Python and Node.js runtime images named by the deployment before starting it.-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:+Start RAGFlow using its usual Compose instructions, then configure `http://sandbox-executor-manager:9385` as the admin endpoint. Services on the shared Compose network resolve that name automatically; no host `/etc/hosts` entry is needed.-```bash-docker pull infiniflow/sandbox-base-python:latest-docker pull infiniflow/sandbox-base-nodejs:latest+For RAGFlow running directly on the same host, use `http://127.0.0.1:<published-port>`. The supplied Compose service publishes its port on loopback only. For a remote sandbox, use a reachable address secured by the sandbox operator rather than the local Compose service name.-docker tag infiniflow/sandbox-base-python:latest sandbox-base-python:latest-docker tag infiniflow/sandbox-base-nodejs:latest sandbox-base-nodejs:latest-```+Compose deployment variables remain available in `docker/.env`: `SANDBOX_EXECUTOR_MANAGER_IMAGE`, `SANDBOX_EXECUTOR_MANAGER_PORT`, `SANDBOX_EXECUTOR_MANAGER_POOL_SIZE`, `SANDBOX_BASE_PYTHON_IMAGE`, `SANDBOX_BASE_NODEJS_IMAGE`, `SANDBOX_ENABLE_SECCOMP`, `SANDBOX_MAX_MEMORY`, `SANDBOX_CONTAINER_NETWORK`, and `SANDBOX_TIMEOUT`. These configure the optional service, not RAGFlow's HTTP connection. Apply service deployment changes through Compose and follow the Sandbox repository's security guidance. Preserve the default runner network isolation (`none`) unless outbound access is deliberately required.-Then restart the standalone sandbox services:+Admin schema values are not a readback of the external service's deployed configuration. Saving connection settings does not restart or reconfigure that service.-```bash-# Stop the standalone Sandbox services before applying the changes.-docker compose -f docker-compose.yml down-# Start the standalone Sandbox services in the background.-docker compose -f docker-compose.yml up -d-```+## RAGFlow artifact storage-## Running with RAGFlow+`SANDBOX_ARTIFACT_BUCKET` selects RAGFlow's object-storage bucket for files returned by sandbox providers. It is independent of executor-manager deployment and defaults to `sandbox-artifacts`. RAGFlow publishes returned artifact bytes and serves them through its authorized artifact endpoint.-1. If you use the `self_managed` provider, verify that gVisor is installed and operational.+## Other providers-2. Configure **docker/.env**:--- Include `sandbox` in `COMPOSE_PROFILES` if you want the default `self_managed` executor-manager service.-- If you use the `ssh` provider, set `RAGFLOW_SSH_KNOWN_HOSTS` to the host `known_hosts` file and keep `SSH_KNOWN_HOSTS` as the path used inside the Go container. The default values are `${HOME}/.ssh/known_hosts` and `/etc/ragflow/ssh_known_hosts`.-- 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 kvrocks 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 the sandbox deployment:--- `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.--### 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. Defaults to `infiniflow/sandbox-executor-manager:latest`.-- `SANDBOX_EXECUTOR_MANAGER_POOL_SIZE`: Number of Python and Node.js sandbox containers kept in each runtime pool. Defaults to `3`.-- `SANDBOX_BASE_PYTHON_IMAGE`: Python runtime image used by executor-managed containers. Defaults to `infiniflow/sandbox-base-python:latest`.-- `SANDBOX_BASE_NODEJS_IMAGE`: Node.js runtime image used by executor-managed containers. Defaults to `infiniflow/sandbox-base-nodejs:latest`.-- `SANDBOX_EXECUTOR_MANAGER_PORT`: Host port exposed by the executor manager. Defaults to `9385` and binds to `127.0.0.1` in the provided Compose configuration.-- `SANDBOX_ENABLE_SECCOMP`: Enables the optional seccomp profile for sandbox containers. Defaults to `false`.-- `SANDBOX_MAX_MEMORY`: Memory limit for each sandbox runtime container. Defaults to `256m`; it is not the total memory limit for all sandbox containers.-- `SANDBOX_CONTAINER_NETWORK`: Docker network attached to each sandbox runtime container. Defaults to `none`, which prevents external network access. Use `bridge` only when sandboxed code needs outbound network access.-- `SANDBOX_TIMEOUT`: Default execution timeout. Defaults to `10s`.-- `SANDBOX_EXECUTOR_MANAGER_API_TOKEN`: Shared secret used to authenticate requests from RAGFlow to the executor manager. Set a strong value for network-accessible deployments; the same value is passed to both services by the provided Compose configuration.--### 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 `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-```+SSH and cloud providers do not require the optional executor-manager service. For SSH, retain the host known-hosts mount configured by `RAGFLOW_SSH_KNOWN_HOSTS` and the container path `SSH_KNOWN_HOSTS`.diff --git a/docs/guides/agent/agent_workflow/data_manipulation_components.md b/docs/guides/agent/agent_workflow/data_manipulation_components.mdindex 4f34ae72f9..489f56167e 100644--- a/docs/guides/agent/agent_workflow/data_manipulation_components.md+++ b/docs/guides/agent/agent_workflow/data_manipulation_components.md@@ -12,7 +12,7 @@ sidebar_custom_props: {## Code ComponentThe Code component executes Python or JavaScript code for complex data processing, format conversion, calculation, file generation and custom logic.-Prerequisite: The Code component requires a configured Sandbox provider. If you select the Self-Managed provider, install and enable gVisor and configure the RAGFlow sandbox environment variables. Restart the service after changing sandbox dependencies or configuration.+Prerequisite: Configure a Sandbox provider in Admin > Sandbox Settings. For Self-Managed, deploy the external service following [Standalone Sandbox](https://github.com/infiniflow/sandbox), then configure its endpoint and token in RAGFlow. Isolation prerequisites belong to the sandbox service host, which may be separate from RAGFlow. See [Sandbox quickstart](../../../administrator/configurations/sandbox_quickstart.md).Configuration:1. **Input**: Define parameters passed into code; variables can be directly referenced inside scripts.diff --git a/internal/agent/sandbox/aliyun.go b/internal/agent/sandbox/aliyun.goindex adb4e82959..6870555f86 100644--- a/internal/agent/sandbox/aliyun.go+++ b/internal/agent/sandbox/aliyun.go@@ -46,8 +46,7 @@ const aliyunDefaultRegion = "cn-hangzhou"const aliyunExecutePath = "/sandboxes/%s/contexts/execute"-// AliyunCodeInterpreterProvider is the Go port of-// `agent/sandbox/providers/aliyun_codeinterpreter.py::AliyunCodeInterpreterProvider`.+// AliyunCodeInterpreterProvider calls Alibaba Cloud Code Interpreter.type AliyunCodeInterpreterProvider struct {accessKeyID stringaccessKeySecret stringdiff --git a/internal/agent/sandbox/artifacts.go b/internal/agent/sandbox/artifacts.goindex 0243bfb849..defa44699a 100644--- a/internal/agent/sandbox/artifacts.go+++ b/internal/agent/sandbox/artifacts.go@@ -19,17 +19,6 @@// an artifact accepted by one is accepted by the other — the// model sees a uniform `artifacts: [{name, content_b64,// mime_type, size}, ...]` shape across providers.-//-// The set is ported verbatim from the Python side:-//-// agent/sandbox/providers/local.py (the _collect_artifacts-// allowlist)-// agent/sandbox/providers/ssh.py (ALLOWED_ARTIFACT_EXTENSIONS)-//-// Python's allowlist includes `.csv .html .jpeg .jpg .json .pdf-// .png .svg`. We mirror it 1:1. To extend, add here AND in-// both Python files.-package sandbox// allowedArtifactExts is the set of file extensions the Localdiff --git a/internal/agent/sandbox/e2b.go b/internal/agent/sandbox/e2b.goindex db41dc6889..d28159675f 100644--- a/internal/agent/sandbox/e2b.go+++ b/internal/agent/sandbox/e2b.go@@ -14,12 +14,7 @@// limitations under the License.//-// e2b.go is the Go port of-// `agent/sandbox/providers/e2b.py` (which is itself a stub on the-// Python side — see Python E2BProvider.execute_code raising-// "E2B provider is not yet fully implemented"). On the Go side we-// go further: we ship a real implementation that talks to e2b-// cloud sandboxes via the community Go SDK.+// E2B execution uses cloud sandboxes through the community Go SDK.//// The community SDK is at github.com/eric642/e2b-go-sdk// (Apache-2.0; community-maintained port of the official@@ -62,10 +57,7 @@ const e2bDefaultTemplate = "base"// the Python e2b-code-interpreter SDK's default.const e2bDefaultSandboxTimeout = 5 * time.Minute-// E2BProvider is the Go port of-// `agent/sandbox/providers/e2b.py::E2BProvider`. On the Python-// side this class is a stub; on the Go side it is a real-// implementation that talks to e2b cloud sandboxes.+// E2BProvider executes code in E2B cloud sandboxes.type E2BProvider struct {client *e2bsdk.Clienttemplate stringdiff --git a/internal/agent/sandbox/local.go b/internal/agent/sandbox/local.goindex 27fb10b6ce..0daeaab8ce 100644--- a/internal/agent/sandbox/local.go+++ b/internal/agent/sandbox/local.go@@ -14,7 +14,7 @@// limitations under the License.//-// local.go is the Go port of `agent/sandbox/providers/local.py`.+// Local execution runs trusted code on the RAGFlow host.//// LocalProvider runs the user's code on the Go host itself via// os/exec. There is no sandboxing — the code runs with the Go@@ -107,8 +107,7 @@ func (c *localOutputCapture) Write(p []byte) (int, error) {return n, err}-// LocalProvider is the Go port of-// `agent/sandbox/providers/local.py::LocalProvider`.+// LocalProvider executes code on the current host.type LocalProvider struct {pythonBin stringnodeBin stringdiff --git a/internal/agent/sandbox/manager.go b/internal/agent/sandbox/manager.goindex 493f880e84..5e6c374657 100644--- a/internal/agent/sandbox/manager.go+++ b/internal/agent/sandbox/manager.go@@ -14,10 +14,7 @@// limitations under the License.//-// manager.go is the Go port of `agent/sandbox/providers/manager.py`.-//-// Configuration source priority (matches the Python load order, see-// `agent/sandbox/client.py::_load_provider_from_settings`):+// Configuration source priority://// 1. Admin-panel `sandbox.provider_type` + `sandbox.{provider_type}`// JSON config stored in the `system_settings` MySQL table. The@@ -30,7 +27,7 @@// `FromConfig` constructor is the single source of truth.//// Once initialized, the manager holds the active provider. There is-// at most one active provider at a time — same as Python, because+// at most one active provider at a time because// sandbox configuration is global.package sandbox@@ -49,9 +46,7 @@ import ("gorm.io/gorm")-// ProviderManager is the Go equivalent of-// `agent/sandbox/providers/manager.py::ProviderManager`. It is-// goroutine-safe and lazily initialized.+// ProviderManager is goroutine-safe and lazily initialized.type ProviderManager struct {refreshMu sync.Mutexmu sync.RWMutex@@ -62,9 +57,7 @@ type ProviderManager struct {settingsConfigured bool}-// globalManager is the package-level manager. Mirrors the Python-// `_provider_manager` global in `agent/sandbox/client.py`. Tests-// can use SetProvider to inject a custom provider.+// globalManager is the package-level manager. Tests can inject a provider.var (globalManager *ProviderManagerglobalManagerOnce sync.Once@@ -216,10 +209,7 @@ func (m *ProviderManager) LoadFromSettingsWithReader(ctx context.Context, db *goreturn nil}-// ReloadFromSettings resets the manager and re-reads the admin-panel-// settings. Mirrors Python's `reload_provider()` in-// `agent/sandbox/client.py` — call after the operator updates the-// sandbox settings.+// ReloadFromSettings resets the manager and re-reads admin settings.func (m *ProviderManager) ReloadFromSettings(ctx context.Context, db *gorm.DB) error {return m.ReloadFromSettingsWithReader(ctx, db, dao.NewSystemSettingsDAO())}diff --git a/internal/agent/sandbox/provider.go b/internal/agent/sandbox/provider.goindex e8d275f4dc..8046334c3d 100644--- a/internal/agent/sandbox/provider.go+++ b/internal/agent/sandbox/provider.go@@ -16,17 +16,8 @@// Package sandbox implements RAGFlow's Go-side CodeExec sandbox subsystem.//-// The package is the Go port of `agent/sandbox/` in the Python repo. It-// exposes a single active provider (self_managed or aliyun_codeinterpreter-// today; e2b is a loud stub) through a ProviderManager. The-// ManagerClient returned by NewManagerClient implements the-// tool.SandboxClient interface in the parent package, so the CodeExec-// tool can dispatch code execution through this manager without-// knowing which provider is active.-//-// See §17 of docs/develop/agent-go-port-design.md for the decision-// record and the SDK gap that forced an HTTP fallback for the-// aliyun execute path.+// ProviderManager selects the active backend. ManagerClient adapts it to+// tool.SandboxClient without exposing provider details to CodeExec.package sandboximport (@@ -36,9 +27,7 @@ import ("strings")-// ProviderType is the canonical identifier for a sandbox backend. The-// values match the Python-side `sandbox.provider_type` system setting-// and the keys in `agent/sandbox/providers/__init__.py`.+// ProviderType identifies a backend stored in sandbox.provider_type.type ProviderType stringconst (@@ -90,11 +79,7 @@ var ErrE2BProviderNotImplemented = errors.New("ErrCodeExecSandboxMissing pattern in tool.SandboxClient)",)-// ExecutionResult is the wire shape returned by every provider. The-// fields mirror the Python `agent/sandbox/providers/base.py`-// ExecutionResult dataclass so downstream consumers (the CodeExec-// tool, the Message component, rich-content rendering) can pattern-// match unchanged across the two ports.+// ExecutionResult carries streams, exit status, and provider metadata.type ExecutionResult struct {// Stdout is the captured standard output from the sandbox.Stdout string@@ -127,11 +112,7 @@ type SandboxInstance struct {Metadata map[string]any}-// SandboxProvider is the contract every backend must satisfy. The-// shape mirrors `agent/sandbox/providers/base.py` SandboxProvider ABC-// so the Go port's providers are semantically interchangeable with-// the Python ones — same lifecycle, same argument shape, same result-// shape.+// SandboxProvider is the lifecycle and execution contract for each backend.type SandboxProvider interface {// Initialize configures the provider. Returns an error if the// provider is misconfigured or the upstream is unreachable. Thediff --git a/internal/agent/sandbox/result_protocol.go b/internal/agent/sandbox/result_protocol.goindex c388d0e740..514f85e707 100644--- a/internal/agent/sandbox/result_protocol.go+++ b/internal/agent/sandbox/result_protocol.go@@ -14,7 +14,7 @@// limitations under the License.//-// result_protocol.go is the Go port of `agent/sandbox/result_protocol.py`.+// result_protocol.go defines wrappers and result parsing for Go providers.//// The contract://@@ -30,8 +30,8 @@// The marker protocol is a contract with `executor_manager`// (Python FastAPI service that runs the actual code). Renaming the// marker is a wire-format break — `executor_manager` parses for this-// exact prefix. See `agent/sandbox/executor_manager/services/execution.py`-// for the Python side that depends on it.+// exact prefix. The external producer lives in infiniflow/sandbox at+// executor_manager/services/execution.py.package sandbox@@ -43,8 +43,7 @@ import ()// resultMarkerPrefix is the wire-level marker the executor_manager-// Python service scans stdout for. Keep in sync with Python-// `agent/sandbox/result_protocol.py::RESULT_MARKER_PREFIX`.+// service scans stdout for. Preserve this cross-repository wire contract.const resultMarkerPrefix = "__RAGFLOW_RESULT__:"// BuildPythonWrapper wraps a Python source so that:diff --git a/internal/agent/sandbox/self_managed.go b/internal/agent/sandbox/self_managed.goindex 77df728481..08a0ece2c9 100644--- a/internal/agent/sandbox/self_managed.go+++ b/internal/agent/sandbox/self_managed.go@@ -14,19 +14,11 @@// limitations under the License.//-// self_managed.go is the Go port of-// `agent/sandbox/providers/self_managed.py`.+// Self-managed execution calls the external service maintained at+// https://github.com/infiniflow/sandbox. That service owns container lifecycle+// and isolation; this file implements only its HTTP client.//-// The provider wraps the existing executor_manager HTTP API-// (default `http://sandbox-executor-manager:9385`) which manages a-// pool of Docker containers with gVisor for secure code execution.-// We do NOT port the container pool itself — that's the Python-// FastAPI service and stays in Python. We only port the *client*-// surface that the Go CodeExec tool needs to dispatch a code-// execution request.-//-// Wire format (matches the Python `requests.post` call in-// self_managed.py::execute_code):+// Request://// POST {endpoint}/run// Content-Type: application/json@@ -37,7 +29,7 @@// }//// Response (executor_manager's CodeExecutionResult, see-// agent/sandbox/executor_manager/models/schemas.py):+// https://github.com/infiniflow/sandbox/blob/main/executor_manager/models/schemas.py)://// {// "status": "ok" | "PROGRAM_RUNNER_ERROR" | ...,@@ -73,12 +65,11 @@ import ()// selfManagedDefaultEndpoint is the canonical executor_manager-// endpoint baked into the Python side. Operators override via+// endpoint for the optional Compose service. Operators override via// SANDBOX_EXECUTOR_MANAGER_URL.const selfManagedDefaultEndpoint = "http://sandbox-executor-manager:9385"-// SelfManagedProvider is the Go port of-// `agent/sandbox/providers/self_managed.py::SelfManagedProvider`.+// SelfManagedProvider calls the external executor-manager API.type SelfManagedProvider struct {endpoint stringtimeout time.Duration@@ -91,18 +82,13 @@ type SelfManagedProvider struct {// fully-qualified Docker image references. Empty string means// "use the executor_manager's default" — no override.//- // Mirrors the Python side's- // `SANDBOX_BASE_PYTHON_IMAGE` / `SANDBOX_BASE_NODEJS_IMAGE`- // env vars (default: `infiniflow/sandbox-base-python:latest`- // and `infiniflow/sandbox-base-nodejs:latest`). The Go port- // reads the same env vars; operators who customize one- // language's image get a per-language override path that the- // executor_manager can then route at container-create time.+ // Sent as base_image for custom managers; the reference service uses+ // its deployment environment instead of this request field.baseImages map[string]string// apiToken is the shared secret authenticating this RAGFlow// instance towards the executor_manager's /run endpoint- // (Authorization: Bearer). Empty means the executor_manager runs- // without authentication (backwards compatibility).+ // (Authorization: Bearer). Empty omits the header; the service decides+ // whether unauthenticated requests are accepted.apiToken string}@@ -276,7 +262,7 @@ func (p *SelfManagedProvider) ExecuteCode(start := time.Now()// Shared-secret authentication towards the executor_manager; empty- // token keeps the request unauthenticated (backwards compatibility).+ // token omits the header; it does not change service authentication policy.var reqHeaders map[string]stringif p.apiToken != "" {reqHeaders = map[string]string{"Authorization": "Bearer " + p.apiToken}diff --git a/internal/agent/sandbox/ssh.go b/internal/agent/sandbox/ssh.goindex 3449e30678..332c24f2bf 100644--- a/internal/agent/sandbox/ssh.go+++ b/internal/agent/sandbox/ssh.go@@ -14,7 +14,7 @@// limitations under the License.//-// ssh.go is the Go port of `agent/sandbox/providers/ssh.py`.+// SSH execution runs code on a configured remote host.//// SSHProvider runs the user's code on a remote host via SSH. The// Go equivalent of Python's `paramiko` library is@@ -75,8 +75,7 @@ const (sshDefaultWorkDir = "/tmp")-// SSHProvider is the Go port of-// `agent/sandbox/providers/ssh.py::SSHProvider`.+// SSHProvider executes code on a remote host.type SSHProvider struct {host stringport intdiff --git a/internal/agent/sandbox/tenki.go b/internal/agent/sandbox/tenki.goindex 4337cddfc3..fb08e8386c 100644--- a/internal/agent/sandbox/tenki.go+++ b/internal/agent/sandbox/tenki.go@@ -14,8 +14,7 @@// limitations under the License.//-// tenki.go is the Go port of-// `agent/sandbox/providers/tenki.py::TenkiProvider`. It runs each+// Tenki runs each// CodeExec call in a disposable Tenki microVM: CreateInstance// provisions a fresh sandbox, ExecuteCode runs `python3 -c <wrapped>`// or `node -e <wrapped>` inside it, and DestroyInstance terminates it.diff --git a/internal/agent/tool/code_exec.go b/internal/agent/tool/code_exec.goindex 64201bcf4a..fb7bba4c18 100644--- a/internal/agent/tool/code_exec.go+++ b/internal/agent/tool/code_exec.go@@ -35,11 +35,7 @@ import ("go.uber.org/zap")-// ErrCodeExecSandboxMissing is returned when no sandbox client is-// registered. The Python sandbox itself is kept as-is (the Go-// side never reimplemented the sandbox). When a client is-// registered via SetSandboxClient at boot, the tool dispatches-// the execution.+// ErrCodeExecSandboxMissing is returned when no sandbox client is registered.var ErrCodeExecSandboxMissing = errors.New("CodeExec sandbox client not registered — call SetSandboxClient at boot",)@@ -93,9 +89,7 @@ type codeExecResult struct {Attachments []map[string]any `json:"attachments,omitempty"`}-// CodeExecTool is the for the CodeExec tool-// ( . It validates language +-// non-empty code and returns a structured "not-yet-wired" error.+// CodeExecTool validates input and dispatches execution to the sandbox client.type CodeExecTool struct{}// NewCodeExecTool returns a CodeExecTool implementing eino'sdiff --git a/internal/agent/tool/code_exec_client.go b/internal/agent/tool/code_exec_client.goindex 11ef1e8b98..9dce872e58 100644--- a/internal/agent/tool/code_exec_client.go+++ b/internal/agent/tool/code_exec_client.go@@ -14,31 +14,8 @@// limitations under the License.//-// CodeExec sandbox client. The Python sandbox service is kept-// as-is (we do NOT rewrite the sandbox). The Go side has a-// client that talks to the Python sandbox subsystem via the-// internal/agent/sandbox providers.-//-// The Python agent's code_exec delegates to a-// `SandboxProvider` subsystem (agent/sandbox/providers/) with-// three backends: self-managed (Docker + gVisor via local-// executor_manager HTTP), Aliyun Code Interpreter (cloud), and-// e2b (cloud SaaS). A `ProviderManager` selects one at-// startup. The Go side's decision is recorded in-// code_exec_sandbox_design.md:-//-// 1. shell out = spawn a Python subprocess that uses-// ProviderManager to dispatch to whichever provider the-// operator has configured. Reuses all three providers.-// 2. in-process = reimplement all three provider clients in-// Go. No Python dep, but three SDK surfaces to maintain.-//-// Decision: shell out (option A). The interface here is stable —-// when the implementation lands, callers see no change.-//-// Until the proto lands, CodeExecTool.InvokableRun surfaces-// ErrCodeExecSandboxMissing (defined in code_exec.go) so callers-// can detect the no-sandbox state.+// CodeExec dispatches through the Go provider manager in internal/agent/sandbox.+// Self-managed execution uses the external Sandbox executor-manager HTTP API.package toolimport (@@ -46,18 +23,13 @@ import ("sync")-// SandboxClient is the abstract interface for the CodeExec gRPC-// client. Production code calls SetSandboxClient at boot to install-// a real client; the default is a stub returning-// ErrSandboxNotWired.+// SandboxClient dispatches CodeExec requests to the configured provider.+// Production installs a ManagerClient; the default stub reports missing wiring.type SandboxClient interface {ExecuteCode(ctx context.Context, req SandboxRequest) (*SandboxResponse, error)}-// SandboxRequest is the wire shape between the CodeExec tool and-// the sandbox subsystem. Mirrors `agent.sandbox.client.execute_code`'s-// input surface. Arguments and Timeout are optional — the bridge-// applies defaults (no args, 30s timeout) when zero-valued.+// SandboxRequest carries code, arguments, and timeout to the provider adapter.type SandboxRequest struct {Lang string // "python" | "javascript"Script string // the user's codediff --git a/internal/agent/tool/code_exec_sandbox_design.md b/internal/agent/tool/code_exec_sandbox_design.mddeleted file mode 100644index b46d4b03e1..0000000000--- a/internal/agent/tool/code_exec_sandbox_design.md+++ /dev/null@@ -1,188 +0,0 @@-# CodeExec sandbox — Phase 5d design decision--Status: **decision recorded, implementation pending**. This file captures-the trade-offs so the choice can be revisited without re-deriving it.--## Context (what the Python side actually does)--The Python agent's code_exec delegates to a **provider-based-sandbox subsystem** under `agent/sandbox/`. It is NOT a single-SDK and NOT a local subprocess — it is a thin abstraction over-several execution backends.--### Provider interface (`agent/sandbox/providers/base.py`)--```python-class SandboxProvider(ABC):- def initialize(self, config) -> bool- def create_instance(self, template: str) -> SandboxInstance- def execute_code(self, instance_id, code, language,- timeout=10, arguments=None) -> ExecutionResult- def destroy_instance(self, instance_id) -> bool- def health_check(self) -> bool- def get_supported_languages(self) -> List[str]-```--### Providers shipped in the Python repo--| Provider | File | Backend |-|----------|------|---------|-| `SelfManagedProvider` | `self_managed.py` | HTTP at `sandbox-executor-manager:9385` (the `executor_manager`, which runs a Docker pool with gVisor) |-| `AliyunCodeInterpreterProvider` | `aliyun_codeinterpreter.py` | Alibaba Cloud sandbox (uses `agentrun` SDK / Function Compute) |-| `E2BProvider` | `e2b.py` | e2b cloud sandbox (SaaS) |--`ProviderManager` (`manager.py`) selects one provider at startup-based on configuration; the CodeExec tool talks only to the-manager, never to a specific provider.--### Subprocess flow on the Python side--A CodeExec call goes through `agent/sandbox/client.execute_code(...)`-which is the public entry point the CodeExec component uses-(`agent/tools/code_exec.py:365`):--```python-from agent.sandbox.client import execute_code as sandbox_execute_code-result = sandbox_execute_code(- code=code, language=language,- timeout=timeout_seconds, arguments=arguments,-)-```--That function:-1. Resolves the active provider via `ProviderManager` (which reads- `SystemSettingsService.get_by_name("sandbox.provider_type")` —- i.e. the choice is driven by the system admin panel, not the- caller).-2. Calls `provider.create_instance(template=language)` →- `provider.execute_code(...)` → `provider.destroy_instance(...)`.--So the CodeExec component **does** support all three providers —-the provider choice is invisible to it. If the provider system-is not configured, the CodeExec component falls back to a direct-HTTP POST to `http://{SANDBOX_HOST}:9385/run` (the executor_manager-endpoint) for backward compatibility. Both paths land in the-same `_process_execution_result` handler.--## Options for the Go port--### A. Shell out to a Python subprocess--Go spawns `python3 -c "..."` that:-- Imports `agent.sandbox.providers.ProviderManager`-- Picks up the same configuration the Python agent uses-- Returns the ExecutionResult over stdout (JSON)--Pros-: Reuses the full provider surface (self-managed + Aliyun + e2b).- A single Python subprocess call covers all three.-: Plan §2.11.4 ("don't rewrite the sandbox") honored literally.-: Operators that already deploy Python RAGFlow have the- provider configuration in place; Go inherits it for free.--Cons-: Per-call latency = Python interpreter startup + provider import- + dispatch. ~hundreds of ms for the first call, similar for- subsequent calls (no interpreter caching yet).-: Adds a Python dependency on the Go host.-: Pipe / stdout JSON serialisation is awkward for binary output- (matplotlib plots, files written to the sandbox). Can be- mitigated with file-based handoff for large payloads, but adds- operational complexity.--### B. Reimplement the ProviderManager in Go--Read the three provider implementations and write Go equivalents:--- `SelfManagedProvider` → Go HTTP client to `sandbox-executor-manager:9385`- (the executor_manager). Smallest of the three.-- `AliyunCodeInterpreterProvider` → Go reimplementation of the- `agentrun` SDK client. ~Vendor SDK surface to maintain.-- `E2BProvider` → Go reimplementation of the e2b SDK client.--Pros-: No Python dependency on the Go side.-: Lower per-call latency.-: Clean integration with the rest of the Go agent runtime.--Cons-: Three SDK / API surfaces to maintain in parallel with the- Python ones. Every vendor release requires Go updates.-: Plan §2.11.4's intent is to avoid duplicating sandbox logic;- reimplementing three providers arguably violates the spirit- even if it doesn't violate the letter.-: The `agentrun` and `e2b` SDKs include auth, retry, pagination,- and connection management — real ongoing work.--## Decision--**Option A (shell out to a Python subprocess that uses-`ProviderManager`)**. Reasoning:--1. The Python-side flow already supports all three providers via- a single entry point. The Go port's job is the orchestrator +- agent runtime, not duplicating three vendor SDKs.-2. The latency cost is real but acceptable — CodeExec is called- sparingly (a script per LLM turn at most).-3. Plan §2.11.4 commits to NOT rewriting the sandbox. Option B- pushes against that intent; option A doesn't.--The Python subprocess must go through `ProviderManager`, not-directly to any one provider, so configuration stays in one place.-**"Shell out to system python3 directly"** (without the agentrun-SDK or any sandbox) is NOT a valid implementation — it would-execute user-supplied code with the agent process's privileges,-violating the security model.--## Implementation sketch--1. Add a `PythonProviderManagerClient` implementing- `SandboxClient` (`tool/code_exec_client.go`).-2. The subprocess command mirrors the Python CodeExec flow:-- ```go- cmd := exec.CommandContext(ctx, "python3", "-c", `- import json, sys- from agent.sandbox.client import execute_code- result = execute_code(- code=sys.argv[1],- language=sys.argv[2],- timeout=int(sys.argv[3]),- arguments=json.loads(sys.argv[4]) if sys.argv[4] else None,- )- json.dump({- "stdout": result.stdout,- "stderr": result.stderr,- "returned": "", # provider returns stdout; no REPL value- "artifacts": (result.metadata or {}).get("artifacts", []),- }, sys.stdout)- `)- cmd.Args = append(cmd.Args, code, language,- strconv.Itoa(timeout), argsJSON)- ```--3. Parse the JSON response and map to `SandboxResponse`.--4. Add config knobs:- - `code_exec_python_bin` (default `python3`)- - `code_exec_provider_type` (read by Python — let the admin- panel set `sandbox.provider_type` as today)--**Capability parity note**: by going through-`agent.sandbox.client.execute_code`, the Go CodeExec tool inherits-all three providers (self_managed / aliyun_codeinterpreter /-e2b) for the cost of one Python subprocess call. The provider-choice happens inside Python based on `SystemSettingsService`,-invisible to the Go side. This matches what the Python-`agent/tools/code_exec.py` does today (lines 358-381 of that-file).--## What this file is not--This is not an implementation task. It records the agreed-upon-direction so any future contributor (or this file's author, six-months from now) doesn't accidentally land a "shell out to-system python3" stub that bypasses the sandbox. If you find-yourself writing `exec.CommandContext("python3", "-c", ...)`-without going through `ProviderManager`, **stop** — you're-working against the plan and the security model.diff --git a/web/src/pages/agent/form-sheet/next.tsx b/web/src/pages/agent/form-sheet/next.tsxindex 54992ee111..f1dad5c3fb 100644--- a/web/src/pages/agent/form-sheet/next.tsx+++ b/web/src/pages/agent/form-sheet/next.tsx@@ -34,7 +34,7 @@ interface IProps {const EmptyContent = () => <div></div>;const SandboxQuickstartUrl =- 'https://github.com/infiniflow/ragflow/blob/main/docs/guides/agent/agent_quickstarts/sandbox_quickstart.md';+ 'https://github.com/infiniflow/ragflow/blob/main/docs/administrator/configurations/sandbox_quickstart.md';const openSandboxQuickstart: MouseEventHandler<HTMLButtonElement> = (e) => {e.stopPropagation();