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: unify sandbox docs (#20951)
YanZhang95f90203803e
diff --git a/docs/administrator/admin/admin_ui/configure_code_execution_sandbox.md b/docs/administrator/admin/admin_ui/configure_code_execution_sandbox.mdindex 8baf005eab..5f38ad7e5a 100644--- a/docs/administrator/admin/admin_ui/configure_code_execution_sandbox.md+++ b/docs/administrator/admin/admin_ui/configure_code_execution_sandbox.md@@ -6,152 +6,44 @@ title: Configure Code Execution Sandbox# Configure Code Execution Sandbox-## Select a Sandbox Provider+Administrators configure the active code execution provider in **Admin > Sandbox Settings**. For provider selection, deployment, security, and troubleshooting guidance, start with [Code Execution Sandbox](../../sandbox/overview.md).-If your organization uses the **Code** component in Agent, administrators must configure the code execution sandbox in **Sandbox settings**.+:::caution System-wide setting+Saving a provider makes it active for subsequent Code component runs across this RAGFlow deployment. Test the configuration before replacing a provider that is already in use.+:::-The current page supports the following `Provider` options:+## Select a provider-| Provider | Description |-| --- | --- |-| `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. |-| `UCloud Agent Sandbox` | Run code in disposable UCloud cloud sandboxes. |--After selecting a `Provider`, the page displays the corresponding configuration area.--**Caution:** Sandbox configuration affects not only connection availability, but also code isolation, network access, file access, and runtime resource limits. In production environments, use `Self-Managed`, cloud, or independent remote execution solutions with isolation capabilities.--| Provider | Applicable scenario | Main characteristics | Recommendation |-| --- | --- | --- | --- |-| `Self-Managed` | Enterprise intranet and private deployment | Uses a self-managed sandbox service to execute code. Data and runtime environments can be controlled independently. | Suitable for production environments and scenarios with high data security requirements. |-| `SSH` | Existing independent execution servers | Executes code on a remote host through SSH. | Suitable for reusing existing servers or custom runtime environments. |-| `AliyunCodeInterpreter` | Alibaba Cloud-related services | Uses a cloud service to provide the code execution environment, making elastic scaling easier. | Suitable for organizations already using the corresponding cloud service. |-| `E2B` | Fast access to a cloud sandbox | Executes code in an isolated environment provided by E2B. | Suitable for scenarios that need quick use without deployment. |-| `UCloud Agent Sandbox` | UCloud-hosted agent workloads | Creates a disposable sandbox from a template containing Python and Node.js. | Suitable for teams using UCloud or needing managed sandboxes in China or North America. |--## Test and Save Configuration--When configuring a sandbox, first fill in the connection information and runtime parameters required by the selected `Provider`, then use **Test connection** to verify availability. After the test succeeds, click **Save**.--## Self-Managed Configuration--`Self-Managed` configuration connects to a deployed `SandboxExecutorManager` service for remote sandbox execution. If the code execution service is deployed on an independent server or in a container, complete this configuration.--1. Go to **Self-Managed Configuration**.-2. Configure the code execution service connection information.-3. Click **Test connection** to test whether the connection is normal.-4. After the test succeeds, click **Save**.--| 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.--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--`SSH` configuration connects to a remote Linux host and executes Python or Node.js code on the remote server. After configuration, the system logs in to the specified server through SSH and executes code in the remote working directory.--1. Go to **System management > Model service > SSH Configuration**.-2. Fill in the remote server connection information.-3. Select the authentication method: password authentication or private-key authentication.-4. Configure the remote code runtime environment.-5. Click **Test connection** to test whether the connection is normal.-6. After the test succeeds, click **Save**.+The page supports:-### SSH Connection Configuration--| Parameter | Description | Recommendation |-| --- | --- | --- |-| `SSH Host` | Remote server IP address or host name. | For example, `192.168.1.10` or `server.example.com`. |-| `SSH Username` | User name used to log in to the remote server. | Enter a user with code execution permissions, such as `root`, `ubuntu`, or `ragflow`. |-| `SSH Port` | Port on which the SSH service listens. | The default is `22`. If the server uses another SSH port, enter the actual port. |--### Authentication--The system supports `Password` and `PrivateKey` authentication.--| Authentication method | Description | Recommendation |-| --- | --- | --- |-| `Password` | Uses the SSH user password for authentication. | Fill in `SSH Password`. |-| `PrivateKey` | Uses an SSH private key for authentication. | Fill in the SSH private key content. If the private key has a password, also fill in the corresponding `Passphrase`. Private-key authentication is recommended in production. |--### Execution--| Parameter | Description | Recommendation |-| --- | --- | --- |-| `Remote Workspace Root` | Working directory on the remote server for temporary files generated during code runs. | Configure a directory with read and write permissions, such as `/tmp` or `/home/ragflow/workspace`. |-| `Python Binary` | Python executable name or full path. | Usually `python3`. If using a virtual environment, enter the full Python path. |-| `Node.js Binary` | Node.js executable name or full path. | Usually `node`. If installed elsewhere, enter the full path. |-| `Max Artifact Bytes` | Maximum allowed size for a single generated file. | Keep the default or adjust according to business needs. |-| `Max Artifacts` | Maximum number of files allowed in one run. | Keep the default configuration. |-| `Max Output Bytes` | Maximum size of console output. | Keep the default. Output exceeding the limit is truncated. |-| `Timeout (seconds)` | Maximum runtime for a single code execution. | The default is 30 seconds. Increase it when execution takes longer. |--Make sure the remote server has SSH enabled and allows the current user to log in. The configured user must have read and write permissions on the remote working directory and be able to execute the configured Python and Node.js binaries. When using private-key authentication, make sure the private key matches the server configuration.--## Alibaba Cloud CodeInterpreter Configuration--Alibaba Cloud `CodeInterpreter` configuration connects to Alibaba Cloud CodeInterpreter. The system executes code tasks through this service.--1. Go to **AliyunCodeInterpreter Configuration**.-2. Fill in the connection information for Alibaba Cloud CodeInterpreter.-3. Click **Test connection** to test whether the connection is normal.-4. After the test succeeds, click **Save**.--| Parameter | Description | Recommendation |-| --- | --- | --- |-| `AccessKeyID` | Alibaba Cloud account `AccessKeyID` for authentication. | Enter an `AccessKeyID` with access to the CodeInterpreter service. |-| `AccessKeySecret` | Secret corresponding to `AccessKeyID`. | Enter the corresponding `AccessKeySecret` and keep it secure to avoid leakage. |-| `AccountID` | Alibaba Cloud account ID. | Enter the current Alibaba Cloud account ID. |-| `Region` | Region where the CodeInterpreter service is located. | Enter the actual deployment region, such as `cn-hangzhou`. |-| `TemplateName` | Template name used by CodeInterpreter. | Enter the created template name, such as `my-interpreter`. |-| `ExecutionTimeout (seconds)` | Maximum runtime allowed for a single code execution. | The default is 30 seconds. Adjust according to business needs. |--## E2B Configuration--`E2B` configuration connects to the E2B Cloud code execution service. After configuration, the system executes code tasks through the E2B cloud sandbox.+| Provider | Detailed instructions |+| --- | --- |+| **Self-Managed** | [Quickstart with Self-Managed](../../sandbox/quickstart_with_self_managed.md) |+| **SSH** | [Configure SSH](../../sandbox/configure_ssh_and_cloud_providers.md#configure-ssh) |+| **Aliyun Code Interpreter** | [Configure Aliyun Code Interpreter](../../sandbox/configure_ssh_and_cloud_providers.md#configure-aliyun-code-interpreter) |+| **E2B** | [Configure E2B](../../sandbox/configure_ssh_and_cloud_providers.md#configure-e2b) |+| **Tenki** | [Configure Tenki](../../sandbox/configure_ssh_and_cloud_providers.md#configure-tenki) |+| **UCloud Agent Sandbox** | [Configure UCloud Agent Sandbox](../../sandbox/configure_ssh_and_cloud_providers.md#configure-ucloud-agent-sandbox) |-1. Go to **E2B**.-2. Fill in the E2B service connection information.-3. Click **Test connection** to test whether the connection is normal.-4. After the test succeeds, click **Save**.+## Test and save the configuration-| Parameter | Description | Recommendation |-| --- | --- | --- |-| `API Key` | API key provided by E2B Cloud for authentication. | Log in to the E2B platform, create the corresponding API key, and enter it. |-| `Region` | Region where the E2B service is located. | Enter the actual region, such as `us`. |-| `Request Timeout (seconds)` | Timeout for requests to the E2B service. | The default is 30 seconds. Increase it if the network is slow or execution takes longer. |+1. Select a provider and complete its fields.+2. Select **Test connection**. The test uses the values currently shown in the form and does not save them.+3. Confirm that the result shows `PASSED`.+4. Select **Save** to make the provider active.-## UCloud Agent Sandbox Configuration+The connection test runs a small Python program. For Self-Managed, this verifies that Executor Manager can start a Python Runner; `/healthz` alone is not sufficient. Cloud tests may consume account quota or incur short-lived charges.-`UCloud Agent Sandbox` creates a fresh cloud sandbox for each code execution and destroys it when execution finishes. RAGFlow uses UCloud's native SDK and supports Python and JavaScript with the built-in `base` template.+## Self-Managed fields-1. Obtain an API key from [UCloud ModelVerse API Keys](https://astraflow.ucloud.cn/modelverse/api-keys).-2. Go to **UCloud Agent Sandbox Configuration**.-3. Enter the API key and select the desired region.-4. Click **Test connection**, then click **Save** after the test succeeds.+The Admin page configures only the connection from RAGFlow to Executor Manager:-| Parameter | Description | Recommendation |-| --- | --- | --- |-| `API Key` | UCloud Agent Sandbox API key used for authentication. | Keep it secret and rotate it according to your organization's credential policy. |-| `Region` | Sandbox region. Supported values include `cn-wlcb` and `us-ca`. | Keep `cn-wlcb` unless workloads should run in North America. |-| `Domain` | Optional sandbox domain override. | Leave empty to derive `<region>.sandbox.ucloudai.com` from `Region`. |-| `API URL` | Optional control-plane endpoint override. | Leave empty for the public service endpoint. |-| `Template` | UCloud sandbox template. | Use `base`, which includes both Python and Node.js. |-| `Allow Internet Access` | Allows executed code to make outbound network requests. | Disabled by default. Enable only when the code needs external services or package downloads. |-| `Use Insecure HTTP` | Uses HTTP rather than HTTPS. | Keep disabled except in a trusted private test deployment. |-| `Execution Timeout` | Maximum duration of one code execution. | The default is 30 seconds. |-| `Sandbox Lifetime` | Maximum lifetime of the disposable sandbox. | The default is 300 seconds and is extended when needed for an allowed execution. |-| Output and artifact limits | Bound console output and files returned from `artifacts/`. | Keep the defaults unless the workload has a known need for larger results. |+| Field | Purpose |+| --- | --- |+| **Executor Manager Endpoint** | Manager address reachable from the RAGFlow process or container. |+| **Executor Manager API Token** | Shared token that must match `SANDBOX_EXECUTOR_MANAGER_API_TOKEN` on the Manager. |+| **Request Timeout (seconds)** | Maximum time RAGFlow waits for one Manager request. |-Files written under the execution workspace's `artifacts/` directory are returned to RAGFlow. Supported artifact extensions are `.csv`, `.html`, `.jpeg`, `.jpg`, `.json`, `.pdf`, `.png`, and `.svg`.+Runner images, capacity, memory, service timeout, and network access are deployment settings. Manage them through [Manage Self-Managed Sandbox](../../sandbox/manage_self_managed_sandbox.md).-See the [UCloud Agent Sandbox prerequisites](https://astraflow.ucloud.cn/docs/agent-sandbox/product/prerequisites) and [region documentation](https://astraflow.ucloud.cn/docs/agent-sandbox/product/region) for service-side details.+If a connection or execution test fails, see the [Code Execution Sandbox FAQ](../../sandbox/faq.md).diff --git a/docs/administrator/configurations/sandbox_quickstart.md b/docs/administrator/configurations/sandbox_quickstart.mddeleted file mode 100644index e2292f3aeb..0000000000--- a/docs/administrator/configurations/sandbox_quickstart.md+++ /dev/null@@ -1,106 +0,0 @@-----sidebar_position: 2-title: Sandbox Quickstart-sidebar_label: Sandbox Quickstart-slug: /sandbox_quickstart-sidebar_custom_props: {- categoryIcon: LucideCog-}-----# 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.-- `ssh`: Runs code on a remote machine over SSH.-- `aliyun_codeinterpreter`, `e2b`, and `tenki`: Cloud providers.--## Provider options--RAGFlow supports multiple sandbox providers. Configure the active provider in Admin > Sandbox Settings after the services are up.--- `self_managed`: Runs code inside Docker-managed sandbox containers. This is the default provider.-- `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 afterward. It is cloud-hosted, so it needs no local sandbox services, gVisor, or Docker base images — only outbound network access and an API key.--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.--## Self-managed architecture--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.--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.--## Connect RAGFlow to an external sandbox--In **Admin > Sandbox Settings**, select `self_managed` and configure:--| 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. |--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.--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.--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.--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.--## Optional published-image deployment with RAGFlow--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.--In `docker/.env`:--- 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.--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.--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.--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.--Admin schema values are not a readback of the external service's deployed configuration. Saving connection settings does not restart or reconfigure that service.--## RAGFlow artifact storage--`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.--## Other providers--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/administrator/sandbox/_category_.json b/docs/administrator/sandbox/_category_.jsonnew file mode 100644index 0000000000..b69ec552c8--- /dev/null+++ b/docs/administrator/sandbox/_category_.json@@ -0,0 +1,8 @@+{+ "label": "Code Execution Sandbox",+ "position": 1,+ "link": {+ "type": "doc",+ "id": "administrator/sandbox/overview"+ }+}diff --git a/docs/administrator/sandbox/configure_ssh_and_cloud_providers.md b/docs/administrator/sandbox/configure_ssh_and_cloud_providers.mdnew file mode 100644index 0000000000..688ca5c8e6--- /dev/null+++ b/docs/administrator/sandbox/configure_ssh_and_cloud_providers.md@@ -0,0 +1,276 @@+---+sidebar_position: 3+title: Configure SSH and Cloud Providers+sidebar_label: Configure SSH and Cloud Providers+slug: /configure_ssh_and_cloud_sandbox_providers+---++# Configure SSH and Cloud Providers++Use this guide to connect RAGFlow to an existing SSH host or a managed cloud sandbox. These providers do not require the Self-Managed Sandbox Executor Manager.++:::caution Provider changes are system-wide+Saving a provider configuration makes it the active code execution provider for this RAGFlow deployment. Test the new configuration before replacing a provider that is already in use.+:::++## Configuration workflow++Use the same workflow for every provider:++1. Prepare the remote host or cloud account, credentials, and network access.+2. Open **Admin > Sandbox Settings**.+3. Select the provider and complete its settings.+4. Select **Test connection**.+5. Confirm that the result shows `PASSED`, then select **Save**.+6. Run the test in [Verify code execution](#verify-code-execution).++:::note+**Test connection** uses the values currently entered in the form; you do not need to save them first. The test creates a temporary Python execution environment, runs a small diagnostic, and then attempts to clean up the environment. Cloud providers may consume account quota or incur short-lived charges during this test.++A cleanup failure is written to the RAGFlow logs and may not change a successful test result. Check the provider console for leftover resources if the logs report a cleanup failure.+:::++## Configure SSH++The SSH provider runs code on a Linux host that you operate. RAGFlow connects to the host for each execution, creates a temporary workspace, uploads and runs the script, collects generated artifacts, and removes the workspace.++:::caution SSH does not provide strong isolation+Code runs with the permissions of the configured SSH user. Use a dedicated execution host and a low-privilege account, and restrict its filesystem and network access. Do not run untrusted code as `root` or on a server that hosts production workloads.+:::++### Before you begin++Make sure that:++- RAGFlow can reach the SSH host and port.+- The SSH service accepts either password or private-key authentication for the selected user.+- The user can create directories and files under the configured workspace root.+- Python 3 is installed and available through the configured **Python Binary**. The connection test requires Python.+- Node.js is installed and available through the configured **Node.js Binary** if users will run JavaScript.+- The SSH server's host key has been verified and added to a trusted `known_hosts` file.++### Prepare the SSH `known_hosts` file++RAGFlow verifies the SSH server's host key before sending credentials or running code. Confirm the server's host-key fingerprint with the server administrator, then add the verified key to the `known_hosts` file used by RAGFlow.++For a server that listens on a non-default port, include the port when collecting the key. Replace `SSH_HOST` and `SSH_PORT` with the values configured in **Admin > Sandbox Settings**. For example, if the actual host is `sandbox.example.com` and the port is `2222`, use `[sandbox.example.com]:2222`.++The `[SSH_HOST]:SSH_PORT` format is for non-default ports. For port `22`, use `SSH_HOST` without brackets or a port in the `ssh-keygen -F` and `ssh-keygen -R` commands.++First, create a unique temporary file and save the key to it:++```bash+ssh_key_file=$(mktemp /tmp/ragflow-ssh-host-key.XXXXXX)+trap 'rm -f "$ssh_key_file"' EXIT+ssh-keyscan -p SSH_PORT SSH_HOST > "$ssh_key_file"+```++Continue the following commands in the same terminal session so that `ssh_key_file` remains available. `mktemp` avoids overwriting another administrator's scan and prevents the command from following a predictable file name prepared by another local user.++Display the scanned fingerprints:++```bash+ssh-keygen -lf "$ssh_key_file"+```++`ssh-keyscan` may return more than one host-key type. Compare every fingerprint shown with the fingerprints supplied by the server administrator. Continue only if every key in the temporary file is verified.++If the same host and port already have an entry, inspect it first:++```bash+ssh-keygen -F '[SSH_HOST]:SSH_PORT' -f ~/.ssh/known_hosts+```++After confirming that the verified new keys are legitimate replacements, remove the old entry before appending them:++```bash+ssh-keygen -R '[SSH_HOST]:SSH_PORT' -f ~/.ssh/known_hosts+```++Add the verified keys:++```bash+mkdir -p ~/.ssh+chmod 700 ~/.ssh+cat "$ssh_key_file" >> ~/.ssh/known_hosts+chmod 600 ~/.ssh/known_hosts+rm -f "$ssh_key_file"+trap - EXIT+```++For port `22`, the entry identifies the server as `SSH_HOST`. For a non-default port, it uses `[SSH_HOST]:SSH_PORT`. Never add a host key that has not been independently verified.++#### Docker deployment++Set the following values in `docker/.env`:++```dotenv+RAGFLOW_SSH_KNOWN_HOSTS=${HOME}/.ssh/known_hosts+SSH_KNOWN_HOSTS=/etc/ragflow/ssh_known_hosts+```++The variables refer to different locations:++- `RAGFLOW_SSH_KNOWN_HOSTS` is the `known_hosts` file on the Docker host.+- `SSH_KNOWN_HOSTS` is the path at which RAGFlow reads that file inside its container.++In `docker/docker-compose.yml`, uncomment the following volume mount for the RAGFlow service:++```yaml+- ${RAGFLOW_SSH_KNOWN_HOSTS:-${HOME}/.ssh/known_hosts}:${SSH_KNOWN_HOSTS:-/etc/ragflow/ssh_known_hosts}:ro+```++Make sure the host file exists, then apply the changes to RAGFlow:++```bash+cd docker+docker compose up -d ragflow-cpu+```++In **SSH known_hosts File**, enter the container path: `/etc/ragflow/ssh_known_hosts`.++#### Source deployment++When RAGFlow runs from source, it checks the `~/.ssh/known_hosts` file of the operating-system user running RAGFlow. To use another file, set `SSH_KNOWN_HOSTS` to its path before starting RAGFlow. `RAGFLOW_SSH_KNOWN_HOSTS` is only used by Docker Compose and is not required for a source deployment.++In **SSH known_hosts File**, enter the path that is visible to the RAGFlow process.++### Configure the connection++In **Admin > Sandbox Settings**, select **SSH** and configure:++| Setting | Required | Value |+| --- | --- | --- |+| **SSH Host** | Yes | Hostname or IP address of the remote execution server. Do not include a URL scheme or port. |+| **SSH Port** | Yes | SSH port. The default is `22`. |+| **SSH Username** | Yes | Remote user that will run the code. |+| **SSH known_hosts File** | No | Path to an OpenSSH-format `known_hosts` file visible to the RAGFlow process or container. When empty, RAGFlow uses the running user's `~/.ssh/known_hosts`. Unknown host keys are rejected. |++### Choose an authentication method++Configure one of the following methods:++| Method | Settings |+| --- | --- |+| Password | Enter **SSH Password**. |+| Private key | Paste the PEM-formatted key into **SSH Private Key**, or enter a private-key file path that is readable by the RAGFlow process. If the key is encrypted, also enter **Private Key Passphrase**. |++Private-key authentication is recommended for production. Do not configure both methods; selecting one method in the Admin UI clears fields belonging to the other.++For a Docker deployment, pasting the PEM content is the simplest option. A private-key path must refer to a file inside the RAGFlow container, not an unmounted path on the Docker host. If you use a path, mount the key into the RAGFlow service as a read-only file and enter its container path in **SSH Private Key**.++### Configure the execution environment++The defaults are appropriate for an initial test:++| Setting | Default | Description |+| --- | --- | --- |+| **Python Binary** | `python3` | Python executable name or absolute path on the SSH host. |+| **Node.js Binary** | `node` | Node.js executable name or absolute path on the SSH host. |+| **Remote Workspace Root** | `/tmp` | Writable directory under which RAGFlow creates a temporary workspace for each execution. |+| **Timeout (seconds)** | `30` | Maximum SSH execution time for one run. Range: 1–600 seconds. |+| **Max Output Bytes** | `1048576` | Maximum combined stdout and stderr size. |+| **Max Artifacts** | `20` | Maximum number of files collected from the execution's `artifacts/` directory. |+| **Max Artifact Bytes** | `10485760` | Maximum size of one artifact file. |++Select **Test connection**. Confirm that the result shows `PASSED`, then select **Save**. If the test returns `knownhosts: key is unknown`, see [Why does SSH return `knownhosts: key is unknown`?](./faq.md#why-does-ssh-return-knownhosts-key-is-unknown).++## Configure Aliyun Code Interpreter++Prepare a RAM user with Code Interpreter permissions and [create an Alibaba Cloud AccessKey pair](https://help.aliyun.com/en/ram/user-guide/create-an-accesskey-pair). Then select **Aliyun Code Interpreter** in **Admin > Sandbox Settings** and configure:++| Setting | Required | Default | Description |+| --- | --- | --- | --- |+| **Access Key ID** | Yes | — | Alibaba Cloud AccessKey ID. |+| **Access Key Secret** | Yes | — | Secret associated with the AccessKey ID. |+| **Account ID** | Yes | — | Alibaba Cloud primary account ID used for API requests. |+| **Region** | No | `cn-hangzhou` | Code Interpreter region. The UI also supports `cn-beijing`, `cn-shanghai`, `cn-shenzhen`, and `cn-guangzhou`. |+| **Template Name** | No | — | Existing Code Interpreter template. When empty, RAGFlow uses a language-specific default template and creates it if it does not exist. |+| **Execution Timeout (seconds)** | No | `30` | Maximum execution time. Alibaba Cloud limits this value to 30 seconds. |++## Configure E2B++Create an API key in the [E2B dashboard](https://e2b.dev/dashboard). Then select **E2B** in **Admin > Sandbox Settings** and configure:++| Setting | Required | Default | Description |+| --- | --- | --- | --- |+| **API Key** | Yes | — | E2B API key, normally beginning with `e2b_sk_`. |+| **Region** | No | `us` | E2B service region. `us` works with the Admin settings alone. Using `eu` also requires `E2B_DOMAIN` in the RAGFlow runtime environment. |+| **Request Timeout (seconds)** | No | `30` | Maximum time RAGFlow waits for an E2B request. Range: 5–300 seconds. |++For the `eu` region, obtain the domain from E2B. For Docker deployments, set `E2B_DOMAIN` in `docker/.env`, then apply the change from the RAGFlow repository root:++```bash+cd docker+docker compose up -d ragflow-cpu+```++For source deployments, set `E2B_DOMAIN` in the RAGFlow process environment and restart RAGFlow. This value is not configured in Admin.++## Configure Tenki++Create an API key in the [Tenki console](https://app.tenki.cloud). For provider setup, see the [Tenki Sandbox Quickstart](https://tenki.cloud/docs/sandbox/quickstart). Then select **Tenki** in **Admin > Sandbox Settings** and configure:++| Setting | Required | Default | Description |+| --- | --- | --- | --- |+| **API Key** | Yes | — | Normally begins with `tk_`. |+| **API Endpoint** | No | Tenki default | Override the Tenki API endpoint. Leave empty for the hosted service. |+| **Sandbox Image** | No | Tenki default | Custom images must include the required runtime. |+| **Allow Outbound Network** | No | Disabled | Enable only when required. |+| **Timeout (seconds)** | No | `30` | Range: 1–600. |+| **Max Sandbox Lifetime (seconds)** | No | `3600` | Range: 60–86400. |+| **vCPU Cores** | No | `0` | `0` uses the provider default; maximum: 16. |+| **Memory (MB)** | No | `0` | `0` uses the provider default. |+| **Disk Size (GB)** | No | `0` | `0` uses the provider default; maximum: 100. |+| **Max Output Bytes** | No | `1048576` | Combined stdout and stderr. |+| **Max Artifacts** | No | `20` | Number of returned files. |+| **Max Artifact Bytes** | No | `10485760` | Per returned file. |++Keep outbound networking disabled unless executed code requires it.++## Configure UCloud Agent Sandbox++Obtain an API key from [UCloud ModelVerse API Keys](https://astraflow.ucloud.cn/modelverse/api-keys). Then select **UCloud Agent Sandbox** in **Admin > Sandbox Settings** and configure:++| Setting | Required | Default | Description |+| --- | --- | --- | --- |+| **API Key** | Yes | — | UCloud Agent Sandbox API key. |+| **Region** | No | `cn-wlcb` | For example, `cn-wlcb` or `us-ca`. |+| **Domain** | No | Derived from Region | Override only when required. |+| **API URL** | No | Public service endpoint | Override only when required. |+| **Template** | No | `base` | The default includes Python and Node.js. |+| **Allow Internet Access** | No | Disabled | Enable only when required. |+| **Use Insecure HTTP** | No | Disabled | Use only in a trusted private environment. |+| **Execution Timeout (seconds)** | No | `30` | Range: 1–600. |+| **Sandbox Lifetime (seconds)** | No | `300` | Range: 60–86400. |+| **Max Output Bytes** | No | `1048576` | Combined stdout and stderr. |+| **Max Artifacts** | No | `20` | Number of returned files. |+| **Max Artifact Bytes** | No | `10485760` | Per returned file. |++Keep internet access and insecure HTTP disabled unless required.++## Verify code execution++After saving the provider:++1. Create or open an Agent.+2. Add a **Code** component.+3. Set the language to Python.+4. Run the following code:++```python+def main():+ return "Sandbox is ready"+```++5. Confirm that the result is:++```text+Sandbox is ready+```++This verifies the complete path from RAGFlow to the selected provider. **Test connection** uses Python, so run a separate JavaScript Code component if JavaScript support is required.++When replacing a provider that is already in use, also test representative existing Agents. Confirm that their required packages, outbound network access, execution time, and artifact handling work in the new environment.++If the test fails, see the [Code Execution Sandbox FAQ](./faq.md). For SSH, also verify the host key, authentication method, remote workspace permissions, and runtime paths. For cloud providers, verify credentials, region availability, account quota, and outbound network access from the RAGFlow server.diff --git a/docs/administrator/sandbox/faq.md b/docs/administrator/sandbox/faq.mdnew file mode 100644index 0000000000..fe9b2e4e64--- /dev/null+++ b/docs/administrator/sandbox/faq.md@@ -0,0 +1,201 @@+---+sidebar_position: 5+title: Code Execution Sandbox FAQ+sidebar_label: FAQ+slug: /sandbox_faq+---++# Code Execution Sandbox FAQ++## Provider selection and configuration++### Which provider should I choose?++- Choose **Self-Managed** to run Docker-managed Runners in infrastructure you control.+- Choose **SSH** to reuse a dedicated Linux execution host with a custom runtime.+- Choose **Aliyun Code Interpreter**, **E2B**, **Tenki**, or **UCloud Agent Sandbox** when a managed cloud execution environment fits your region, security, and operational requirements.++See [Choose a sandbox provider](./overview.md#choose-a-sandbox-provider) for a comparison and links to each setup guide.++### Does Test connection save the configuration?++No. **Test connection** uses the values currently entered in the form without changing the active provider. After the result shows `PASSED`, select **Save** to activate the configuration.++Cloud connection tests create a temporary execution environment and may consume quota or incur short-lived charges. RAGFlow attempts to remove the environment afterward; cleanup failures are written to the RAGFlow logs.++### When does a newly saved provider become active?++The saved provider is used for subsequent Code component executions across the RAGFlow deployment. A run that is already in progress continues with the provider configuration it started with. Test representative existing Agents after changing the provider.++## Self-Managed startup and connection++### Why did `sandbox-executor-manager` not start?++From the repository's `docker` directory, check its state and logs:++If RAGFlow uses custom Compose options, use the same options in every command below.++```bash+docker compose ps --all sandbox-executor-manager+docker compose logs --tail=200 sandbox-executor-manager+```++Common causes include:++- The service was not explicitly started and `sandbox` is missing from `COMPOSE_PROFILES`.+- The deployment account cannot access the Docker daemon.+- Docker cannot pull the Manager or Runner images.+- The host cannot run privileged containers or expose `/var/run/docker.sock` to the Manager.+- Port `9385`, or the configured `SANDBOX_EXECUTOR_MANAGER_PORT`, is already in use.+- A deployment value in `docker/.env` is invalid.++After correcting the problem, apply the changes:++```bash+docker compose up -d sandbox-executor-manager+```++If Docker reports `permission denied` for `/var/run/docker.sock`, verify access with `docker info`. Run the deployment with an account authorized to manage Docker, or configure access according to the host-security policy. Docker daemon access is root-equivalent and should be restricted to trusted administrators.++### Which endpoint should Docker and source deployments use?++| RAGFlow location | Executor Manager location | Endpoint |+| --- | --- | --- |+| RAGFlow container in the supplied Compose project | Same Compose project | `http://sandbox-executor-manager:9385` |+| RAGFlow source process on the Docker host | Manager container on the same host | `http://127.0.0.1:9385` |+| RAGFlow and Manager on different hosts | Protected remote endpoint | A private or protected HTTPS address reachable from RAGFlow |++An endpoint is resolved from the RAGFlow process or container. Inside a container, `127.0.0.1` refers to that container and cannot reach another container.++### Why does the connection return an error?++| Error | Likely cause | What to check |+| --- | --- | --- |+| `Connection refused` | Nothing is listening at the address and port. | Manager state, published port, and endpoint. |+| DNS or `no such host` | The service name cannot be resolved from the RAGFlow network. | Compose project and network membership; do not use the Compose service name from an unrelated host. |+| Timeout | A firewall, route, proxy, or overloaded service prevented a timely response. | Connectivity from the RAGFlow container or process, Manager logs, and request timeout. |+| `401 Unauthorized` | The Admin token does not match the Manager token. | `SANDBOX_EXECUTOR_MANAGER_API_TOKEN` on the Manager and **Executor Manager API Token** in Admin. |+| `503 Service Unavailable` | Executor Manager may not have an API token configured. | Set `SANDBOX_EXECUTOR_MANAGER_API_TOKEN`, restart the Manager, and enter the same token in Admin. |++When testing connectivity, run the check from the same host or container network where RAGFlow runs.++### Why does the health check succeed while Code execution fails?++`/healthz` only shows that Executor Manager is responding. It does not prove that the Manager can authenticate a `/run` request, access Docker, start the selected Runner image, execute code, or return artifacts.++Run **Test connection** in Admin. It starts a Python Runner and executes a diagnostic. If it fails, inspect Manager logs and verify the token, Docker socket, Runner images, resource limits, and execution timeout.++## Self-Managed execution++### Why did a Runner image fail to start?++Check that the configured image exists, supports the host architecture, and is accessible to the Docker daemon used by Executor Manager:++```bash+docker pull infiniflow/sandbox-base-python:latest+docker pull infiniflow/sandbox-base-nodejs:latest+```++If custom image variables are set, pull those exact tags instead. Then apply the changes to Executor Manager. Also verify available disk space, memory, Docker socket access, and Manager–Runner version compatibility.++### Why is the Docker API version incompatible?++Executor Manager communicates with the host Docker daemon through `/var/run/docker.sock`. An error stating that a client API version is too old or unsupported indicates that the Manager image's Docker client and the host daemon do not support a common API version.++Pull a current, tested Executor Manager image or use a Docker daemon version supported by that image. Do not work around the error by setting an arbitrary API version without confirming compatibility. Record the Manager image tag and Docker server version when reporting the issue.++### Why did execution exceed the memory or timeout limit?++Self-Managed execution has separate limits:++- The Code request can specify an execution timeout.+- `SANDBOX_TIMEOUT` limits execution on Executor Manager.+- **Request Timeout (seconds)** limits how long RAGFlow waits for the HTTP response.+- `SANDBOX_MAX_MEMORY` limits Runner memory.++The shortest applicable timeout ends the request first. Increase limits only after confirming that the workload is expected and that the host has sufficient resources. Apply the changes after updating Compose deployment values.++### Why can executed code not access the internet?++The supplied deployment uses `SANDBOX_CONTAINER_NETWORK=none` by default. This is an intentional security control.++Prefer adding required dependencies to a trusted Runner image. If outbound access is necessary, use a controlled Docker network and apply egress restrictions before changing `SANDBOX_CONTAINER_NETWORK`. See [Manage Runner network access](./manage_self_managed_sandbox.md#manage-runner-network-access).++## SSH++### Why does SSH return `knownhosts: key is unknown`?++The network connection reached the SSH server, but RAGFlow could not find a trusted host key for that host and port. RAGFlow rejects unknown keys before attempting password or private-key authentication.++For a non-default SSH port, the `known_hosts` entry must include the port—for example, `[192.168.1.5]:2222`. Verify the server fingerprint, add the key to the file used by RAGFlow, and ensure that the file is visible to the RAGFlow process or container.++For Docker and source deployment instructions, see [Prepare the SSH `known_hosts` file](./configure_ssh_and_cloud_providers.md#prepare-the-ssh-known_hosts-file).++If the message reports a host-key mismatch instead, verify whether the server key was intentionally changed before replacing the existing entry. An unexpected key change can indicate that the connection is being intercepted.++### Why does SSH authentication fail?++Verify the username and the selected authentication method. For password authentication, confirm that the server permits password login. For private-key authentication, confirm that:++- The public key is authorized for the selected remote user.+- The pasted PEM is complete, or the configured path is readable by the RAGFlow process.+- A Docker path refers to a file mounted inside the RAGFlow container, not only to a host path.+- The passphrase matches the encrypted key.++Do not configure both password and private-key authentication at the same time.++### Why can RAGFlow not create the remote workspace?++The configured SSH user must be able to create and remove directories under **Remote Workspace Root**. Check the path, ownership, permissions, available disk space, filesystem mount options, and user quota. `/tmp` is the default; use a dedicated writable path when server policy restricts it.++### Why can the remote host not find Python or Node.js?++The configured binary must be available in the non-interactive SSH session. Shell profile files may not modify `PATH` for this type of session. Enter an absolute executable path, such as `/usr/bin/python3` or the interpreter inside a virtual environment, and verify that the SSH user can execute it.++**Test connection** always uses Python. Node.js is only required for JavaScript Code components.++## Cloud providers++Return to the detailed configuration for [Aliyun Code Interpreter](./configure_ssh_and_cloud_providers.md#configure-aliyun-code-interpreter), [E2B](./configure_ssh_and_cloud_providers.md#configure-e2b), [Tenki](./configure_ssh_and_cloud_providers.md#configure-tenki), or [UCloud Agent Sandbox](./configure_ssh_and_cloud_providers.md#configure-ucloud-agent-sandbox) when checking credentials, regions, endpoints, resource settings, or network access.++### Why is the API credential rejected?++Check that the credential belongs to the selected provider and account, has not expired or been revoked, and has permission to list or create the required resources. Confirm the account ID and region where applicable. For Aliyun, the credentials need Code Interpreter template and sandbox permissions. For E2B `eu`, the RAGFlow runtime must also have `E2B_DOMAIN` configured.++After changing a deployment-level environment variable, apply the change to RAGFlow before testing again.++### Why does sandbox creation time out?++Confirm that RAGFlow can reach the provider API, the selected region is available, and the account has quota. Check provider status, firewall and proxy rules, DNS, and RAGFlow logs. Increasing a request timeout does not fix invalid credentials, unavailable quota, or a blocked network path.++### How do region, quota, network, and account limits affect execution?++Cloud providers create resources in the configured account and region. An unsupported region, exhausted concurrency quota, billing restriction, or organization policy can prevent creation even when credentials are valid. The provider console and audit logs usually contain the most specific service-side error.++Test connection and Code execution may consume quota or incur charges. Review provider limits before enabling the service for multiple users.++## Artifacts++### Why was a generated file not returned?++The file must be written under the execution workspace's `artifacts/` directory and use a supported extension. It can also be omitted when it exceeds provider size or count limits, cannot be decoded, or cannot be uploaded to object storage. Check Code execution output, RAGFlow logs, provider limits, and object-storage availability.++### Where should code write generated files?++Use a path under `artifacts/` relative to the execution workspace. Files written elsewhere are treated as temporary execution files and are not returned.++### What size, count, type, and retention limits apply?++SSH, Tenki, and UCloud expose **Max Artifacts** and **Max Artifact Bytes** settings. Other providers or Executor Manager versions may enforce their own limits. Supported returned extensions are `.csv`, `.html`, `.jpeg`, `.jpg`, `.json`, `.pdf`, `.png`, and `.svg`.++RAGFlow stores returned files in the bucket selected by `SANDBOX_ARTIFACT_BUCKET`, which defaults to `sandbox-artifacts`. Configure retention and deletion through the object-storage service; RAGFlow does not define a separate Sandbox artifact retention setting here.++## Security++### Can the Executor Manager endpoint be exposed publicly?++Do not expose it directly to the public internet. The endpoint accepts code-execution requests and the Manager has privileged Docker access in the supplied deployment. Keep it on a private network or behind a protected TLS reverse proxy, require a strong API token, restrict allowed source addresses, and monitor authentication failures.++### Why should Runner network access remain disabled by default?++Network-disabled Runners cannot directly reach internal services, cloud metadata endpoints, other containers, or the internet. This reduces the effect of malicious or accidental code. Prefer trusted images with dependencies pre-installed. Enable outbound access only for a defined workload and protect it with egress controls.diff --git a/docs/administrator/sandbox/manage_self_managed_sandbox.md b/docs/administrator/sandbox/manage_self_managed_sandbox.mdnew file mode 100644index 0000000000..c6466de764--- /dev/null+++ b/docs/administrator/sandbox/manage_self_managed_sandbox.md@@ -0,0 +1,216 @@+---+sidebar_position: 4+title: Manage Self-Managed Sandbox+sidebar_label: Manage Self-Managed Sandbox+slug: /manage_self_managed_sandbox+---++# Manage Self-Managed Sandbox++Use this guide after completing [Quickstart with Self-Managed](./quickstart_with_self_managed.md). The settings in this document control the optional `sandbox-executor-manager` Compose service and its Runner containers.++Run the Docker Compose commands below from the RAGFlow repository's `docker` directory. If the existing deployment uses a custom Compose project name, Compose file, or environment file, use the same options with every command in this guide.++## Check service health++Check the service state:++```bash+docker compose ps --all sandbox-executor-manager+```++Check the Manager health endpoint. The command below uses the default host port; if you changed `SANDBOX_EXECUTOR_MANAGER_PORT`, use that port instead:++```bash+curl -f http://127.0.0.1:9385/healthz+```++If the service is not `healthy`, inspect its logs:++```bash+docker compose logs --tail=200 sandbox-executor-manager+```++The `/healthz` endpoint only confirms that Executor Manager is responding. To verify that it can create a Runner and execute code, open **Admin > Sandbox Settings**, select **Self-Managed**, and run **Test connection**. A successful test displays `PASSED`.++After deployment changes, also run a Code component to verify the complete path from RAGFlow through Executor Manager to the Runner.++## Stop or restart the service++Stop Executor Manager without removing its Compose configuration:++```bash+docker compose stop sandbox-executor-manager+```++While the service is stopped, Code components that use the active Self-Managed provider cannot execute.++Start it again:++```bash+docker compose up -d sandbox-executor-manager+```++Wait until the service reports `healthy`, then run **Test connection** before allowing users to execute code again.++## Connect to a remote Executor Manager++Executor Manager can run on another host while RAGFlow runs in Docker or from source. RAGFlow only needs an HTTP or HTTPS endpoint that it can reach.++:::caution Protect the execution endpoint+The `/run` endpoint executes submitted code and must not be exposed directly to the public internet. Use a private network or a protected reverse proxy, require a strong API token, restrict source addresses, and use TLS when traffic crosses an untrusted network.+:::++The supplied RAGFlow Compose service publishes port `9385` on `127.0.0.1` only, so it is not remotely reachable by default. For a separately hosted Manager, follow the deployment and security guidance in the [Sandbox repository](https://github.com/infiniflow/sandbox), then:++1. Confirm that the remote Manager has the Python and Node.js Runner images available.+2. Set a strong `SANDBOX_EXECUTOR_MANAGER_API_TOKEN` on the Manager.+3. Make the protected endpoint reachable from the RAGFlow host or container.+4. Verify the remote health endpoint from the environment where RAGFlow runs. If RAGFlow runs in a container, test from that container or its network—not only from the Docker host:++ ```bash+ curl -f https://sandbox.example.com/healthz+ ```++5. Open **Admin > Sandbox Settings** and select **Self-Managed**.+6. Enter the remote URL in **Executor Manager Endpoint** and the matching token in **Executor Manager API Token**.+7. Run **Test connection**, confirm `PASSED`, and save the configuration.++Do not use `127.0.0.1` unless RAGFlow and the published Manager port are on the same host and RAGFlow runs directly on that host. Inside a RAGFlow container, `127.0.0.1` refers to the RAGFlow container itself.++## Configure deployment settings++Configure these values in `docker/.env`:++| Variable | Default | Purpose |+| --- | --- | --- |+| `SANDBOX_EXECUTOR_MANAGER_POOL_SIZE` | `3` | Number of Runner environments maintained by Executor Manager. Increase it only after measuring concurrent demand and host capacity. |+| `SANDBOX_EXECUTOR_MANAGER_PORT` | `9385` | Port published on `127.0.0.1` of the Docker host. Set it in `docker/.env`. This does not change the container port `9385` used inside the Compose network. |+| `SANDBOX_MAX_MEMORY` | `256m` | Memory limit applied to a Runner container. Accepts Docker-style sizes such as `512m` or `1g`. |+| `SANDBOX_TIMEOUT` | `10s` | Service-side execution limit, such as `30s` or `1m`. |+| `SANDBOX_ENABLE_SECCOMP` | `false` | Enables the seccomp behavior supported by the deployed Executor Manager version. Validate workload compatibility before enabling it. |++`SANDBOX_TIMEOUT` is different from **Request Timeout (seconds)** in Admin. The service-side limit controls the Runner execution; the Admin setting controls how long RAGFlow waits for the Manager response. Keep the Admin request timeout longer than the expected service execution time.++After changing deployment values, apply the changes:++```bash+docker compose up -d sandbox-executor-manager+```++Then check its health and run **Test connection** again.++## Manage Runner images++The default Runner images are:++```dotenv+SANDBOX_BASE_PYTHON_IMAGE=infiniflow/sandbox-base-python:latest+SANDBOX_BASE_NODEJS_IMAGE=infiniflow/sandbox-base-nodejs:latest+```++Use a custom image when every execution needs additional packages or system libraries. Prefer pre-installing dependencies in a trusted image instead of enabling Runner internet access and installing packages during each run.++To change an image:++1. Build or select an image compatible with the deployed Executor Manager.+2. Pin a tested version tag or digest instead of relying on a moving tag in production.+3. Pull the image on the Docker host:++ ```bash+ RUNNER_IMAGE=infiniflow/sandbox-base-python:latest+ docker pull "$RUNNER_IMAGE"+ ```++ Replace the `RUNNER_IMAGE` value with the full name and tag of the selected image.++4. Set `SANDBOX_BASE_PYTHON_IMAGE` or `SANDBOX_BASE_NODEJS_IMAGE` in `docker/.env`.+5. Apply the changes to Executor Manager and run **Test connection**.+6. Run a Code component in each language whose image changed.++To update Executor Manager itself, set `SANDBOX_EXECUTOR_MANAGER_IMAGE` to a tested image tag, pull it, and apply the change. Keep Manager and Runner image versions compatible.++## Manage Runner network access++Runner containers use no network by default:++```dotenv+SANDBOX_CONTAINER_NETWORK=none+```++This prevents executed code from reaching the internet, internal services, cloud metadata endpoints, and other containers. Keep this default for untrusted code.++If a controlled workload requires outbound access, set an explicitly managed Docker network. The commonly used Docker value `bridge` gives broader outbound access:++```dotenv+SANDBOX_CONTAINER_NETWORK=bridge+```++Before enabling it, apply egress filtering and confirm that Runners cannot reach sensitive internal services or host-management endpoints. Apply the change and verify the workload.++## Manage generated artifacts++Code must write files intended for return under the execution workspace's `artifacts/` directory. RAGFlow publishes supported files to object storage and returns authorized links to the Agent.++Supported extensions are `.csv`, `.html`, `.jpeg`, `.jpg`, `.json`, `.pdf`, `.png`, and `.svg`. Provider or Executor Manager limits may also restrict the number and size of files.++The object-storage bucket defaults to `sandbox-artifacts`. To use another bucket, set the following value in the RAGFlow runtime environment:++```dotenv+SANDBOX_ARTIFACT_BUCKET=ragflow-sandbox-artifacts+```++Replace the example value with the name of the bucket used by the deployment.++For Docker deployments, set it in `docker/.env` and apply the change to RAGFlow:++```bash+docker compose up -d ragflow-cpu+```++This variable controls RAGFlow storage, not the Runner or Executor Manager.++RAGFlow does not define a separate Sandbox artifact retention value in this configuration. Apply retention and lifecycle rules through the configured object-storage service according to your organization's policy.++## Rotate the API token++The token configured on Executor Manager must match **Executor Manager API Token** in Admin.++:::note Maintenance window recommended+The Compose service accepts one configured token. Requests can fail between restarting Executor Manager with the new token and saving the matching Admin configuration.+:::++1. Generate a new token:++ ```bash+ openssl rand -hex 32+ ```++2. Replace `SANDBOX_EXECUTOR_MANAGER_API_TOKEN` in `docker/.env`.+3. Apply the token change:++ ```bash+ docker compose up -d sandbox-executor-manager+ ```++4. In **Admin > Sandbox Settings**, enter the new token under **Self-Managed**.+5. Run **Test connection**, confirm `PASSED`, and select **Save**.+6. Run a Code component and confirm that execution succeeds.++## Production checklist++- Keep Executor Manager on a private network or behind a protected TLS reverse proxy.+- Configure a strong API token and rotate it according to your credential policy.+- Restrict access to the Docker socket and the privileged Manager container.+- Set Runner pool, memory, and timeout values that fit the host capacity.+- Keep Runner networking disabled unless outbound access is required and controlled.+- Use trusted, pinned Manager and Runner images and scan custom images before deployment.+- Apply object-storage access controls and lifecycle rules to generated artifacts.+- Monitor Manager logs, Runner creation failures, resource exhaustion, and repeated authentication failures.+- Test Python and JavaScript after image, network, token, or resource-limit changes.++## Admin UI settings++Admin controls the RAGFlow-to-Manager connection: endpoint, API token, and request timeout. Compose variables control the Manager and Runner deployment. Changing one does not automatically update the other.++For the connection fields, see [Configure Code Execution Sandbox](../admin/admin_ui/configure_code_execution_sandbox.md#self-managed-fields).diff --git a/docs/administrator/sandbox/overview.md b/docs/administrator/sandbox/overview.mdnew file mode 100644index 0000000000..e3e3f0acbb--- /dev/null+++ b/docs/administrator/sandbox/overview.md@@ -0,0 +1,51 @@+---+sidebar_position: 1+title: Code Execution Sandbox+sidebar_label: Overview+slug: /code_execution_sandbox+---++# Code Execution Sandbox++RAGFlow Agents can use the **Code** component to run Python or JavaScript. Before users can run code, an administrator must select and configure a sandbox provider.++The provider determines where the code runs. Depending on your choice, RAGFlow can send code to containers managed in your own environment, an existing SSH server, or a managed cloud sandbox.++:::warning System-wide setting+The active sandbox provider is a system-wide setting. Changing it affects subsequent Code component runs across the RAGFlow deployment. Test the new configuration before saving it.+:::++For instructions on using the Code component after an administrator has configured a provider, see [Code component](../../guides/agent/agent_workflow/data_manipulation_components.md).++## Choose a sandbox provider++Choose the provider that matches where you want code to run and who should manage the execution environment.++| Provider | Where code runs | Choose it when |+| --- | --- | --- |+| [**Self-Managed**](./quickstart_with_self_managed.md) | Python or Node.js Runner containers managed by Sandbox Executor Manager in your environment | You want to keep code execution under your operational control. This is the default option and the focus of the Self-Managed guides. |+| [**SSH**](./configure_ssh_and_cloud_providers.md#configure-ssh) | An existing remote Linux host | You already operate a suitable execution server with Python or Node.js and can manage its SSH access and host keys. |+| [**Aliyun Code Interpreter**](./configure_ssh_and_cloud_providers.md#configure-aliyun-code-interpreter) | Alibaba Cloud Code Interpreter | Your organization uses Alibaba Cloud and wants a managed execution environment. |+| [**E2B**](./configure_ssh_and_cloud_providers.md#configure-e2b) | E2B cloud sandboxes | You want an externally managed cloud sandbox without operating local Runner containers. |+| [**Tenki**](./configure_ssh_and_cloud_providers.md#configure-tenki) | A disposable Tenki microVM created for each execution | You want each run to use an isolated, short-lived cloud microVM. |+| [**UCloud Agent Sandbox**](./configure_ssh_and_cloud_providers.md#configure-ucloud-agent-sandbox) | A disposable UCloud Agent Sandbox | You want a managed cloud sandbox in a supported UCloud region. |++:::note Before choosing a cloud provider+Confirm that your RAGFlow deployment can reach the provider's API, and that your account has valid credentials, sufficient quota, and access to the required region.+:::++## Recommended path for private deployments++For most private or on-premises deployments, start with **Self-Managed**. In the standard deployment:++1. RAGFlow sends the execution request to Sandbox Executor Manager.+2. Sandbox Executor Manager selects a Python or Node.js Runner container.+3. The Runner executes the code and returns its output and generated files to RAGFlow.++RAGFlow can run with Docker Compose or directly from source while Sandbox Executor Manager and its Runners use Docker. Follow [Quickstart with Self-Managed](./quickstart_with_self_managed.md) for both deployment patterns.++## Next steps++- Get started with [Quickstart with Self-Managed](./quickstart_with_self_managed.md).+- To use SSH or a cloud service, see [Configure SSH and Cloud Providers](./configure_ssh_and_cloud_providers.md).+- For maintenance and troubleshooting, see [Manage Self-Managed Sandbox](./manage_self_managed_sandbox.md) and [FAQ](./faq.md).diff --git a/docs/administrator/sandbox/quickstart_with_self_managed.md b/docs/administrator/sandbox/quickstart_with_self_managed.mdnew file mode 100644index 0000000000..a9e9526655--- /dev/null+++ b/docs/administrator/sandbox/quickstart_with_self_managed.md@@ -0,0 +1,202 @@+---+sidebar_position: 2+title: Quickstart with Self-Managed+sidebar_label: Quickstart with Self-Managed+slug: /sandbox_quickstart_self_managed+---++# Quickstart with Self-Managed++This guide helps you connect RAGFlow to a Self-Managed Sandbox and run your first Code component task. The standard setup uses the published Sandbox Executor Manager and Python and Node.js Runner images with Docker.++## Before you begin++You need:++- A Linux host with Docker and Docker Compose.+- Permission to run Docker containers. The deployment must allow privileged containers and Docker socket access.+- A running RAGFlow deployment or a working RAGFlow source environment.+- Access to **Admin > Sandbox Settings**.+- Network access to pull images from Docker Hub.++You do not need to install Python or Node.js on the RAGFlow host. They run in the Sandbox Runner containers.++Confirm that the deployment account can access the Docker daemon:++```bash+docker info+```++Continue only if this command displays Docker server information. If it returns `permission denied` for `/var/run/docker.sock`, use an account already authorized to manage Docker or configure Docker access according to your organization's host-security policy. Membership in the Docker group grants root-equivalent control of the host; do not grant it broadly. The deployment must also allow the privileged Executor Manager container to mount the Docker socket.++## 1. Determine the Sandbox endpoint++First, identify where RAGFlow and Sandbox Executor Manager are running. Their deployment locations determine the endpoint that you must enter later in **Admin > Sandbox Settings**.++| Deployment scenario | Endpoint |+| --- | --- |+| RAGFlow and Sandbox Executor Manager run in the supplied Docker Compose deployment | `http://sandbox-executor-manager:9385` |+| RAGFlow runs from source, and Sandbox Executor Manager runs in Docker on the same host | `http://127.0.0.1:9385` |+| Sandbox Executor Manager runs on another host | An address reachable from RAGFlow, such as `https://sandbox.example.com` |++These endpoints use the default ports. If you change `SANDBOX_EXECUTOR_MANAGER_PORT`, update the source-deployment endpoint accordingly. Replace `https://sandbox.example.com` with the actual remote address, including its port when required.++:::note+The endpoint is resolved from where RAGFlow runs. If RAGFlow runs in a container, `127.0.0.1` refers to that container—not the Docker host or another container.++In the supplied Compose deployment, RAGFlow resolves `sandbox-executor-manager` through the shared Docker network. You do not need to add it to `/etc/hosts`.+:::++If an Executor Manager is already deployed, skip Steps 2–4 and use its endpoint and API token in [Configure Self-Managed in Admin](#5-configure-self-managed-in-admin). Before connecting to a Manager on another host, follow [Connect to a remote Executor Manager](./manage_self_managed_sandbox.md#connect-to-a-remote-executor-manager) to protect the endpoint.++## 2. Prepare the Sandbox service++In the RAGFlow repository, find the Sandbox section in `docker/.env` and uncomment the following settings:++```dotenv+COMPOSE_PROFILES=${COMPOSE_PROFILES},sandbox+SANDBOX_EXECUTOR_MANAGER_API_TOKEN=replace-with-a-generated-secret+```++Adding `sandbox` to `COMPOSE_PROFILES` ensures that future RAGFlow Compose startups also include Sandbox Executor Manager. Step 3 explicitly names the service so that you can start it immediately without restarting the other RAGFlow services.++Do not use the example token literally. Replace `replace-with-a-generated-secret` with a secret value, which you can generate with:++```bash+openssl rand -hex 32+```++Keep this token private. You will enter the same value in the RAGFlow Admin settings.++Pull the default runtime images:++```bash+docker pull infiniflow/sandbox-base-python:latest+docker pull infiniflow/sandbox-base-nodejs:latest+```++The Python image runs Python code, and the Node.js image runs JavaScript code. The supplied Compose configuration uses both images by default unless you override them in `docker/.env`.++The `latest` tag is convenient for initial setup. For production, use tested and compatible Manager and Runner image versions.++## 3. Start Sandbox Executor Manager++From the RAGFlow repository, enter the `docker` directory:++```bash+cd docker+```++Start Sandbox Executor Manager without restarting the other RAGFlow services:++```bash+docker compose up -d sandbox-executor-manager+```++This command works whether RAGFlow itself runs with Docker Compose or from source. By default, it publishes Executor Manager at `127.0.0.1:9385` on the Docker host. `SANDBOX_EXECUTOR_MANAGER_PORT` changes the published host port.++:::caution Use the existing Compose project+If RAGFlow was started with custom Compose options, use the same options in every command. For example:++```bash+docker compose -p YOUR_PROJECT_NAME up -d sandbox-executor-manager+```++Replace `YOUR_PROJECT_NAME` with the existing RAGFlow Compose project name. Otherwise, the Manager may be healthy but unreachable from RAGFlow.+:::++:::tip First startup can take longer+Docker may need to pull the Executor Manager image and initialize its Runners.+:::++## 4. Verify the service++Check its status:++```bash+docker compose ps --all sandbox-executor-manager+```++Wait until the service reports `healthy`, then check its health endpoint. The command below uses the default host port; if you changed `SANDBOX_EXECUTOR_MANAGER_PORT`, use that port instead:++```bash+curl -f http://127.0.0.1:9385/healthz+```++The health check succeeds when the command completes without an error and Docker Compose reports the service as `healthy`. The response body may vary by Executor Manager version.++Continue only when both checks succeed. If the status remains `starting`, allow more time for initialization. If it reports `unhealthy` or `exited`, inspect the logs:++```bash+docker compose logs --tail=200 sandbox-executor-manager+```++For a Compose deployment, also verify access from RAGFlow:++```bash+docker compose exec ragflow-cpu curl -f http://sandbox-executor-manager:9385/healthz+```++If you changed `SANDBOX_EXECUTOR_MANAGER_PORT`, use that port for the host health check. The Compose endpoint remains on port `9385`. See the [FAQ](./faq.md) if the service does not become healthy.++:::caution Verify the effective isolation runtime+Check the startup logs for the active runtime. `falling back to runc` means execution works without gVisor isolation. Confirm that this meets your security requirements.+:::++## 5. Configure Self-Managed in Admin++1. Open **Admin > Sandbox Settings**.+2. Select **Self-Managed**.+3. Complete the connection settings:++ | Setting | Value |+ | --- | --- |+ | **Executor Manager Endpoint** | Use the endpoint selected in [Step 1](#1-determine-the-sandbox-endpoint). |+ | **Executor Manager API Token** | Enter the same token configured for Executor Manager. |+ | **Request Timeout (seconds)** | Keep the default `30` for the first test. |++4. Select **Test connection**.+5. Confirm that the test result shows `PASSED`.+6. Select **Save**.++The connection test runs a small Python program. It verifies more than the `/healthz` endpoint: Executor Manager must also be able to start a Runner and execute code.++## 6. Run your first Code component++1. Create or open an Agent.+2. Add a **Code** component.+3. Set the language to Python.+4. Paste the following code:++```python+def main():+ return "Sandbox is ready"+```++5. Run the component.+6. Confirm that the result is:++```text+Sandbox is ready+```++This confirms the complete path from RAGFlow to Executor Manager and a Python Runner.++If **Test connection** succeeds but the Code component fails, see [Self-Managed execution](./faq.md#self-managed-execution) in the FAQ.++## Confirm the setup++The setup is complete when:++- `docker info` displays Docker server information.+- `docker compose ps --all sandbox-executor-manager` reports the service as `healthy`.+- The `/healthz` request completes without an error.+- **Test connection** displays `PASSED`.+- The Code component returns `Sandbox is ready`.++## Troubleshooting and next steps++- To adjust Runner capacity, images, resource limits, network access, artifacts, or authentication, see [Manage Self-Managed Sandbox](./manage_self_managed_sandbox.md).+- To connect RAGFlow to an Executor Manager on another host, see [Connect to a remote Executor Manager](./manage_self_managed_sandbox.md#connect-to-a-remote-executor-manager).+- If startup, connection, authentication, or execution fails, see [Code Execution Sandbox FAQ](./faq.md).+- To use SSH or a managed cloud service instead, see [Configure SSH and Cloud Providers](./configure_ssh_and_cloud_providers.md).diff --git a/docs/guides/agent/agent_workflow/data_manipulation_components.md b/docs/guides/agent/agent_workflow/data_manipulation_components.mdindex 489f56167e..c6ef6bc673 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: 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).+Prerequisite: An administrator must configure a provider in **Admin > Sandbox Settings**. See [Code Execution Sandbox](../../../administrator/sandbox/overview.md). For a private deployment, follow [Quickstart with Self-Managed](../../../administrator/sandbox/quickstart_with_self_managed.md).Configuration:1. **Input**: Define parameters passed into code; variables can be directly referenced inside scripts.