document/content/self-host/upgrading/4-16/41601.en.mdx
Version 4.16.0 requires the proxy for static resource access. If your gateway supports WebSocket and HTTP traffic on the same port, you only need to expose one port. Otherwise, set PREVIEW_PORT to configure the HTTP port.
# Port for the WebSocket and HTTP services
PORT=1006
# HTTP service port; overrides PORT when set
PREVIEW_PORT=1007
The access URL must start with http:// or https://. With a single-port deployment, it can use the same host and port as AGENT_SANDBOX_PROXY_URL, while the protocols remain HTTP(S) and WebSocket(S), respectively. We strongly recommend using a different origin from the main FastGPT site. A same-origin deployment places user-generated scripts inside the main site's security boundary, where they may access site credentials or APIs. FastGPT does not currently enforce origin isolation.
Visit https://{{host}}/health to verify that the service is accessible.
Update the variables in both fastgpt-app and fastgpt-pro.
# HTTP(S) URL used by browsers to preview Sandbox files. Use the URL configured in step 1.
AGENT_SANDBOX_PREVIEW_PROXY_URL=https://sandbox-proxy.example.com
# Required for OpenSandbox. Sets the full storage name prefix (previously configured on the volume image).
VM_VOLUME_NAME_PREFIX=fastgpt-session
AGENT_SANDBOX_DISK_MB and all E2B-related variables.
| Variable | Default | Description |
|---|---|---|
AGENT_SANDBOX_CPU_COUNT | 1 | Maximum CPU cores per Agent Sandbox instance. |
AGENT_SANDBOX_MEMORY_MIB | 2048 | Memory limit per Agent Sandbox instance, in MiB. |
AGENT_SANDBOX_STORAGE_SIZE_GI | 1 | Agent Sandbox storage capacity, in Gi. Used as the Sealos Devbox storage limit and to create new PVCs in OpenSandbox Kubernetes mode. |
AGENT_SANDBOX_SUSPEND_MINUTES | 60 | Number of minutes an active Sandbox can remain idle before it is automatically suspended. |
AGENT_SANDBOX_ARCHIVE_INACTIVE_DAYS | 7 | Number of days a suspended Sandbox can remain inactive before it is automatically archived. |
The E2B Sandbox Provider has been removed. Environments previously configured for E2B must switch to opensandbox or sealosdevbox and remove AGENT_SANDBOX_E2B_API_KEY.
The preview protocols have changed for FastGPT,
fastgpt-agent-sandbox-proxy, andfastgpt-agent-sandbox. When Agent Sandbox is enabled, use the images released with this version. Mixing old and new versions is not supported.
v4.16.0-beta1v4.16.0-beta1v1.1.0-beta1v0.3.0-beta4 (for OpenSandbox only)v0.3.0-beta4 (for Sandbox only)This release changes App Chat's Agent Sandbox from โone instance per sessionโ to โone shared instance per App and user.โ Files from different sessions remain isolated under sessions/<chatId>. Published Skills are stored in the shared projects directory.
If Agent Sandbox was previously enabled, migrate the existing Workspaces in the following order. You can skip this section if Agent Sandbox has never been enabled.
Run a dry run first to see how many beta6 Sandbox fields require normalization and how many legacy Skill Debug Chats require cleanup. The dry run does not create resources, access object storage, or modify data:
curl -X POST 'https://ไฝ ็ๅๅ/api/admin/4160/initUserSandbox' \
-H 'Content-Type: application/json' \
-H 'rootkey: ไฝ ็ROOT_KEY' \
-d '{"dryRun":true}'
After reviewing the dry-run result, run the migration. The migration first performs the beta6 normalization and continues to Workspace archiving in the same request only when no pending normalization work remains:
curl -X POST 'https://ไฝ ็ๅๅ/api/admin/4160/initUserSandbox' \
-H 'Content-Type: application/json' \
-H 'rootkey: ไฝ ็ROOT_KEY' \
-d '{"dryRun":false}'
If every item in failures reports Sandbox source is missing or deleted, and you have confirmed that the corresponding Apps or Skills no longer exist, you can explicitly skip those stale Sandboxes:
curl -X POST 'https://ไฝ ็ๅๅ/api/admin/4160/initUserSandbox' \
-H 'Content-Type: application/json' \
-H 'rootkey: ไฝ ็ROOT_KEY' \
-d '{"dryRun":false,"skipError":true}'
skipError defaults to false, so omitting it preserves strict migration behavior. The switch only skips an entire source group when that source is missing or soft-deleted. Sandboxes in the group are not archived, deleted, or migrated, and are reported through skippedCount and skipped. Archive, object storage, provider, concurrency-control, and all other errors remain blocking.
The migration first runs all V4.15.0-beta6 normalization steps. It fills in sourceType/sourceId for legacy Sandboxes, removes obsolete fields, deletes orphaned resources that cannot be associated, and cleans up the three legacy Skill Debug Chat collections and old private/public Bucket prefixes when sourceType is missing. A Skill whose ID matches an App ID is excluded from Chat cleanup. After recounting, the two categories are combined into normalization.pendingCount; Workspace archiving does not begin while the count is non-zero. Once normalization is complete, all legacy Workspaces are archived, old compute resources are cleaned up, Skills are migrated, and records are aggregated into user-level Sandboxes by App and user. Installation does not start if any archive operation fails. New Sandboxes are suspended after Workspace installation and start normally on first use. The script is safe to retry: completed archive and migration operations are not repeated. Old archives and MongoDB records are retained as backups after migration.
Check normalization.pendingCount, normalizationBlocked, failedCount, failures, skippedCount, and skipped in the response. When both normalization.pendingCount and failedCount are 0 and normalizationBlocked is false, every non-skipped Sandbox has been migrated. Legacy records listed in skipped remain in place and are not migrated.
This release changes array parameters in manually configured HTTP tools to standard JSON Schema. Environments with manual HTTP tools created before the upgrade must run this migration. OpenAPI-mode HTTP tools do not require migration and are skipped automatically.
Run a dry run first to inspect pending data in current Apps and historical versions. The dry run does not modify data:
curl -X POST 'https://ไฝ ็ๅๅ/api/admin/4160/initHttpToolSchema' \
-H 'Content-Type: application/json' \
-H 'rootkey: ไฝ ็ROOT_KEY' \
-d '{"dryRun":true}'
After confirming the result, run the migration:
curl -X POST 'https://ไฝ ็ๅๅ/api/admin/4160/initHttpToolSchema' \
-H 'Content-Type: application/json' \
-H 'rootkey: ไฝ ็ROOT_KEY' \
-d '{"dryRun":false}'
The script first filters Apps by HTTP tool type, then migrates historical versions associated with those appId values. Only manual-mode tools without apiSchemaStr are processed; other Apps and OpenAPI-mode tools are left unchanged. The migration runs in batches and is safe to retry. total.changedDocumentCount in the response shows how many documents require processing. Run another dry run after the migration and confirm that this value is 0.
PASSWORD_LOGIN_LOCK_SECONDS is deprecated. Use PASSWORD_LOGIN_MINUTE_LIMIT_COUNT to control the maximum number of password login attempts allowed per account per minute.metadata, which can be imported as JSON through the API, CSV templates, or Excel templates. Search results and backup exports preserve this field. Template and backup imports accept both .csv and .xlsx files with q, a, index, and metadata headers. q, a, and metadata each use one column, while index may use multiple columns in any order. Excel files must contain a single worksheet with no merged cells. FastGPT reports an invalid file format when it cannot parse a CSV or Excel file correctly.