General Sandbox Configuration

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.

Deploy sandbox-proxy

1. Add the yml service

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.

2. Update FastGPT environment variables

Add the following three environment variables to fastgpt-app:

# 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
# Browser-accessible HTTP(S) URL for Sandbox file previews
AGENT_SANDBOX_PREVIEW_PROXY_URL=https://sandbox-proxy.example.com

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. However, when Agent Sandbox is enabled, you must add AGENT_SANDBOX_PREVIEW_PROXY_URL to fastgpt-pro. It can use the same value as fastgpt-app.

We strongly recommend hosting the preview proxy on an origin separate from the FastGPT application, with a different scheme, host, or port. HTML files in a Sandbox may contain user-generated scripts. If previews share the FastGPT application origin, those scripts run inside the application's same-origin security boundary and may be able to access application credentials or APIs. FastGPT currently validates only that this variable uses http:// or https://; it does not enforce origin isolation.

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 a preview URL with anyone who should not have access to that Workspace.

3. Verify startup

Restart fastgpt-app, fastgpt-pro, and fastgpt-agent-sandbox-proxy.
Visit https://agent-proxy-domain/health. It should return OK.

4. Deploy a sandbox provider

After deploying the proxy service, connect one of the supported sandbox providers:

Additional Configuration

Custom package mirrors

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

Resource limit variables

Configure the following variables in fastgpt-app and fastgpt-pro when you need to adjust resource limits:

Variable	Default	Description
`AGENT_SANDBOX_CPU_COUNT`	`1`	Maximum CPU count for each Agent Sandbox instance.
`AGENT_SANDBOX_MEMORY_MIB`	`2048`	Maximum memory for each Agent Sandbox instance, in MiB.
`AGENT_SANDBOX_STORAGE_SIZE_GI`	`1`	Agent Sandbox storage size in Gi. FastGPT derives its archive, Skill, and single-file limits as storage in MB / 2 - 150.
`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.

Lifecycle variables

Variable	Default	Description
`AGENT_SANDBOX_SUSPEND_MINUTES`	`60`	Number of inactive minutes before a running Agent Sandbox is suspended.
`AGENT_SANDBOX_ARCHIVE_INACTIVE_DAYS`	`7`	Number of inactive days before a suspended Agent Sandbox is archived.

FAQ

AGENT_SANDBOX_PROXY_URL or AGENT_SANDBOX_PREVIEW_PROXY_URL is required

After Agent Sandbox is enabled, fastgpt-app requires AGENT_SANDBOX_PROXY_SECRET, AGENT_SANDBOX_PROXY_URL, and AGENT_SANDBOX_PREVIEW_PROXY_URL. fastgpt-pro requires only AGENT_SANDBOX_PREVIEW_PROXY_URL. You must add the preview proxy URL, such as https://sandbox-proxy.example.com, to both services.

Browser WebSocket connection fails

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.

proxy validation fails or returns 401

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.

General Sandbox Configuration

On this page