description: General FastGPT Agent 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` :
```dotenv
# Shared with fastgpt-agent-sandbox-proxy. Use a random secret longer than 32 characters in production.
| `AGENT_SANDBOX_PROXY_SECRET` | Shared HMAC secret for the main service and `fastgpt-agent-sandbox-proxy` . It must be at least 32 characters, and both services must use the exact same value. |
| `AGENT_SANDBOX_PROXY_URL` | Browser-accessible WebSocket base URL for `fastgpt-agent-sandbox-proxy` . It must start with `ws://` or `wss://` . Do not set this to the FastGPT main site URL. |
## 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.
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://` .
| `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://localhost:3000` | Internal URL of the FastGPT main service. The proxy uses it to call `/api/core/ai/sandbox/verifyTicket` . |
| `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. |
| `AGENT_SANDBOX_PROXY_REWRITE_HOST` | Empty | Rewrites the upstream host when the provider returns a `localhost` or `127.0.0.1` sandbox endpoint that the proxy cannot reach. |
## 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_NPM_REGISTRY` | npm registry used by npm, yarn, pnpm, and bun inside the sandbox. |
| `AGENT_SANDBOX_PYPI_INDEX_URL` | PyPI index URL used by pip, `python -m pip` , and uv inside the sandbox. |
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.
| `IDE_AGENT_BIND_ADDR` | `0.0.0.0:1318` | Listening address for the IDE Agent inside the sandbox. Change it only when using a custom sandbox image or port. |
| `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 size. |
| `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. |
## 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.
After `AGENT_SANDBOX_PROVIDER=sealosdevbox` is enabled, `AGENT_SANDBOX_PROXY_URL` is required. This is the browser-accessible WebSocket URL for the proxy service, such as `wss://sandbox-proxy.example.com` . It is not the FastGPT main site URL.
### AGENT_SANDBOX_SEALOS_IMAGE is required
The `sealosdevbox` provider requires `AGENT_SANDBOX_SEALOS_IMAGE` . Use the Agent Sandbox runtime image provided by support or the image that matches your current FastGPT version.
### 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.
### 1. Run the Workflow V1 to V2 Migration (Optional)
This is the final beta release before the 4.15.0 stable release. If you deployed any 4.15.0-beta version, upgrade to this version first, complete all upgrade steps introduced during the beta period, and then update all images to the stable release. See [4.15.0](./41500.mdx) for the stable release images.
- Update the fastgpt-app (FastGPT main service) image tag to v4.15.0-beta7.
- Update the fastgpt-pro (FastGPT Commercial Edition) image tag to v4.15.0-beta7.
### 4. Run the Workflow V1 to V2 Migration (Optional)
Only users who have deployed a FastGPT version earlier than `<4.8` need to run this step.
...
...
@@ -46,7 +96,7 @@ Migration behavior:
5. Missing `node.name` falls back to `flowType`, and missing `input.label` falls back to `input.key`.
6. Before writing, the script validates `nodes`, `edges`, and `chatConfig` with `PublishAppBodySchema`. Documents that fail validation are not written and are included in the endpoint response.
### 2. Run the Workflow V2 Enum and Structure Cleanup
### 5. Run the Workflow V2 Enum and Structure Cleanup
Some historical workflow nodes may have stored TypeScript enum expression strings directly in MongoDB, for example:
...
...
@@ -104,12 +154,13 @@ Cleanup behavior:
The response includes separate statistics for `apps`, `appVersions`, and `total`, including scanned documents, fixable documents, Zod error count, successful writes, failed writes, enum expression statistics, change samples, and error samples.
### 3. Update Images
## ⚙️ Optimizations
See the [4.15.0 stable image tags](./41500.mdx) and update all images to the stable release.
1. Virtual machine file URLs now use the new API.
## 🐛 Fixes
1. Fixed historical V1 workflow data that could fail validation under the new save payload structure.
2. Fixed dirty `FlowNodeInputTypeEnum.*`, `FlowNodeOutputTypeEnum.*`, and `WorkflowIOValueTypeEnum.*` expression strings in workflow node configuration that could break input rendering and IO type checks.
3. Fixed AgentV2 MCP not being able to retrieve schemas.
4. Fixed variable updates not being written back at the end of batch execution nodes.
