Sandbox CLI

Manage Docker-based sandbox containers for isolated agent execution.

Overview

ClawdBot can run agents in isolated Docker containers for security. The sandbox commands help you manage these containers, especially after updates or configuration changes.

Commands

`clawd sandbox list`

List all sandbox containers with their status and configuration.

clawd sandbox list
clawd sandbox list --browser  # List only browser containers
clawd sandbox list --json     # JSON output

Output includes:

Container name and status (running/stopped)
Docker image and whether it matches config
Age (time since creation)
Idle time (time since last use)
Associated session/agent

`clawd sandbox recreate`

Remove sandbox containers to force recreation with updated images/config.

clawd sandbox recreate --all                # Recreate all containers
clawd sandbox recreate --session main       # Specific session
clawd sandbox recreate --agent mybot        # Specific agent
clawd sandbox recreate --browser            # Only browser containers
clawd sandbox recreate --all --force        # Skip confirmation

Options:

--all: Recreate all sandbox containers
--session <key>: Recreate container for specific session
--agent <id>: Recreate containers for specific agent
--browser: Only recreate browser containers
--force: Skip confirmation prompt

Important: Containers are automatically recreated when the agent is next used.

Use Cases

After updating Docker images

# Pull new image
docker pull clawdbot-sandbox:latest
docker tag clawdbot-sandbox:latest clawdbot-sandbox:bookworm-slim

# Update config to use new image
# Edit clawdbot.config.json: agent.sandbox.docker.image

# Recreate containers
clawd sandbox recreate --all

After changing sandbox configuration

# Edit clawdbot.config.json: agent.sandbox.*

# Recreate to apply new config
clawd sandbox recreate --all

For a specific agent only

# Update only one agent's containers
clawd sandbox recreate --agent alfred

Why is this needed?

Problem: When you update sandbox Docker images or configuration:

Existing containers continue running with old settings
Containers are only pruned after 24h of inactivity
Regularly-used agents keep old containers running indefinitely

Solution: Use clawd sandbox recreate to force removal of old containers. They'll be recreated automatically with current settings when next needed.

Configuration

Sandbox settings are in clawdbot.config.json:

{
  "agent": {
    "sandbox": {
      "mode": "all",                    // off, non-main, all
      "scope": "agent",                 // session, agent, shared
      "docker": {
        "image": "clawdbot-sandbox:bookworm-slim",
        "containerPrefix": "clawdbot-sbx-"
        // ... more Docker options
      },
      "prune": {
        "idleHours": 24,               // Auto-prune after 24h idle
        "maxAgeDays": 7                // Auto-prune after 7 days
      }
    }
  }
}

3.2 KiB Raw Blame History