diff --git a/docs/en/use/astrbot-agent-sandbox.md b/docs/en/use/astrbot-agent-sandbox.md
index 05940b6dcc..05e02f88b9 100644
--- a/docs/en/use/astrbot-agent-sandbox.md
+++ b/docs/en/use/astrbot-agent-sandbox.md
@@ -9,68 +9,381 @@ Starting from version `v4.12.0`, AstrBot introduced the Agent sandbox environmen
 
 ## Enabling the Sandbox Environment
 
-Currently, the sandbox environment only supports running through Docker. We are currently using the [Shipyard](https://github.com/AstrBotDevs/shipyard) project as AstrBot's sandbox environment driver. In the future, we will support more types of sandbox environment drivers, such as e2b.
+AstrBot currently supports the following sandbox drivers:
+
+- `Shipyard Neo` (recommended)
+- `Shipyard` (legacy option, still supported)
+
+In the current AstrBot console, go to **AI Settings** -> **Agent Computer Use** and select:
+
+- `Computer Use Runtime` = `sandbox`
+- `Sandbox Driver` = `Shipyard Neo` or `Shipyard`
+
+`Shipyard Neo` is now the default driver. It consists of Bay, Ship, and Gull:
+
+- **Bay**: the control-plane API responsible for creating and managing sandboxes
+- **Ship**: provides Python / Shell / filesystem capabilities
+- **Gull**: provides browser automation capabilities
+
+For `Shipyard Neo`, the workspace root is fixed at `/workspace`. When using filesystem tools in AstrBot, you should pass **paths relative to the workspace root**, for example `reports/result.txt`, not `/workspace/reports/result.txt`.
+
+> [!TIP]
+> Browser capability is not available in every `Shipyard Neo` profile. AstrBot only mounts browser-related tools when the selected profile supports the `browser` capability. A typical example is `browser-python`.
+
+## Performance Requirements
+
+AstrBot limits each sandbox instance to at most 1 CPU and 512 MB of memory.
+
+We recommend that your host machine have at least 2 CPUs, 4 GB of memory, and swap enabled, so multiple sandbox instances can run more reliably.
+
+## Recommended: Use Shipyard Neo
+
+### Deploy Shipyard Neo Separately (Recommended)
+
+If you plan to use `Shipyard Neo` for the long term, it is generally better to **deploy it separately on a machine with more resources**, such as your homelab, a LAN server, or a dedicated cloud host, and then let AstrBot connect to Bay remotely.
+
+The reason is that `Shipyard Neo` can become fairly resource-heavy when browser capability is enabled, because it needs to run a full browser runtime. On resource-constrained cloud servers, deploying AstrBot and `Shipyard Neo` on the same machine usually puts significant pressure on CPU and memory, which can negatively affect both stability and overall experience.
+
+A basic deployment flow looks like this:
+
+```bash
+git clone https://github.com/AstrBotDevs/shipyard-neo
+cd shipyard-neo/deploy/docker
+# Modify the key settings in config.yaml, such as security.api_key
+docker compose up -d
+```
+
+After deployment:
+
+- Bay listens on `http://<your-host>:8114` by default
+- In the AstrBot console, choose the `Shipyard Neo` driver
+- Set `Shipyard Neo API Endpoint` to the corresponding address, for example `http://<your-host>:8114`
+- Set `Shipyard Neo Access Token` to the Bay API key; if AstrBot can access Bay's `credentials.json`, you may also leave it empty and let AstrBot auto-discover it
+
+### Reference: Full `config.yaml` Example (with Notes)
+
+If you want to customize the deployment parameters of `Shipyard Neo`, you can refer to the complete example below, adapted from [`deploy/docker/config.yaml`](https://github.com/AstrBotDevs/shipyard-neo/blob/main/deploy/docker/config.yaml). It keeps the default structure and adds explanatory notes to make each option easier to understand.
+
+> [!TIP]
+> The minimum required change is `security.api_key`. If you are not sure what the other options do, it is usually best to keep the defaults first and only adjust profiles, resource limits, and warm pool settings as needed.
+
+```yaml
+# Bay Production Config - Docker Compose (container_network mode)
+#
+# Bay runs inside Docker and communicates with Ship/Gull containers
+# through a shared Docker network.
+# In this mode, sandbox containers do not need to expose ports to the host.
+#
+# At minimum, update:
+#   1. security.api_key  — set a strong random secret
+
+server:
+  # Bay API listen address
+  host: "0.0.0.0"
+  # Bay API listen port
+  port: 8114
+
+database:
+  # SQLite is the default for single-node deployment.
+  # For multi-instance / HA deployments, you can switch to PostgreSQL, for example:
+  # url: "postgresql+asyncpg://user:pass@db-host:5432/bay"
+  url: "sqlite+aiosqlite:///./data/bay.db"
+  echo: false
+
+driver:
+  # Docker is the default driver
+  type: docker
+
+  # Whether to pull images when creating new sandboxes.
+  # In production, always is usually recommended so you get the latest images.
+  image_pull_policy: always
+
+  docker:
+    # Docker Socket endpoint
+    socket: "unix:///var/run/docker.sock"
+
+    # When Bay, Ship, and Gull all run in containers,
+    # container_network is recommended for direct container-network communication.
+    connect_mode: container_network
+
+    # Shared network name; must match the network in docker-compose.yaml
+    network: "bay-network"
+
+    # Whether to expose sandbox container ports to the host.
+    # Disabling this is generally recommended in production.
+    publish_ports: false
+    host_port: null
+
+cargo:
+  # Cargo storage root path on the Bay side
+  root_path: "/var/lib/bay/cargos"
+  # Default workspace size limit (MB)
+  default_size_limit_mb: 1024
+  # Path mounted inside the sandbox. This is AstrBot/Neo's workspace root.
+  mount_path: "/workspace"
+
+security:
+  # Required: set a strong random secret, for example openssl rand -hex 32
+  api_key: "CHANGE-ME"
+  # Whether anonymous access is allowed. false is recommended for production.
+  allow_anonymous: false
+
+# Proxy environment variable injection for containers.
+# When enabled, Bay injects HTTP(S)_PROXY and NO_PROXY into sandbox containers.
+proxy:
+  enabled: false
+  # http_proxy: "http://proxy.example.com:7890"
+  # https_proxy: "http://proxy.example.com:7890"
+  # no_proxy: "my-internal.service"
+
+# Warm Pool: keep standby sandboxes pre-warmed to reduce cold-start latency.
+# When a user creates a sandbox, Bay will first try to claim a pre-warmed instance.
+warm_pool:
+  enabled: true
+  # Number of warmup queue workers
+  warmup_queue_workers: 2
+  # Maximum warmup queue size
+  warmup_queue_max_size: 256
+  # Policy when the queue is full
+  warmup_queue_drop_policy: "drop_newest"
+  # Useful threshold for operational alerts
+  warmup_queue_drop_alert_threshold: 50
+  # Warm pool maintenance interval (seconds)
+  interval_seconds: 30
+  # Whether to start warm-pool maintenance when Bay starts
+  run_on_startup: true
+
+profiles:
+  # ── Standard Python sandbox ────────────────────────
+  - id: python-default
+    description: "Standard Python sandbox with filesystem and shell access"
+    image: "ghcr.io/astrbotdevs/shipyard-neo-ship:latest"
+    runtime_type: ship
+    runtime_port: 8123
+    resources:
+      cpus: 1.0
+      memory: "1g"
+    capabilities:
+      - filesystem  # includes upload/download
+      - shell
+      - python
+    # Idle timeout (seconds)
+    idle_timeout: 1800
+    # Keep 1 warm instance ready
+    warm_pool_size: 1
+    env: {}
+    # Optional profile-level proxy override
+    # proxy:
+    #   enabled: false
+
+  # ── Data-science sandbox (more resources) ──────────
+  - id: python-data
+    description: "Data science sandbox with extra CPU and memory"
+    image: "ghcr.io/astrbotdevs/shipyard-neo-ship:latest"
+    runtime_type: ship
+    runtime_port: 8123
+    resources:
+      cpus: 2.0
+      memory: "4g"
+    capabilities:
+      - filesystem  # includes upload/download
+      - shell
+      - python
+    idle_timeout: 1800
+    warm_pool_size: 1
+    env: {}
+
+  # ── Browser + Python multi-container sandbox ───────
+  - id: browser-python
+    description: "Browser automation with Python backend"
+    containers:
+      - name: ship
+        image: "ghcr.io/astrbotdevs/shipyard-neo-ship:latest"
+        runtime_type: ship
+        runtime_port: 8123
+        resources:
+          cpus: 1.0
+          memory: "1g"
+        capabilities:
+          - python
+          - shell
+          - filesystem  # includes upload/download
+        # These capabilities are primarily handled by the ship container
+        primary_for:
+          - filesystem
+          - python
+          - shell
+        env: {}
+      - name: browser
+        image: "ghcr.io/astrbotdevs/shipyard-neo-gull:latest"
+        runtime_type: gull
+        runtime_port: 8115
+        resources:
+          cpus: 1.0
+          memory: "2g"
+        capabilities:
+          - browser
+        env: {}
+    idle_timeout: 1800
+    warm_pool_size: 1
+
+gc:
+  # Automatic GC is recommended in production
+  enabled: true
+  run_on_startup: true
+  # GC interval (seconds)
+  interval_seconds: 300
+
+  # Must be unique in multi-instance deployments
+  instance_id: "bay-prod"
+
+  idle_session:
+    enabled: true
+  expired_sandbox:
+    enabled: true
+  orphan_cargo:
+    enabled: true
+  orphan_container:
+    # Recommended in production to clean up leaked containers
+    enabled: true
+```
+
+A practical way to think about this file:
+
+- **Minimum required change**: `security.api_key`
+- **Most commonly adjusted options**: resource limits, `warm_pool_size`, and `idle_timeout` under `profiles`
+- **If you need browser capability**: use or customize the `browser-python` profile
+- **If you want to reduce cold-start time**: keep `warm_pool.enabled: true` and increase `warm_pool_size` for frequently used profiles
+- **If resources are limited**: reduce `warm_pool_size`, or even disable `warm_pool`
+- **If outbound proxy access is needed**: configure the top-level `proxy`, or override it per profile
+
+### About Shipyard Neo Reuse and Persistence
+
+`Shipyard Neo` has several important concepts:
+
+- **Sandbox**: the stable, externally visible resource unit
+- **Session**: the actual running container session, which may be stopped or rebuilt
+- **Cargo**: the persistent workspace volume mounted at `/workspace`
+
+From AstrBot's perspective, the current implementation caches the sandbox booter by request `session_id`; in the default main-agent flow, this `session_id` usually equals the message-session identifier `unified_msg_origin`. As a result, follow-up requests from the same message session will usually continue using the same Neo sandbox; if the sandbox becomes unavailable, it will be rebuilt automatically.
+
+For more detailed explanations of TTL and persistence behavior, see the later sections on [`Shipyard Neo Sandbox TTL`](docs/en/use/astrbot-agent-sandbox.md) and [`Data Persistence in the Sandbox Environment`](docs/en/use/astrbot-agent-sandbox.md).
+
+## Legacy Option: Shipyard
+
+The following content describes the older `Shipyard` driver. It is kept for compatibility with existing legacy deployments.
 
 ### Deploying AstrBot and Shipyard with Docker Compose
 
-If you haven't deployed AstrBot yet, or want to switch to our recommended deployment method with sandbox environment, we recommend using Docker Compose to deploy AstrBot with the following code:
+If you have not deployed AstrBot yet, or want to use the older recommended deployment method with sandbox support, you can still deploy AstrBot with Docker Compose using the following commands:
 
 ```bash
 git clone https://github.com/AstrBotDevs/AstrBot
 cd AstrBot
-# Modify the environment variable configuration in the compose-with-shipyard.yml file, such as Shipyard's access token, etc.
+# Modify the environment variables in compose-with-shipyard.yml, such as the Shipyard access token
 docker compose -f compose-with-shipyard.yml up -d
 docker pull soulter/shipyard-ship:latest
 ```
 
-This will start a Docker Compose service that includes AstrBot main program and the sandbox environment.
+This starts a Docker Compose stack containing the AstrBot main program and the sandbox environment.
 
 ### Deploying Shipyard Separately
 
-If you have already deployed AstrBot but haven't deployed the sandbox environment, you can deploy Shipyard separately.
-
-Code as follows:
+If AstrBot is already deployed but the sandbox environment is not, you can deploy Shipyard separately.
 
 ```bash
 mkdir astrbot-shipyard
 cd astrbot-shipyard
 wget https://raw.githubusercontent.com/AstrBotDevs/shipyard/refs/heads/main/pkgs/bay/docker-compose.yml -O docker-compose.yml
-# Modify the environment variable configuration in the compose-with-shipyard.yml file, such as Shipyard's access token, etc.
+# Modify the environment variables in docker-compose.yml, such as the Shipyard access token
 docker compose -f docker-compose.yml up -d
-# pull the latest Shipyard ship image
 docker pull soulter/shipyard-ship:latest
 ```
 
-After successful deployment, the above command will start a Shipyard service that listens on `http://<your-host>:8156` by default.
+After successful deployment, Shipyard listens on `http://<your-host>:8156` by default.
 
 > [!TIP]
-> If you deploy AstrBot using Docker, you can also modify the Compose file above to place Shipyard's network in the same Docker network as AstrBot, so you don't need to expose Shipyard's port to the host machine.
+> If you deploy AstrBot with Docker, you can also place Shipyard on the same Docker network as AstrBot so you do not need to expose Shipyard's port to the host.
 
 ## Configuring AstrBot to Use the Sandbox Environment
 
-In the AstrBot console, go to the "Configuration Files" page and find "Agent Sandbox Environment", then enable the sandbox environment switch.
+> [!TIP]
+> Please make sure your AstrBot version is `v4.12.0` or later.
+
+In the AstrBot console, go to **AI Settings** -> **Agent Computer Use**.
+
+1. Set `Computer Use Runtime` to `sandbox`
+2. Select `Shipyard Neo` or `Shipyard` as the sandbox driver
+3. Fill in the corresponding configuration values for the selected driver
+4. Click **Save**
 
-In the configuration options that appear:
+### Configuring Shipyard Neo
 
-For `Shipyard API Endpoint`, if you use the Docker Compose deployment method above, fill in `http://shipyard:8156`. If you deployed Shipyard separately, please fill in the corresponding address, such as `http://<your-host>:8156`.
+If you choose `Shipyard Neo`, the main configuration items are:
 
-For `Shipyard Access Token`, please fill in the access token you configured when deploying Shipyard.
+- `Shipyard Neo API Endpoint`
+  - For a separated deployment, use the actual address, such as `http://<your-host>:8114`
+- `Shipyard Neo Access Token`
+  - Fill in the Bay API key
+  - If AstrBot can access Bay's `credentials.json`, you may leave it empty and let AstrBot auto-discover it
+- `Shipyard Neo Profile`
+  - For example `python-default` or `browser-python`
+  - If not explicitly specified, AstrBot will try to choose a profile with richer capabilities, preferring one that includes the `browser` capability, and fall back to `python-default` if needed
+- `Shipyard Neo Sandbox TTL`
+  - The upper lifetime limit of the sandbox, defaulting to 3600 seconds (1 hour)
 
-For `Shipyard Ship Lifetime (seconds)`, this defines the lifetime of each sandbox environment instance, with a default value of 3600 seconds (1 hour). You can adjust this value as needed.
+### Configuring Shipyard (Legacy)
 
-For `Shipyard Ship Session Reuse Limit`, this defines the maximum number of sessions that each sandbox environment instance can reuse, with a default value of 10. This means that 10 sessions will share the same sandbox environment instance. You can adjust this value as needed.
+If you choose the legacy `Shipyard` driver, the relevant configuration items are:
 
-After configuring, click the "Save" button at the bottom of the page to save the configuration.
+- `Shipyard API Endpoint`
+  - If you use the Docker Compose deployment above, set it to `http://shipyard:8156`
+  - If Shipyard is deployed separately, use the corresponding address, such as `http://<your-host>:8156`
+- `Shipyard Access Token`
+  - Fill in the access token you configured when deploying Shipyard
+- `Shipyard Ship Lifetime (seconds)`
+  - Defines the lifetime of each sandbox instance, default 3600 seconds (1 hour)
+- `Shipyard Ship Session Reuse Limit`
+  - Defines the maximum number of sessions that can reuse the same sandbox instance, default 10
+
+## About `Shipyard Neo Sandbox TTL`
+
+In `Shipyard Neo`:
+
+- TTL represents the upper lifetime bound of the sandbox
+- The selected profile also defines a separate idle timeout (`idle_timeout`)
+- Capability calls from AstrBot usually refresh the idle timeout, rather than directly extending the TTL
+- `keepalive` only extends the idle timeout; it does not automatically start a new session and does not extend the TTL
 
 ## About `Shipyard Ship Lifetime (seconds)`
 
-The lifetime of a sandbox environment instance defines the maximum time each instance can exist before being destroyed. This setting needs to be determined based on your usage scenario and resources.
+The following explanation applies only to the legacy `Shipyard` driver:
+
+The lifetime of a sandbox instance defines the maximum amount of time that instance can exist before being destroyed. This value should be chosen according to your use case and available resources.
 
-- When a new session joins an existing sandbox environment instance, the instance will automatically extend its lifetime to the TTL requested by this session.
-- When an operation is performed on a sandbox environment instance, the instance will automatically extend its lifetime to the current time plus the TTL.
+- When a new session joins an existing sandbox instance, the instance automatically extends its lifetime to the TTL requested by that session
+- When an operation is performed on a sandbox instance, the instance automatically extends its lifetime to the current time plus TTL
 
 ## About Data Persistence in the Sandbox Environment
 
-Shipyard allocates a working directory for each session under the `/home/<unique session ID>` directory.
+### Shipyard Neo
+
+The workspace root of `Shipyard Neo` is fixed at `/workspace`.
+
+Persistence is provided by Cargo:
+
+- Filesystem data is stored in Cargo and mounted at `/workspace`
+- Even if the underlying Session is stopped or rebuilt, the data in Cargo is usually retained
+- For profiles with browser capability, browser state may also be persisted together, for example under `/workspace/.browser/profile/`
+
+### Shipyard (Legacy)
+
+Shipyard allocates a working directory for each session under `/home/<unique session ID>`.
+
+Shipyard automatically mounts the `/home` directory from the sandbox environment to `${PWD}/data/shipyard/ship_mnt_data` on the host. When a sandbox instance is destroyed and a session later requests the sandbox again, Shipyard recreates a new instance and remounts the previously persisted data to preserve continuity.
+
+## Other Community Plugins
+
+### luosheng520qaq/astrobot_plugin_code_executor
 
-Shipyard automatically mounts the /home directory in the sandbox environment to the `${PWD}/data/shipyard/ship_mnt_data` directory on the host machine. When a sandbox environment instance is destroyed, if a session continues to request the sandbox, Shipyard will recreate a new sandbox environment instance and remount the previously persisted data to ensure data continuity.
+If your resources are limited and you do not want to use the sandbox environment for code execution, you can try the [astrobot_plugin_code_executor](https://github.com/luosheng520qaq/astrobot_plugin_code_executor) plugin developed by luosheng520qaq. This plugin executes code directly on the host machine. It tries to improve safety as much as possible, but you should still pay close attention to code-execution security.
diff --git a/docs/zh/use/astrbot-agent-sandbox.md b/docs/zh/use/astrbot-agent-sandbox.md
index 68bbdec162..c6e2847c52 100644
--- a/docs/zh/use/astrbot-agent-sandbox.md
+++ b/docs/zh/use/astrbot-agent-sandbox.md
@@ -9,7 +9,26 @@
 
 ## 启用沙盒环境
 
-目前，沙盒环境仅支持通过 Docker 来运行。我们目前使用了 [Shipyard](https://github.com/AstrBotDevs/shipyard) 项目作为 AstrBot 的沙盒环境驱动器。未来，我们会支持更多类型的沙盒环境驱动器，如 e2b。
+目前，AstrBot 的沙盒环境驱动器支持：
+
+- `Shipyard Neo`（当前推荐）
+- `Shipyard`（旧方案，仍可继续使用）
+
+在当前版本的 AstrBot 控制台中，可在“AI 配置” -> “Agent Computer Use”中选择：
+
+- `Computer Use Runtime` = `sandbox`
+- `沙箱环境驱动器` = `Shipyard Neo` 或 `Shipyard`
+
+其中，`Shipyard Neo` 是当前默认驱动器。它由 Bay、Ship、Gull 三部分组成：
+
+- **Bay**：控制面 API，负责创建和管理 sandbox
+- **Ship**：负责 Python / Shell / 文件系统能力
+- **Gull**：负责浏览器自动化能力
+
+对于 `Shipyard Neo`，工作区根目录固定为 `/workspace`。在 AstrBot 中调用文件系统工具时，应当传入**相对于工作区根目录**的路径，例如 `reports/result.txt`，而不是 `/workspace/reports/result.txt`。
+
+> [!TIP]
+> `Shipyard Neo` 下浏览器能力并不是所有 profile 都有。只有 profile 支持 `browser` capability 时，AstrBot 才会挂载浏览器相关工具。典型 profile 如 `browser-python`。
 
 ## 性能要求
 
@@ -17,6 +36,242 @@ AstrBot 给每个沙盒环境限制最高 1 CPU 和 512 MB 内存。
 
 我们建议您的宿主机至少有 2 个 CPU 和 4 GB 内存，并开启 Swap，以保证多个沙盒环境实例可以稳定运行。
 
+## 推荐：使用 Shipyard Neo
+
+### 单独部署 Shipyard Neo（推荐）
+
+如果您准备长期使用 `Shipyard Neo`，更推荐将它**单独部署在一台资源更充足的机器上**，例如您的 homelab、局域网服务器，或独立云主机，然后再让 AstrBot 远程接入 Bay。
+
+原因是：`Shipyard Neo` 在启用浏览器能力时需要运行较重的浏览器运行时。对于资源紧张的云服务器，把 AstrBot 和 `Shipyard Neo` 部署在同一台机器上，通常会让 CPU 和内存压力都比较大，稳定性和体验都不理想。
+
+大致步骤如下：
+
+```bash
+git clone https://github.com/AstrBotDevs/shipyard-neo
+cd shipyard-neo/deploy/docker
+# 修改 config.yaml 中的关键配置，例如 security.api_key
+docker compose up -d
+```
+
+部署完成后：
+
+- Bay 默认监听在 `http://<your-host>:8114`
+- 在 AstrBot 控制台中选择 `Shipyard Neo` 驱动器
+- `Shipyard Neo API Endpoint` 填写对应地址，例如 `http://<your-host>:8114`
+- `Shipyard Neo Access Token` 填写 Bay API Key；如果 AstrBot 能访问 Bay 的 `credentials.json`，也可以留空让 AstrBot 自动发现
+
+### 参考：`config.yaml` 完整示例（附说明）
+
+如果您准备自行调整 `Shipyard Neo` 的部署参数，可以直接参考下面这份基于 [`deploy/docker/config.yaml`](https://github.com/AstrBotDevs/shipyard-neo/blob/main/deploy/docker/config.yaml) 整理的完整示例。它保留了默认结构，并额外加上了中文注释，便于理解每个配置项的用途。
+
+> [!TIP]
+> 其中最少需要修改的是 `security.api_key`。如果不清楚其他参数的作用，建议先保持默认值，仅按需调整 profile、资源限制和 warm pool 配置。
+
+```yaml
+# Bay Production Config - Docker Compose (container_network mode)
+#
+# Bay 运行在 Docker 容器中，并通过共享 Docker 网络与 Ship/Gull 容器通信。
+# 这种模式下，sandbox 容器不需要向宿主机暴露端口。
+#
+# 部署前至少需要修改：
+#   1. security.api_key  —— 设置强随机密钥
+
+server:
+  # Bay API 监听地址
+  host: "0.0.0.0"
+  # Bay API 监听端口
+  port: 8114
+
+database:
+  # 单机部署默认使用 SQLite。
+  # 如果要做多实例 / 高可用，可改用 PostgreSQL，例如：
+  # url: "postgresql+asyncpg://user:pass@db-host:5432/bay"
+  url: "sqlite+aiosqlite:///./data/bay.db"
+  echo: false
+
+driver:
+  # 当前默认使用 Docker 驱动
+  type: docker
+
+  # 创建新 sandbox 时是否拉取镜像。
+  # 生产环境通常建议 always，以便拿到最新镜像。
+  image_pull_policy: always
+
+  docker:
+    # Docker Socket 地址
+    socket: "unix:///var/run/docker.sock"
+
+    # Bay 在容器内运行，Ship/Gull 也在容器内运行时，
+    # 推荐使用 container_network 通过容器网络直接通信。
+    connect_mode: container_network
+
+    # 共享网络名，必须与 docker-compose.yaml 中的网络一致
+    network: "bay-network"
+
+    # 是否将 sandbox 容器端口暴露到宿主机。
+    # 生产环境建议关闭，以减少攻击面。
+    publish_ports: false
+    host_port: null
+
+cargo:
+  # Cargo 在 Bay 侧的存储根路径
+  root_path: "/var/lib/bay/cargos"
+  # 默认工作区大小限制（MB）
+  default_size_limit_mb: 1024
+  # Cargo 挂载到 sandbox 内的路径。AstrBot/Neo 的工作区根目录就是这里。
+  mount_path: "/workspace"
+
+security:
+  # 必改项：设置一个强随机密钥，例如 openssl rand -hex 32
+  api_key: "CHANGE-ME"
+  # 是否允许匿名访问。生产环境建议 false。
+  allow_anonymous: false
+
+# 容器代理环境变量注入。
+# 启用后，Bay 会把 HTTP(S)_PROXY 和 NO_PROXY 注入到 sandbox 容器。
+proxy:
+  enabled: false
+  # http_proxy: "http://proxy.example.com:7890"
+  # https_proxy: "http://proxy.example.com:7890"
+  # no_proxy: "my-internal.service"
+
+# Warm Pool：预热一批待命 sandbox，减少冷启动延迟。
+# 当用户创建 sandbox 时，Bay 会优先尝试领取一个已预热实例。
+warm_pool:
+  enabled: true
+  # 预热队列 worker 数量
+  warmup_queue_workers: 2
+  # 预热队列最大长度
+  warmup_queue_max_size: 256
+  # 队列满时的丢弃策略
+  warmup_queue_drop_policy: "drop_newest"
+  # 超过这个阈值时便于运维告警
+  warmup_queue_drop_alert_threshold: 50
+  # 预热池维护扫描周期（秒）
+  interval_seconds: 30
+  # Bay 启动时是否立即运行预热逻辑
+  run_on_startup: true
+
+profiles:
+  # ── 标准 Python 沙箱 ────────────────────────
+  - id: python-default
+    description: "Standard Python sandbox with filesystem and shell access"
+    image: "ghcr.io/astrbotdevs/shipyard-neo-ship:latest"
+    runtime_type: ship
+    runtime_port: 8123
+    resources:
+      cpus: 1.0
+      memory: "1g"
+    capabilities:
+      - filesystem  # 包含 upload/download
+      - shell
+      - python
+    # 空闲超时（秒）
+    idle_timeout: 1800
+    # 保持 1 个预热实例
+    warm_pool_size: 1
+    env: {}
+    # 可选：profile 级代理覆盖
+    # proxy:
+    #   enabled: false
+
+  # ── 数据科学沙箱（更多资源） ──────────
+  - id: python-data
+    description: "Data science sandbox with extra CPU and memory"
+    image: "ghcr.io/astrbotdevs/shipyard-neo-ship:latest"
+    runtime_type: ship
+    runtime_port: 8123
+    resources:
+      cpus: 2.0
+      memory: "4g"
+    capabilities:
+      - filesystem  # 包含 upload/download
+      - shell
+      - python
+    idle_timeout: 1800
+    warm_pool_size: 1
+    env: {}
+
+  # ── 浏览器 + Python 多容器沙箱 ───────
+  - id: browser-python
+    description: "Browser automation with Python backend"
+    containers:
+      - name: ship
+        image: "ghcr.io/astrbotdevs/shipyard-neo-ship:latest"
+        runtime_type: ship
+        runtime_port: 8123
+        resources:
+          cpus: 1.0
+          memory: "1g"
+        capabilities:
+          - python
+          - shell
+          - filesystem  # 包含 upload/download
+        # 这些能力优先由 ship 容器提供
+        primary_for:
+          - filesystem
+          - python
+          - shell
+        env: {}
+      - name: browser
+        image: "ghcr.io/astrbotdevs/shipyard-neo-gull:latest"
+        runtime_type: gull
+        runtime_port: 8115
+        resources:
+          cpus: 1.0
+          memory: "2g"
+        capabilities:
+          - browser
+        env: {}
+    idle_timeout: 1800
+    warm_pool_size: 1
+
+gc:
+  # 生产环境建议启用自动 GC
+  enabled: true
+  run_on_startup: true
+  # GC 扫描周期（秒）
+  interval_seconds: 300
+
+  # 多实例部署时必须保证唯一
+  instance_id: "bay-prod"
+
+  idle_session:
+    enabled: true
+  expired_sandbox:
+    enabled: true
+  orphan_cargo:
+    enabled: true
+  orphan_container:
+    # 建议在生产环境开启，用于清理遗留容器
+    enabled: true
+```
+
+通常可以按下面的思路理解和修改：
+
+- **最小必改项**：`security.api_key`
+- **最常改项**：`profiles` 里的资源限制、`warm_pool_size`、`idle_timeout`
+- **需要浏览器能力时**：使用或调整 `browser-python` profile
+- **希望减少冷启动时间时**：保留 `warm_pool.enabled: true`，并适当提高常用 profile 的 `warm_pool_size`
+- **资源较紧张时**：可先把 `warm_pool_size` 改小，甚至关闭 `warm_pool`
+- **如果需要代理访问外网**：配置顶层 `proxy`，或按 profile 单独覆盖
+
+### 关于 Shipyard Neo 的复用与持久化
+
+`Shipyard Neo` 中有几个重要概念：
+
+- **Sandbox**：对外稳定可见的资源单元
+- **Session**：实际运行中的容器会话，可被停止或重建
+- **Cargo**：持久化工作区卷，挂载到 `/workspace`
+
+对 AstrBot 而言，当前会按请求的 `session_id` 维度缓存沙箱 booter；在主 Agent 默认流程下，这个 `session_id` 通常等于消息会话标识 `unified_msg_origin`。因此，同一消息会话的后续请求通常会继续复用同一个 Neo sandbox；如果沙箱失效，则会自动重建。
+
+关于 TTL 与数据持久化的更详细说明，请参考下文的 [`关于 Shipyard Neo Sandbox TTL`](docs/zh/use/astrbot-agent-sandbox.md) 与 [`关于沙盒环境的数据持久化`](docs/zh/use/astrbot-agent-sandbox.md) 小节。
+
+## 旧方案：Shipyard
+
+以下内容为旧版 `Shipyard` 驱动器的部署与配置说明，仍然保留，供兼容旧部署方案时参考。
+
 ### 使用 Docker Compose 部署 AstrBot 和 Shipyard
 
 如果您还没有部署 AstrBot，或者想更换为我们推荐的带沙盒环境的部署方式，推荐使用 Docker Compose 来部署 AstrBot，代码如下：
@@ -56,22 +311,56 @@ docker pull soulter/shipyard-ship:latest
 > [!TIP]
 > 请确保您的 AstrBot 版本在 `v4.12.0` 及之后。
 
-在 AstrBot 控制台，进入 “配置文件” 页面，找到 “Agent 沙箱环境”，启用沙箱环境开关。
+在 AstrBot 控制台，进入 “AI 配置” -> “Agent Computer Use”。
 
-在出现的配置项中，
+1. 将 `Computer Use Runtime` 设为 `sandbox`
+2. 在 `沙箱环境驱动器` 中选择 `Shipyard Neo` 或 `Shipyard`
+3. 根据驱动器填写对应配置项
+4. 点击右下角“保存”
 
-对于 `Shipyard API Endpoint`，如果您使用上述的 Docker Compose 部署方式，填写 `http://shipyard:8156` 即可。如果您是单独部署的 Shipyard，请填写对应的地址，例如 `http://<your-host>:8156`。
+### 配置 Shipyard Neo
 
-对于 `Shipyard Access Token`，请填写您在部署 Shipyard 时配置的访问令牌。
+如果您选择的是 `Shipyard Neo`，主要配置项如下：
 
-对于 `Shipyard Ship 存活时间(秒)`，这个定义了每个沙箱环境实例的存活时间，默认值为 3600 秒（1 小时）。您可以根据需要调整这个值。
+- `Shipyard Neo API Endpoint`
+  - 联合部署时可填写 `http://bay:8114`
+  - 单独部署时填写实际地址，例如 `http://<your-host>:8114`
+- `Shipyard Neo Access Token`
+  - 填写 Bay API Key
+  - 如果是官方联合部署，且 AstrBot 能访问 Bay 的 `credentials.json`，可以留空自动发现
+- `Shipyard Neo Profile`
+  - 例如 `python-default`、`browser-python`
+  - 如果未手动指定，AstrBot 会优先尝试选择能力更完整、且优先带有 `browser` capability 的 profile，失败时再回退到 `python-default`
+- `Shipyard Neo Sandbox TTL`
+  - sandbox 生命周期上限，默认值为 3600 秒（1 小时）
 
-对于 `Shipyard Ship 会话复用上限`，这个定义了每个沙箱环境实例可以复用的最大会话数，默认值为 10。也就是 10 个会话会共享同一个沙箱环境实例。您可以根据需要调整这个值。
+### 配置 Shipyard（旧方案）
 
-填写好之后，点击右下角 “保存” 即可。
+如果您选择的是旧版 `Shipyard`，配置项如下：
+
+- `Shipyard API Endpoint`
+  - 如果您使用上述 Docker Compose 部署方式，填写 `http://shipyard:8156` 即可
+  - 如果您是单独部署的 Shipyard，请填写对应地址，例如 `http://<your-host>:8156`
+- `Shipyard Access Token`
+  - 请填写部署 Shipyard 时配置的访问令牌
+- `Shipyard Ship 存活时间(秒)`
+  - 定义每个沙箱环境实例的存活时间，默认值为 3600 秒（1 小时）
+- `Shipyard Ship 会话复用上限`
+  - 定义每个沙箱环境实例可以复用的最大会话数，默认值为 10
+
+## 关于 `Shipyard Neo Sandbox TTL`
+
+在 `Shipyard Neo` 中：
+
+- TTL 表示 sandbox 生命周期上限
+- profile 还会定义一个独立的空闲超时（`idle_timeout`）
+- AstrBot 发起能力调用时，通常会刷新空闲超时，而不是直接延长 TTL
+- `keepalive` 只会延长空闲超时，不会自动启动新的 session，也不会延长 TTL
 
 ## 关于 `Shipyard Ship 存活时间(秒)`
 
+以下说明仅适用于旧版 `Shipyard`：
+
 沙箱环境实例的存活时间定义了每个实例在被销毁之前可以存在的最长时间，这个时间的设置需要根据您的使用场景以及资源来决定。
 
 - 新的会话加入已有的沙箱环境实例时，该实例会自动延长存活时间到这个会话请求的 TTL。
@@ -79,6 +368,18 @@ docker pull soulter/shipyard-ship:latest
 
 ## 关于沙盒环境的数据持久化
 
+### Shipyard Neo
+
+`Shipyard Neo` 的工作区根目录固定为 `/workspace`。
+
+其持久化由 Cargo 提供：
+
+- 文件系统数据保存在 Cargo 中，并挂载到 `/workspace`
+- 即使底层 Session 被停止或重建，Cargo 中的数据通常仍可保留
+- 对于带浏览器能力的 profile，浏览器状态也可能会一起持久化，例如 `/workspace/.browser/profile/`
+
+### Shipyard（旧方案）
+
 Shipyard 会给每个会话分配一个工作目录，在 `/home/<会话唯一 ID>` 目录下。
 
 Shipyard 会自动将沙盒环境中的 /home 目录挂载到宿主机的 `${PWD}/data/shipyard/ship_mnt_data` 目录下，当沙盒环境实例被销毁后，如果某个会话继续请求调用沙箱，Shipyard 会重新创建一个新的沙盒环境实例，并将之前持久化的数据重新挂载进去，保证数据的连续性。