docs/en/use/astrbot-agent-sandbox.md
[!TIP] This feature is currently in technical preview and may have some bugs. If you encounter any issues, please submit an issue on GitHub.
Starting from version v4.12.0, AstrBot introduced the Agent sandbox environment to replace the previous code executor functionality. The sandbox environment provides Agents with safer and more flexible code execution and automation capabilities.
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 = sandboxSandbox Driver = Shipyard Neo or ShipyardShipyard Neo is now the default driver. It consists of Bay, Ship, and Gull:
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 Neoprofile. AstrBot only mounts browser-related tools when the selected profile supports thebrowsercapability. A typical example isbrowser-python.
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.
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:
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:
http://<your-host>:8114 by defaultShipyard Neo driverShipyard Neo API Endpoint to the corresponding address, for example http://<your-host>:8114Shipyard 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 itconfig.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. 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.
# 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:
security.api_keywarm_pool_size, and idle_timeout under profilesbrowser-python profilewarm_pool.enabled: true and increase warm_pool_size for frequently used profileswarm_pool_size, or even disable warm_poolproxy, or override it per profileShipyard Neo has several important concepts:
/workspaceFrom 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” and “Data Persistence in the Sandbox Environment”.
The following content describes the older Shipyard driver. It is kept for compatibility with existing legacy deployments.
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:
git clone https://github.com/AstrBotDevs/AstrBot
cd AstrBot
# 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 starts a Docker Compose stack containing the AstrBot main program and the sandbox environment.
If AstrBot is already deployed but the sandbox environment is not, you can deploy Shipyard separately.
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 variables in docker-compose.yml, such as the Shipyard access token
docker compose -f docker-compose.yml up -d
docker pull soulter/shipyard-ship:latest
After successful deployment, Shipyard listens on http://<your-host>:8156 by default.
[!TIP] 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.
[!TIP] Please make sure your AstrBot version is
v4.12.0or later.
In the AstrBot console, go to AI Settings -> Agent Computer Use.
Computer Use Runtime to sandboxShipyard Neo or Shipyard as the sandbox driverIf you choose Shipyard Neo, the main configuration items are:
Shipyard Neo API Endpoint
http://<your-host>:8114Shipyard Neo Access Token
credentials.json, you may leave it empty and let AstrBot auto-discover itShipyard Neo Profile
python-default or browser-pythonbrowser capability, and fall back to python-default if neededShipyard Neo Sandbox TTL
If you choose the legacy Shipyard driver, the relevant configuration items are:
Shipyard API Endpoint
http://shipyard:8156http://<your-host>:8156Shipyard Access Token
Shipyard Ship Lifetime (seconds)
Shipyard Ship Session Reuse Limit
Shipyard Neo Sandbox TTLIn Shipyard Neo:
idle_timeout)keepalive only extends the idle timeout; it does not automatically start a new session and does not extend the TTLShipyard Ship Lifetime (seconds)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.
The workspace root of Shipyard Neo is fixed at /workspace.
Persistence is provided by Cargo:
/workspace/workspace/.browser/profile/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.
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 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.