document/content/self-host/config/sandbox/common.en.mdx
This page covers shared Agent Sandbox configuration for both opensandbox and sealosdevbox. Provider-specific settings are documented on each provider page. Regardless of the provider, you need to deploy fastgpt-agent-sandbox-proxy and optionally configure package mirrors for the sandbox runtime.
Use agent-sandbox-proxy.yml as a reference and add the service to your yml file. Expose the external access port and record the AGENT_SANDBOX_PROXY_SECRET value, which you will need in the next step.
FastGPT uses this proxy when accessing the sandbox file system.
Proxy service environment variables
| Variable | Default | Description |
|---|---|---|
PORT | 1006 | Listening port for fastgpt-agent-sandbox-proxy. |
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 URL of the FastGPT main service. The proxy and FastGPT must be able to reach each other on the network. |
FASTGPT_APP_REQUEST_TIMEOUT_SECS | 10 | Timeout, in seconds, for proxy requests back to the FastGPT main service. Increase it if sandbox cold starts take longer. |
RUST_LOG | info,fastgpt_agent_sandbox_proxy=debug | Log level for the proxy service. |
Add the following environment variables to both fastgpt-app and fastgpt-pro:
# Must match AGENT_SANDBOX_PROXY_SECRET in fastgpt-agent-sandbox-proxy. Use a random secret longer than 32 characters in production.
AGENT_SANDBOX_PROXY_SECRET=replace_with_32_chars_random_secret
# Browser-accessible WebSocket URL for agent-sandbox-proxy. Use wss:// when proxying through an HTTPS domain.
AGENT_SANDBOX_PROXY_URL=wss://sandbox-proxy.example.com
fastgpt-app, fastgpt-pro, and fastgpt-agent-sandbox-proxy.https://agent-proxy-domain/health. It should return OK.After deploying the proxy service, connect one of the supported sandbox providers:
If the sandbox needs to install npm or Python dependencies, configure package mirrors in both fastgpt-app and fastgpt-pro. During Agent Sandbox initialization, FastGPT writes these settings for npm, yarn, pnpm, bun, pip, and uv.
# npm registry used by npm/yarn/pnpm/bun inside Agent Sandbox
AGENT_SANDBOX_NPM_REGISTRY=https://registry.npmmirror.com
# PyPI index URL used by pip/python -m pip/uv inside Agent Sandbox
AGENT_SANDBOX_PYPI_INDEX_URL=https://pypi.tuna.tsinghua.edu.cn/simple
Configure the following variables in fastgpt-app and fastgpt-pro when you need to adjust resource limits:
| Variable | Default | Description |
|---|---|---|
AGENT_SANDBOX_DISK_MB | 1024 | Baseline Agent Sandbox disk size in MB. It affects cold archive package limits, Skill package limits, and IDE single-file limits. |
AGENT_SANDBOX_WS_MAX_MESSAGE_BYTES | 67108864 | Maximum IDE Agent WebSocket message size in bytes. |
AGENT_SANDBOX_WS_MAX_FRAME_BYTES | 16777216 | Maximum IDE Agent WebSocket frame size in bytes. |
After Agent Sandbox is enabled, AGENT_SANDBOX_PROXY_URL is required. This is the browser-accessible WebSocket URL for fastgpt-agent-sandbox-proxy, such as wss://sandbox-proxy.example.com. It is not the FastGPT main site URL.
Check that the proxy service is reachable from the browser and that your reverse proxy supports WebSocket Upgrade. If FastGPT is accessed over HTTPS, AGENT_SANDBOX_PROXY_URL should use wss:// to avoid mixed-content blocking.
Make sure AGENT_SANDBOX_PROXY_SECRET is exactly the same in the FastGPT main service and fastgpt-agent-sandbox-proxy, and that it is at least 32 characters long.