Sandbox CLI
CLI reference for openclaw sandbox (manage sandbox containers and effective policies).
Manage Docker-based sandbox containers for isolated agent execution.
Overview
For security, OpenClaw can run agents in isolated Docker containers. The ''sandbox'' command helps you manage these containers, especially after updates or configuration changes.
Commands
#
`openclaw sandbox explain`
Check effective sandbox mode/scope/workspace access, sandbox tool policies, and elevation gates (with fix configuration key paths).
openclaw sandbox explain openclaw sandbox explain --session agent:main:main openclaw sandbox explain --agent work openclaw sandbox explain --json
#
`openclaw sandbox list`
List all sandbox containers with their status and configuration.
openclaw sandbox list openclaw sandbox list --browser # List only browser containers openclaw sandbox list --json # JSON output
Output includes:
- Container name and status (running/stopped)
- Docker image and whether it matches configuration
- Age (time since creation)
- Idle time (time since last use) - Associated session/agent
#
`openclaw sandbox recreate`
Delete sandbox containers to force recreation with updated image/configuration.
openclaw sandbox recreate --all # Recreate all containers openclaw sandbox recreate --session main # Specific session openclaw sandbox recreate --agent mybot # Specific agent openclaw sandbox recreate --browser # Only browser containers openclaw sandbox recreate --all --force # Skip confirmation
Options:
- ''--all'': Recreate all sandbox containers
- ''--session <key>'': Recreate containers for a specific session
- ''--agent <id>'': Recreate containers for a specific agent
- ''--browser'': Recreate only browser containers
- ''--force'': Skip confirmation prompt
Important note: Containers will be automatically recreated on next agent use.
Use Cases
#
After updating Docker image
docker pull openclaw-sandbox:latest docker tag openclaw-sandbox:latest openclaw-sandbox:bookworm-slim openclaw sandbox recreate --all
#
After changing sandbox configuration
openclaw sandbox recreate --all
#
After changing setupCommand
openclaw sandbox recreate --all openclaw sandbox recreate --agent family
#
For specific agents only
openclaw sandbox recreate --agent alfred
Why do you need this?
Problem: When you update sandbox Docker image or configuration:
- Existing containers continue running with old settings
- Containers are only pruned after 24 hours of inactivity
- Frequently used agents keep old containers running indefinitely
''Solution:'' Use ''openclaw sandbox recreate'' to force delete old containers. They will be automatically recreated with current settings when needed next.
Tip: Prefer ''openclaw sandbox recreate'' over manual ''docker rm''. It uses
gateway's container naming and avoids mismatches when scope/session keys change.
Configuration
Sandbox settings are in ''~/.openclaw/openclaw.json'' under ''agents.defaults.sandbox'' (per-agent overrides are in ''agents.list[].sandbox''):
{
"agents": {
"defaults": {
"sandbox": {
"mode": "all", // off, non-main, all
"scope": "agent", // session, agent, shared
"docker": {
"image": "openclaw-sandbox:bookworm-slim",
"containerPrefix": "openclaw-sbx-",
// ... more Docker options
},
"prune": {
"idleHours": 24, // Auto-prune after 24h idle
"maxAgeDays": 7, // Auto-prune after 7 days
},
},
},
},
}