description: General FastGPT Agent 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](/deploy/sandbox_deploy/agent-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.
| `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`:
```dotenv
# Must match AGENT_SANDBOX_PROXY_SECRET in fastgpt-agent-sandbox-proxy. Use a random secret longer than 32 characters in production.
`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
1. Restart `fastgpt-app`, `fastgpt-pro`, and `fastgpt-agent-sandbox-proxy`.
2. 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:
- [Sealos Cloud Sandbox](./sealosdevbox)
- [OpenSandbox Deployment](./opensandbox)
## 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.
```dotenv
# npm registry used by npm/yarn/pnpm/bun inside Agent Sandbox
| `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.
description: Use self-hosted OpenSandbox with FastGPT Agent Sandbox
title: OpenSandbox Configuration
description: Configure OpenSandbox and Agent Sandbox Proxy for FastGPT
---
import { Alert } from '@/components/docs/Alert';
<Alert icon="⚠️" context="warning">
Note: The OpenSandbox setup does not provide network isolation by default. Add your own network
isolation policy if your deployment requires it.
OpenSandbox does not provide network isolation by default. Add your own network isolation policy
if your environment requires it.
</Alert>
OpenSandbox is suitable when you want to self-host the Agent/Skill sandbox runtime. Before starting, complete [General Sandbox Configuration](./common) and make sure `fastgpt-agent-sandbox-proxy` is deployed. Configure the proxy secret, WebSocket URL, and preview URL in `fastgpt-app`; you must configure the preview URL in `fastgpt-pro`.
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.
<Alert icon="⚠️" context="warning">
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.
</Alert>
## 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.
The OpenSandbox setup flow is below.
[View the latest docker-compose.yml (PgVector, global registries)](/deploy/docker/main/global/docker-compose.pg.yml)
## 1. Add yml services
See [Deploy with Docker Compose](../../deploy/docker.en.mdx) for other vector databases and China Mainland registries.
Use [opensandbox.yml](/deploy/sandbox_deploy/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](./common).
## Environment Variables
The sample uses China Mainland image registries. For deployments outside China Mainland, replace them with:
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.
| `x-volume-manager-auth-token` | Authentication token for `fastgpt-volume-manager`. 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. |
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.
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.
### Agent Sandbox Proxy Service
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.
| `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. |
## 3. Update FastGPT variables
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.
Add or update the following environment variables in both `fastgpt-app` and `fastgpt-pro`:
### 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:
```dotenv
# Enable OpenSandbox as the Agent Sandbox provider
AGENT_SANDBOX_PROVIDER=opensandbox
# Internal URL for FastGPT to access OpenSandbox Server
# OpenSandbox persistent volume size. Effective only when creating new PVCs in Kubernetes mode.
AGENT_SANDBOX_STORAGE_SIZE_GI=1
```
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.
`AGENT_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.
## 4. Start and verify
`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`.
1. Pre-pull the sandbox runtime images:
<Alert icon="⚠️" context="warning">
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.
2. Start or restart the related services:
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.
```bash
docker compose up -d fastgpt-opensandbox-server fastgpt-volume-manager fastgpt-app fastgpt-pro
```
## Additional Configuration
### Custom Package Registries
3. Check service health inside the container network:
Configure package registries in both `fastgpt-app` and `fastgpt-pro` when sandboxes need to install npm or Python dependencies:
OpenSandbox should return `{"status":"healthy"}`, and `fastgpt-volume-manager` should return a health JSON response. See [General Sandbox Configuration](./common) for Agent Sandbox Proxy verification.
### Resource and Lifecycle Settings
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.
| `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 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`.
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
OpenSandbox mode requires deploying `fastgpt-volume-manager` and configuring `AGENT_SANDBOX_OPENSANDBOX_VOLUME_MANAGER_URL` and `AGENT_SANDBOX_OPENSANDBOX_VOLUME_MANAGER_TOKEN` in FastGPT.
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 fails to connect
### The sandbox is created, but the file tree or terminal does not 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://`.
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
### 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`.
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`.
@@ -14,6 +14,7 @@ import { Alert } from '@/components/docs/Alert';
1. FastGPT commercial edition is deployed, and the team has Agent Sandbox access.
2. Request Sealos Devbox connection details from support: Devbox service URL, access token, and runtime image.
3. Follow [OpenSandbox Configuration](./opensandbox) to deploy `fastgpt-agent-sandbox-proxy`.
## Configure FastGPT Environment Variables
...
...
@@ -41,7 +42,7 @@ AGENT_SANDBOX_STORAGE_SIZE_GI=1
### AGENT_SANDBOX_PROXY_URL or AGENT_SANDBOX_PREVIEW_PROXY_URL is required
After `AGENT_SANDBOX_PROVIDER=sealosdevbox` is enabled, `fastgpt-app` requires both `AGENT_SANDBOX_PROXY_URL` and `AGENT_SANDBOX_PREVIEW_PROXY_URL`, while `fastgpt-pro` requires `AGENT_SANDBOX_PREVIEW_PROXY_URL`. See [General Sandbox Configuration](./common) for details.
After `AGENT_SANDBOX_PROVIDER=sealosdevbox` is enabled, `fastgpt-app` requires `AGENT_SANDBOX_PROXY_SECRET`, `AGENT_SANDBOX_PROXY_URL`, and `AGENT_SANDBOX_PREVIEW_PROXY_URL`, while `fastgpt-pro` requires `AGENT_SANDBOX_PREVIEW_PROXY_URL`. The proxy secret must match the value configured for `fastgpt-agent-sandbox-proxy` and contain at least 32 characters.
If the documentation site uses a custom domain, an internal domain, or a local address, set `FASTGPT_DEPLOY_BASE_URL` to choose the download source. You can provide either the site root or a URL ending in `/deploy`; the script downloads YAML and `config.json` from that source:
Non-interactive mode also requires `FASTGPT_FE_DOMAIN`, the full URL users use to access FastGPT, such as `https://fastgpt.example.com`, and `FASTGPT_SANDBOX_PROXY_URL`, the Sandbox WebSocket URL, such as `wss://sandbox-proxy.example.com`. Version 4.16 also requires `FASTGPT_SANDBOX_PREVIEW_PROXY_URL` for the HTTP preview URL. In interactive mode, the script prompts for the addresses required by each version; 4.15 prompts only for the WebSocket URL.
The script automatically:
- Downloads or copies `docker-compose.yml`.
- Downloads `docker-compose.yml`.
- Guides you through selecting externally accessible S3 and MCP addresses, then writes them into the config files.
- Generates a random `root` login password, service tokens, app keys, and component passwords, then writes them into `docker-compose.yml`.
- Detects the host Docker socket path and updates the mount path in `docker-compose.yml` when needed.
...
...
@@ -164,24 +174,26 @@ If you need to pin deployment to a specific `docker-compose.yml` file, we recomm
If Agent/Skill Sandbox is enabled, deploy `fastgpt-agent-sandbox-proxy` separately and also replace `AGENT_SANDBOX_SEALOS_IMAGE` or `AGENT_SANDBOX_OPENSANDBOX_IMAGE` so the sandbox provider can pull the `fastgpt-agent-sandbox` image. The v4.15.0 default deployment file does not include `fastgpt-agent-sandbox-proxy` or start OpenSandbox by default. See the [V4.15.0 upgrade notes](../upgrading/4-15/41500.en.mdx#5-agent-sandbox-deployment-options) for sandbox provider setup.
If Agent/Skill Sandbox is enabled, also replace the sandbox-related images in the Compose file and update `AGENT_SANDBOX_SEALOS_IMAGE` or `AGENT_SANDBOX_OPENSANDBOX_IMAGE` so the sandbox provider can pull the matching images. See [OpenSandbox Configuration](../config/sandbox/opensandbox) for details.
### 2. Modify Environment Variables
You must set `FE_DOMAIN` in `fastgpt-app` to the full URL users use to access FastGPT, such as `https://fastgpt.example.com`. It must include a scheme, host, and optional port; do not leave it empty or use an internal container address.
When Agent/Skill Sandbox is enabled, also configure:
- `AGENT_SANDBOX_PROXY_URL`: the browser-accessible Sandbox Proxy WebSocket URL using `ws://` or `wss://`, such as `wss://sandbox-proxy.example.com`, pointing to port 3006.
- Version 4.16 additionally requires `AGENT_SANDBOX_PREVIEW_PROXY_URL`: the browser-accessible HTTP(S) URL for sandbox file previews, such as `https://sandbox-proxy.example.com`, also pointing to port 3006.
The interactive install script prompts for these addresses before the final confirmation.
For `Zilliz version`, you also need credentials — see [Deploy Zilliz Version: Get Account and Credentials](#deploy-zilliz-version-get-account-and-credentials). Other versions can skip to the next step.
### 3. Open External Ports / Configure Domain
...
...
@@ -224,12 +245,16 @@ These ports must be accessible:
1. Port 3000 (FastGPT main service)
2. Port 9000 (S3 service)
3. Port 3003 (FastGPT SSE MCP server service)
4. Port 3006 (FastGPT Agent Sandbox Proxy service)
### 4. Start Containers
Run in the same directory as docker-compose.yml. Ensure `docker-compose` version is 2.17+, or automated commands may fail.
OpenSandbox and other sandbox provider settings have moved to [Sandbox Configuration](../../config/sandbox/common) and are no longer built into the deployment yml.
See the [4.15 deployment YAML](https://doc.fastgpt.cn/deploy/docker/v4.15/cn/docker-compose.pg.yml) for the complete OpenSandbox setup. The 4.15 Docker Compose deployment file already includes OpenSandbox Server, Volume Manager, Agent Sandbox Proxy, and the image pre-pull services.
For this upgrade, focus on:
1. Deploying the `agent-sandbox-proxy` service.
2. Updating OpenSandbox-related image versions.
3. Updating related environment variables in `fastgpt-app` and `fastgpt-pro`.
1. Using the new Docker Compose deployment file, which includes the OpenSandbox services.
2. Updating OpenSandbox environment variables in `fastgpt-app` and `fastgpt-pro`.
You can overwrite your deployment directly with the new OpenSandbox template.
