Skip to content

RAGFlow is an agent-native database: a Retrieval-Augmented Generation (RAG) engine that grew into context infrastructure.

docs(sandbox): correct external deployment guidance (#20810)

Sbaaoui Idrisscb3dc4047e38
diff --git a/docker/.env b/docker/.env
index 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.yml
index 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.md
index 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 Configuration
diff --git a/docs/administrator/configurations/sandbox_quickstart.md b/docs/administrator/configurations/sandbox_quickstart.md
index 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.md
index 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 Component
The 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.go
index 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 string
accessKeySecret string
diff --git a/internal/agent/sandbox/artifacts.go b/internal/agent/sandbox/artifacts.go
index 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 Local
diff --git a/internal/agent/sandbox/e2b.go b/internal/agent/sandbox/e2b.go
index 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.Client
template string
diff --git a/internal/agent/sandbox/local.go b/internal/agent/sandbox/local.go
index 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 string
nodeBin string
diff --git a/internal/agent/sandbox/manager.go b/internal/agent/sandbox/manager.go
index 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.Mutex
mu 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 *ProviderManager
globalManagerOnce sync.Once
@@ -216,10 +209,7 @@ func (m *ProviderManager) LoadFromSettingsWithReader(ctx context.Context, db *go
return 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.go
index 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 sandbox
import (
@@ -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 string
const (
@@ -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. The
diff --git a/internal/agent/sandbox/result_protocol.go b/internal/agent/sandbox/result_protocol.go
index 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.go
index 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 string
timeout 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]string
if p.apiToken != "" {
reqHeaders = map[string]string{"Authorization": "Bearer " + p.apiToken}
diff --git a/internal/agent/sandbox/ssh.go b/internal/agent/sandbox/ssh.go
index 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 string
port int
diff --git a/internal/agent/sandbox/tenki.go b/internal/agent/sandbox/tenki.go
index 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.go
index 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's
diff --git a/internal/agent/tool/code_exec_client.go b/internal/agent/tool/code_exec_client.go
index 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 tool
import (
@@ -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 code
diff --git a/internal/agent/tool/code_exec_sandbox_design.md b/internal/agent/tool/code_exec_sandbox_design.md
deleted file mode 100644
index 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.tsx
index 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();