OpenSandbox Configuration
Configure OpenSandbox and Agent Sandbox Proxy for FastGPT
OpenSandbox does not provide network isolation by default. Add your own network isolation policy if your environment requires it.
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.
Docker Compose Configuration
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.
Environment Variables
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.
OpenSandbox Service
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.
Agent Sandbox Proxy Service
| 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.
fastgpt-app Service
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.2.0
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=1AGENT_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.
Host the preview proxy on an origin separate from the FastGPT application, using a different scheme, host, or port. Sandbox HTML may contain user-generated scripts. If previews share the application origin, those scripts may be able to access application credentials or APIs.
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.
Additional Configuration
Custom Package Registries
Configure package registries in both fastgpt-app and fastgpt-pro when sandboxes need to install npm or Python dependencies:
AGENT_SANDBOX_NPM_REGISTRY=https://registry.npmmirror.com
AGENT_SANDBOX_PYPI_INDEX_URL=https://pypi.tuna.tsinghua.edu.cn/simpleResource and Lifecycle Settings
| 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. |
FAQ
Sandbox provider apiKey is required for opensandbox
Check AGENT_SANDBOX_OPENSANDBOX_API_KEY and make sure it matches [server].api_key in opensandbox-config.
AGENT_SANDBOX_OPENSANDBOX_VOLUME_MANAGER_URL is required
Check AGENT_SANDBOX_OPENSANDBOX_VOLUME_MANAGER_URL and AGENT_SANDBOX_OPENSANDBOX_VOLUME_MANAGER_TOKEN, and make sure Volume Manager is running.
AGENT_SANDBOX_PROXY_URL or AGENT_SANDBOX_PREVIEW_PROXY_URL is required
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.
Browser WebSocket connection fails
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://.
Proxy validation fails or returns 401
Make sure AGENT_SANDBOX_PROXY_SECRET is identical in FastGPT and Agent Sandbox Proxy and contains at least 32 characters.
The sandbox is created, but the file tree or terminal does not connect
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.
Proxy cannot connect to the sandbox endpoint
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.