General Sandbox Configuration

This page covers the shared Agent Sandbox configuration for both opensandbox and sealosdevbox . Provider-specific connection settings are documented in each provider page. Regardless of the provider, you need to deploy fastgpt-agent-sandbox-proxy and optionally configure package mirrors for the sandbox runtime.

Base Environment Variables

Add the following environment variables to both fastgpt-app and fastgpt-pro :

# Shared with 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

Deploy fastgpt-agent-sandbox-proxy

fastgpt-agent-sandbox-proxy is the WebSocket proxy between the browser and the sandbox IDE Agent. The browser does not connect to the provider's internal sandbox directly. Instead, it connects to this proxy, which calls back to the FastGPT main service to verify the ticket and then forwards traffic to the target sandbox.

Docker Compose example:

fastgpt-agent-sandbox-proxy:
  image: ghcr.io/labring/fastgpt-agent-sandbox-proxy:v0.2.0
  container_name: fastgpt-agent-sandbox-proxy
  restart: always
  ports:
    - 3006:1006
  networks:
    - app
  environment:
    PORT: 1006
    # Must exactly match AGENT_SANDBOX_PROXY_SECRET in fastgpt-app / fastgpt-pro.
    AGENT_SANDBOX_PROXY_SECRET: replace_with_32_chars_random_secret
    # Internal FastGPT main service URL. Change the service name if your deployment uses a different one.
    FASTGPT_APP_URL: http://fastgpt-app:3000
    # Covers sandbox cold start, agent password reads, and endpoint lookup time.
    FASTGPT_APP_REQUEST_TIMEOUT_SECS: 60
    RUST_LOG: info,fastgpt_agent_sandbox_proxy=debug
    # Configure this only when the upstream sandbox endpoint returns localhost/127.0.0.1 and the proxy container cannot reach it.
    # AGENT_SANDBOX_PROXY_REWRITE_HOST: host.docker.internal

For China Mainland deployments, you can use this image instead:

image: registry.cn-hangzhou.aliyuncs.com/fastgpt/fastgpt-agent-sandbox-proxy:v0.2.0

When deploying the proxy on Sealos, create a new app, use the matching fastgpt-agent-sandbox-proxy image, expose container port 1006 , and configure the environment variables above. The public access URL must support WebSocket Upgrade. Then set AGENT_SANDBOX_PROXY_URL in both fastgpt-app and fastgpt-pro to that public URL using ws:// or wss:// .

proxy Environment Variables

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

This configuration is cached by content hash in the sandbox runtime state. For the same sandbox, FastGPT rewrites the mirror settings only when the configuration changes.

Optional Limit Settings

The following variables usually keep their defaults. Configure them only when you need to change file size limits, WebSocket message limits, or the IDE Agent listening port.

Verification

1. Restart fastgpt-app , fastgpt-pro , and fastgpt-agent-sandbox-proxy .
2. Visit https://your-proxy-domain/health . It should return OK .
3. In FastGPT, open a scenario that supports Agent Sandbox, such as sandbox file editing or terminal access.
4. If you can read files, write files, or open the terminal, the shared configuration is working.

FAQ

AGENT_SANDBOX_PROXY_URL is required

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.

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.