Sandbox CLI

Manage sandbox runtimes for isolated agent execution.

Overview

OpenClaw can run agents in isolated sandbox runtimes for security. The

commands help you inspect and recreate those runtimes after updates or configuration changes.

Today that usually means:

• Docker sandbox containers
• SSH sandbox runtimes when
  text

  Copy

  agents.defaults.sandbox.backend = "ssh"
• OpenShell sandbox runtimes when
  text

  Copy

  agents.defaults.sandbox.backend = "openshell"

For

and OpenShell , recreate matters more than with Docker:

• the remote workspace is canonical after the initial seed
• text

  Copy

  openclaw sandbox recreate
  deletes that canonical remote workspace for the selected scope
• next use seeds it again from the current local workspace

Commands

text

Copy

openclaw sandbox explain

Inspect the effective sandbox mode/scope/workspace access, sandbox tool policy, and elevated gates (with fix-it config key paths).

bash
Copy
openclaw sandbox explain
openclaw sandbox explain --session agent:main:main
openclaw sandbox explain --agent work
openclaw sandbox explain --json

text

Copy

openclaw sandbox list

List all sandbox runtimes with their status and configuration.

bash
Copy
openclaw sandbox list
openclaw sandbox list --browser  # List only browser containers
openclaw sandbox list --json     # JSON output

Output includes:

• Runtime name and status
• Backend (
  text

  Copy

  docker
  ,
  text

  Copy

  openshell
  , etc.)
• Config label and whether it matches current config
• Age (time since creation)
• Idle time (time since last use)
• Associated session/agent

text

Copy

openclaw sandbox recreate

Remove sandbox runtimes to force recreation with updated config.

bash
Copy
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:

• text

  Copy

  --all
  : Recreate all sandbox containers
• text

  Copy

  --session <key>
  : Recreate container for specific session
• text

  Copy

  --agent <id>
  : Recreate containers for specific agent
• text

  Copy

  --browser
  : Only recreate browser containers
• text

  Copy

  --force
  : Skip confirmation prompt

Use cases

After updating a Docker image

bash
Copy
# Pull new image
docker pull openclaw-sandbox:latest
docker tag openclaw-sandbox:latest openclaw-sandbox:bookworm-slim

# Update config to use new image
# Edit config: agents.defaults.sandbox.docker.image (or agents.list[].sandbox.docker.image)

# Recreate containers
openclaw sandbox recreate --all

After changing sandbox configuration

bash
Copy
# Edit config: agents.defaults.sandbox.* (or agents.list[].sandbox.*)

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

After changing SSH target or SSH auth material

bash
Copy
# Edit config:
# - agents.defaults.sandbox.backend
# - agents.defaults.sandbox.ssh.target
# - agents.defaults.sandbox.ssh.workspaceRoot
# - agents.defaults.sandbox.ssh.identityFile / certificateFile / knownHostsFile
# - agents.defaults.sandbox.ssh.identityData / certificateData / knownHostsData

openclaw sandbox recreate --all

For the core

backend, recreate deletes the per-scope remote workspace root on the SSH target. The next run seeds it again from the local workspace.

After changing OpenShell source, policy, or mode

bash
Copy
# Edit config:
# - agents.defaults.sandbox.backend
# - plugins.entries.openshell.config.from
# - plugins.entries.openshell.config.mode
# - plugins.entries.openshell.config.policy

openclaw sandbox recreate --all

For OpenShell

mode, recreate deletes the canonical remote workspace for that scope. The next run seeds it again from the local workspace.

After changing setupCommand

bash
Copy
openclaw sandbox recreate --all
# or just one agent:
openclaw sandbox recreate --agent family

For a specific agent only

bash
Copy
# Update only one agent's containers
openclaw sandbox recreate --agent alfred

Why this is needed

When you update sandbox configuration:

• Existing runtimes continue running with old settings.
• Runtimes are only pruned after 24h of inactivity.
• Regularly-used agents keep old runtimes alive indefinitely.

Use

to force removal of old runtimes. They are recreated automatically with current settings when next needed.

Configuration

Sandbox settings live in

under (per-agent overrides go in ):

jsonc
Copy
{
  "agents": {
    "defaults": {
      "sandbox": {
        "mode": "all", // off, non-main, all
        "backend": "docker", // docker, ssh, openshell
        "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
        },
      },
    },
  },
}

Related

• CLI reference
• Sandboxing
• Agent workspace
• Doctor: checks sandbox setup.