OpenSandbox Deployment

OpenSandbox is suitable when you want to self-host the Agent/Skill sandbox runtime. Before starting, complete General Sandbox Configuration, make sure fastgpt-agent-sandbox-proxy is deployed, and configure the same AGENT_SANDBOX_PROXY_SECRET and browser-accessible AGENT_SANDBOX_PROXY_URL in both fastgpt-app and fastgpt-pro.

The OpenSandbox setup flow is below.

1. Add yml services

Use opensandbox.yml as a reference. Add fastgpt-opensandbox-server, fastgpt-volume-manager, the image pre-pull services, and opensandbox-config to your current FastGPT docker-compose.yml. Place them on the same app network as the FastGPT App service. You do not need to expose OpenSandbox or Volume Manager ports publicly. Deploy Agent Sandbox Proxy separately as described in General Sandbox Configuration.

The sample uses China Mainland image registries. For deployments outside China Mainland, replace them with:

• opensandbox/server:v0.1.9
• ghcr.io/labring/fastgpt-agent-sandbox:v0.2.0
• opensandbox/execd:v1.0.6
• opensandbox/egress:v1.0.1
• ghcr.io/labring/fastgpt-agent-volume-manager:v0.2.0

2. Update OpenSandbox variables

Only the following values usually need to be changed:

Docker runtime requires mounting the host Docker socket. The default Docker path is usually /var/run/docker.sock; environments such as OrbStack may require replacing it with the actual socket path.

If the server has HTTP_PROXY / HTTPS_PROXY configured, set NO_PROXY / no_proxy for OpenSandbox Server and Volume Manager. Include at least localhost,127.0.0.1,127.0.0.0/8,fastgpt-opensandbox-server,fastgpt-volume-manager,host.docker.internal to prevent internal service calls from being routed through the proxy. OrbStack/Docker may inject IPv6 CIDR entries into NO_PROXY; httpx used by OpenSandbox may parse unbracketed IPv6 CIDR values as invalid URL ports. Explicitly override NO_PROXY if you hit that startup issue.

3. Update FastGPT variables

Add or update the following environment variables in both fastgpt-app and fastgpt-pro:

# Enable OpenSandbox as the Agent Sandbox provider
AGENT_SANDBOX_PROVIDER=opensandbox

# Internal URL for FastGPT to access OpenSandbox Server
AGENT_SANDBOX_OPENSANDBOX_BASEURL=http://fastgpt-opensandbox-server:8090
# OpenSandbox API key. Must match [server].api_key in opensandbox-config.
AGENT_SANDBOX_OPENSANDBOX_API_KEY=replace_with_opensandbox_api_key
# Docker compose deployments use docker runtime
AGENT_SANDBOX_OPENSANDBOX_RUNTIME=docker
# Runtime image used when OpenSandbox creates Agent Sandbox instances
AGENT_SANDBOX_OPENSANDBOX_IMAGE_REPO=registry.cn-hangzhou.aliyuncs.com/fastgpt/fastgpt-agent-sandbox
AGENT_SANDBOX_OPENSANDBOX_IMAGE_TAG=v0.2.0
AGENT_SANDBOX_OPENSANDBOX_USE_SERVER_PROXY=true
# Persistent volume manager URL and token. The token must match x-volume-manager-auth-token.
AGENT_SANDBOX_OPENSANDBOX_VOLUME_MANAGER_URL=http://fastgpt-volume-manager:3000
AGENT_SANDBOX_OPENSANDBOX_VOLUME_MANAGER_TOKEN=replace_with_volume_manager_token

If your docker-compose.yml already uses x-agent-sandbox-config to inject Agent Sandbox variables, fill these values in that anchor so both fastgpt-app and fastgpt-pro inherit the same configuration.

4. Start and verify

1. Pre-pull the sandbox runtime images:

docker compose --profile prepull pull opensandbox-agent-sandbox-image opensandbox-execd-image opensandbox-egress-image

2. Start or restart the related services:

docker compose up -d fastgpt-opensandbox-server fastgpt-volume-manager fastgpt-app fastgpt-pro

3. Check service health inside the container network:

docker compose exec fastgpt-opensandbox-server python -c "import urllib.request; print(urllib.request.urlopen('http://localhost:8090/health', timeout=5).read().decode())"
docker compose exec fastgpt-volume-manager node -e "fetch('http://localhost:3000/health').then(async r => { console.log(await r.text()); if (!r.ok) process.exit(1); })"

OpenSandbox should return OK, and fastgpt-volume-manager should return a health JSON response. See General Sandbox Configuration for Agent Sandbox Proxy verification.

4. Log in to FastGPT and open a scenario that supports Agent Sandbox, such as Agent V2 VM, Skill editing, or Skill debugging. Confirm that the sandbox can be created and that the file tree and terminal open normally.

FAQ

Sandbox provider apiKey is required for opensandbox

Check that both fastgpt-app and fastgpt-pro have AGENT_SANDBOX_OPENSANDBOX_API_KEY configured, and make sure it matches [server].api_key in opensandbox-config.

AGENT_SANDBOX_OPENSANDBOX_VOLUME_MANAGER_URL is required

OpenSandbox mode requires deploying fastgpt-volume-manager and configuring AGENT_SANDBOX_OPENSANDBOX_VOLUME_MANAGER_URL and AGENT_SANDBOX_OPENSANDBOX_VOLUME_MANAGER_TOKEN in FastGPT.

The sandbox is created, but the file tree or terminal fails to connect

Check that AGENT_SANDBOX_PROXY_URL is a browser-accessible ws:// or wss:// URL and that your reverse proxy supports WebSocket Upgrade. If the FastGPT main site uses HTTPS, the proxy URL should use wss://.

proxy cannot connect to the sandbox endpoint

Check [docker].host_ip in opensandbox-config first. When OpenSandbox Server runs in a container, sandbox endpoints using localhost or 127.0.0.1 are not reachable from the proxy container. Use the host's internal IP or host.docker.internal.