Sandbox CLI: Manage Runtimes

Manage sandbox runtimes for isolated agent execution: Docker/Podman containers, SSH targets, or OpenShell backends.

The configured runtimes are not used by openclaw agent exec. Its isolated implicit policy config disables the agent sandbox, permits full Gateway-host execution, and limits filesystem tools to --cwd.

Commands

`openclaw sandbox list`

Show sandbox runtimes along with their status, backend, config match, age, idle time, and linked session/agent.

For plugin-provided backends like OpenShell, the owning backend plugin is loaded by the CLI before live runtime status is checked. Browser-only operations work without activating the backend plugin.

openclaw sandbox list
openclaw sandbox list --browser  # browser containers only
openclaw sandbox list --json

`openclaw sandbox recreate`

Remove sandbox runtimes to force them to be recreated with the current config. The next agent use triggers automatic recreation.

openclaw sandbox recreate --all
openclaw sandbox recreate --agent mybot        # includes agent:mybot:* sub-sessions
openclaw sandbox recreate --session "agent:main:main"
openclaw sandbox recreate --browser --all      # only browser containers
openclaw sandbox recreate --all --force        # skip confirmation

Options:

--all: recreate every sandbox container
--session <key>: recreate the runtime matching this exact scope key (as shown by sandbox list); no short-name expansion
--agent <id>: recreate runtimes for a single agent (matches agent:<id> and agent:<id>:*)
--browser: restrict to browser containers only
--force: bypass the confirmation prompt

Supply exactly one of --all, --session, or --agent.

For ssh and OpenShell remote, recreation carries more weight than with Docker: the remote workspace is canonical after the initial seed, recreate removes that canonical remote workspace for the selected scope, and the next run reseeds it from the current local workspace.

`openclaw sandbox explain`

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

The report keeps workspaceRoot as the configured sandbox root and separately shows the effective host workspace, backend runtime workdir, and Docker mount table. For workspaceAccess: "rw", the effective host workspace is the agent workspace rather than a directory below workspaceRoot.

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

Unlike recreate --session, this accepts short session names (for example main) and expands them against the resolved agent. An explicit --agent is sufficient for multi-agent fleets with no implicit owner; sandbox explanation does not require or guess a default first.

Why recreate is needed

Updating sandbox config does not affect running containers: existing runtimes keep their old settings, and idle runtimes are only pruned after prune.idleHours (default 24h). Regularly used agents can keep stale runtimes alive indefinitely. openclaw sandbox recreate removes the old runtime so the next use rebuilds it from current config.

Tip

Prefer openclaw sandbox recreate over manual backend-specific cleanup. It uses the Gateway's runtime registry and avoids mismatches when scope or session keys change.

Common triggers

Change	Command
Container sandbox image update (`agents.defaults.sandbox.docker.image`)	`openclaw sandbox recreate --all`
Sandbox config (`agents.defaults.sandbox.*`)	`openclaw sandbox recreate --all`
SSH target/auth (`agents.defaults.sandbox.ssh.{target,workspaceRoot,identityFile,certificateFile,knownHostsFile,identityData,certificateData,knownHostsData}`)	`openclaw sandbox recreate --all`
OpenShell source/policy/mode (`plugins.entries.openshell.config.{from,mode,policy}`)	`openclaw sandbox recreate --all`
`setupCommand`	`openclaw sandbox recreate --all` (or `--agent <id>` for one agent)

Note

Runtimes are automatically recreated when the agent is next used.

Registry migration

Sandbox runtime metadata resides in the shared SQLite state database. Older installs may have legacy registry files that regular reads no longer rewrite:

~/.openclaw/sandbox/containers.json
~/.openclaw/sandbox/browsers.json
one JSON shard per container/browser under ~/.openclaw/sandbox/containers/ or ~/.openclaw/sandbox/browsers/

Run openclaw doctor --fix to migrate valid legacy entries into SQLite. Invalid legacy files are quarantined so a corrupt old registry cannot hide current runtime entries.

Configuration

Sandbox settings live in ~/.openclaw/openclaw.json under agents.defaults.sandbox (per-agent overrides go in agents.entries.*.sandbox):

{
  "agents": {
    "defaults": {
      "sandbox": {
        "mode": "all", // off, non-main, all
        "backend": "docker", // docker, podman, ssh; openshell is plugin-provided
        "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
        },
      },
    },
  },
}

Command line interface guide
Isolation mechanisms
Agent working directory
Diagnostics tool: verifies the sandbox configuration.

Commands

openclaw sandbox list

openclaw sandbox recreate

openclaw sandbox explain