document/content/self-host/config/sandbox/opensandbox.en.mdx
import { Alert } from '@/components/docs/Alert';
<Alert icon="⚠️" context="warning"> OpenSandbox does not provide network isolation by default. Add your own network isolation policy if your environment requires it. </Alert>OpenSandbox is designed for self-hosted Agent and Skill sandbox runtimes. FastGPT creates sandboxes through OpenSandbox Server, while Agent Sandbox Proxy provides browser access to files, terminals, and previews.
The latest Docker Compose file already includes OpenSandbox Server, Volume Manager, Agent Sandbox Proxy, and the sandbox runtime images. You do not need to merge any additional YAML files.
View the latest docker-compose.yml (PgVector, global registries)
See Deploy with Docker Compose for other vector databases and China Mainland registries.
The Docker Compose YAML files include default values. This section documents each variable. This page tracks the latest configuration; older releases may differ, so check the YAML for the corresponding older release when needed.
Review these settings in the Compose file for your environment:
| Setting | Description |
|---|---|
x-volume-manager-auth-token | Volume Manager token. It must match AGENT_SANDBOX_OPENSANDBOX_VOLUME_MANAGER_TOKEN in FastGPT. |
[server].api_key | OpenSandbox Server API key. It must match AGENT_SANDBOX_OPENSANDBOX_API_KEY in FastGPT. |
[docker].host_ip | Host address that sandbox endpoints expose to the proxy. Use the host's internal IP or host.docker.internal. |
| Docker socket mount | The Docker runtime requires the host Docker socket. The default is /var/run/docker.sock; use the actual path if different. |
If the host uses HTTP_PROXY or HTTPS_PROXY, explicitly set NO_PROXY and no_proxy for OpenSandbox Server and Volume Manager. Include at least localhost,127.0.0.1,127.0.0.0/8,fastgpt-app,fastgpt-opensandbox-server,fastgpt-volume-manager,fastgpt-agent-sandbox-proxy,host.docker.internal so internal requests do not go through the proxy.
| Variable | Default | Description |
|---|---|---|
PORT | 1006 | Proxy container port, mapped to port 3006 on the host by default. |
PREVIEW_PORT | Same as PORT | In 4.16, sets a separate HTTP preview listener; update the host port mapping and AGENT_SANDBOX_PREVIEW_PROXY_URL accordingly. |
AGENT_SANDBOX_PROXY_SECRET | None | Secret shared with the FastGPT main service. Must be at least 32 characters. |
FASTGPT_APP_URL | http://fastgpt-app:3000 | Internal FastGPT URL used by the proxy. |
FASTGPT_APP_REQUEST_TIMEOUT_SECS | 10 | Timeout for proxy requests to FastGPT, in seconds. Increase for slow cold starts. |
RUST_LOG | info,fastgpt_agent_sandbox_proxy=debug | Proxy service log level. |
In 4.16, WebSocket and HTTP preview traffic use the same port by default. If your gateway cannot route both protocols on one port, set PREVIEW_PORT to another container port (for example, 1007), change the Compose mapping to 3007:1007, and point AGENT_SANDBOX_PREVIEW_PROXY_URL to port 3007.
Configure these variables in the Compose file's x-agent-sandbox-config anchor so fastgpt-app and fastgpt-pro share the OpenSandbox settings:
AGENT_SANDBOX_PROVIDER=opensandbox
# Internal OpenSandbox Server URL and API key
AGENT_SANDBOX_OPENSANDBOX_BASEURL=http://fastgpt-opensandbox-server:8090
AGENT_SANDBOX_OPENSANDBOX_API_KEY=replace_with_opensandbox_api_key
AGENT_SANDBOX_OPENSANDBOX_RUNTIME=docker
AGENT_SANDBOX_OPENSANDBOX_IMAGE=ghcr.io/labring/fastgpt-agent-sandbox:v0.3.1
AGENT_SANDBOX_OPENSANDBOX_USE_SERVER_PROXY=true
# Volume Manager URL, token, and persistent volume name prefix
AGENT_SANDBOX_OPENSANDBOX_VOLUME_MANAGER_URL=http://fastgpt-volume-manager:3000
AGENT_SANDBOX_OPENSANDBOX_VOLUME_MANAGER_TOKEN=replace_with_volume_manager_token
AGENT_SANDBOX_OPENSANDBOX_VOLUME_NAME_PREFIX=fastgpt-session
# Agent Sandbox Proxy settings
AGENT_SANDBOX_PROXY_SECRET=replace_with_32_chars_random_secret
AGENT_SANDBOX_PROXY_URL=wss://sandbox-proxy.example.com
AGENT_SANDBOX_PREVIEW_PROXY_URL=https://sandbox-proxy.example.com
# Per-sandbox resource limits
AGENT_SANDBOX_CPU_COUNT=1
AGENT_SANDBOX_MEMORY_MIB=2048
AGENT_SANDBOX_STORAGE_SIZE_GI=1
AGENT_SANDBOX_OPENSANDBOX_IMAGE is the full runtime image reference used when OpenSandbox creates an Agent Sandbox. The standard fastgpt-agent-sandbox image runs as a non-root user and is suitable for the default case. When a sandbox must modify /etc/apt or install apt packages, use the fastgpt-agent-sandbox-root image and configure AGENT_SANDBOX_APT_MIRROR as well.
Each official image tag includes both amd64 and arm64 variants. Both architectures use the same environment variable configuration, and Docker selects the matching variant based on the architecture of the host running OpenSandbox Server:
| Use case | Image |
|---|---|
| Non-root | ghcr.io/labring/fastgpt-agent-sandbox:v0.3.1 |
| Root | ghcr.io/labring/fastgpt-agent-sandbox-root:v0.3.1 |
For China Mainland registries, replace ghcr.io/labring with registry.cn-hangzhou.aliyuncs.com/fastgpt. If you use a private registry, make sure each tag preserves both the amd64 and arm64 manifests. If the registry provides only a single-architecture image, set AGENT_SANDBOX_OPENSANDBOX_IMAGE to an image matching the architecture of the OpenSandbox Server host.
AGENT_SANDBOX_OPENSANDBOX_API_KEY must match [server].api_key, AGENT_SANDBOX_OPENSANDBOX_VOLUME_MANAGER_TOKEN must match x-volume-manager-auth-token, and AGENT_SANDBOX_PROXY_SECRET must match the same variable in Agent Sandbox Proxy.
fastgpt-pro does not provide the Sandbox Editor or WebSocket proxy path, so it does not require AGENT_SANDBOX_PROXY_SECRET or AGENT_SANDBOX_PROXY_URL. It still requires AGENT_SANDBOX_PREVIEW_PROXY_URL.
Preview URLs are temporary, read-only bearer capabilities. Anyone with a URL can change its path to read other files in the same Sandbox Workspace while the URL remains valid. Do not share preview URLs with users who should not have access to that Workspace.
When upgrading from an earlier Volume Manager release, set AGENT_SANDBOX_OPENSANDBOX_VOLUME_NAME_PREFIX to the previous VM_VOLUME_NAME_PREFIX value so existing persistent volumes can still be cleaned up by their original names.
Configure package registries in both fastgpt-app and fastgpt-pro when sandboxes need to install npm, Python, or apt dependencies:
AGENT_SANDBOX_NPM_REGISTRY=https://registry.npmmirror.com
AGENT_SANDBOX_PYPI_INDEX_URL=https://pypi.tuna.tsinghua.edu.cn/simple
# Ubuntu amd64 example; use ubuntu-ports for Ubuntu arm64 as described below
AGENT_SANDBOX_APT_MIRROR=https://mirrors.tuna.tsinghua.edu.cn/ubuntu
AGENT_SANDBOX_NPM_REGISTRY and AGENT_SANDBOX_PYPI_INDEX_URL apply to all runtime images. AGENT_SANDBOX_APT_MIRROR is effective only for root Agent sandboxes and must point to the apt repository root, not a dists path or a specific release directory.
The apt mirror URL is not selected automatically based on the runtime image architecture. Select the corresponding Ubuntu repository path:
# Ubuntu amd64 / x86_64
AGENT_SANDBOX_APT_MIRROR=https://mirrors.tuna.tsinghua.edu.cn/ubuntu
# Ubuntu arm64 / aarch64
AGENT_SANDBOX_APT_MIRROR=https://mirrors.tuna.tsinghua.edu.cn/ubuntu-ports
Use the Ubuntu mirror guide and Ubuntu Ports mirror guide to confirm paths for other Ubuntu releases. With another mirror provider, use its standard Ubuntu or Ubuntu Ports repository path for the target architecture.
FastGPT reads /etc/os-release and generates or overwrites /etc/apt/sources.list.d/ubuntu.sources based on the Ubuntu version and codename. The file includes the main repository, updates, backports, and security. Before overwriting an existing sources file, FastGPT creates a .copy backup. When the variable is removed, files with a backup are restored and files without a backup are left unchanged. Initialization does not run apt-get update.
| Variable | Default | Description |
|---|---|---|
AGENT_SANDBOX_CPU_COUNT | 1 | Maximum CPU count for each Agent Sandbox. |
AGENT_SANDBOX_MEMORY_MIB | 2048 | Maximum memory for each Agent Sandbox, in MiB. |
AGENT_SANDBOX_STORAGE_SIZE_GI | 1 | Sandbox storage capacity, in Gi. |
AGENT_SANDBOX_WS_MAX_MESSAGE_BYTES | 67108864 | Maximum IDE Agent WebSocket message size. |
AGENT_SANDBOX_WS_MAX_FRAME_BYTES | 16777216 | Maximum IDE Agent WebSocket frame size. |
AGENT_SANDBOX_SUSPEND_MINUTES | 60 | Inactive minutes before a running sandbox is suspended. |
AGENT_SANDBOX_ARCHIVE_INACTIVE_DAYS | 7 | Inactive days before a suspended sandbox is archived. |
Check AGENT_SANDBOX_OPENSANDBOX_API_KEY and make sure it matches [server].api_key in opensandbox-config.
Check AGENT_SANDBOX_OPENSANDBOX_VOLUME_MANAGER_URL and AGENT_SANDBOX_OPENSANDBOX_VOLUME_MANAGER_TOKEN, and make sure Volume Manager is running.
fastgpt-app requires AGENT_SANDBOX_PROXY_SECRET, AGENT_SANDBOX_PROXY_URL, and AGENT_SANDBOX_PREVIEW_PROXY_URL. fastgpt-pro requires AGENT_SANDBOX_PREVIEW_PROXY_URL.
Check that the proxy is reachable from the browser and that your reverse proxy supports WebSocket Upgrade. If FastGPT uses HTTPS, AGENT_SANDBOX_PROXY_URL should use wss://.
Make sure AGENT_SANDBOX_PROXY_SECRET is identical in FastGPT and Agent Sandbox Proxy and contains at least 32 characters.
Make sure AGENT_SANDBOX_PROXY_URL is a browser-accessible ws:// or wss:// URL, and verify that host port 3006 or the corresponding domain is accessible.
Check [docker].host_ip in opensandbox-config. Sandbox endpoints that use localhost or 127.0.0.1 are not reachable from the proxy container. Use the host's internal IP or host.docker.internal.