clawdbot/docs/gateway/sandboxing.md

summary, title, read_when, status

summary	title	read_when	status
How Clawdbot sandboxing works: modes, scopes, workspace access, and images	Sandboxing	You want a dedicated explanation of sandboxing or need to tune agents.defaults.sandbox.	active

Sandboxing

Clawdbot can run tools inside Docker containers to reduce blast radius. This is optional and controlled by configuration (agents.defaults.sandbox or agents.list[].sandbox). If sandboxing is off, tools run on the host. The Gateway stays on the host; tool execution runs in an isolated sandbox when enabled.

This is not a perfect security boundary, but it materially limits filesystem and process access when the model does something dumb.

What gets sandboxed

• Tool execution (bash, read, write, edit, process, etc.).
• Optional sandboxed browser (agents.defaults.sandbox.browser).
  • By default, the sandbox browser auto-starts (ensures CDP is reachable) when the browser tool needs it. Configure via agents.defaults.sandbox.browser.autoStart and agents.defaults.sandbox.browser.autoStartTimeoutMs.
  • agents.defaults.sandbox.browser.allowHostControl lets sandboxed sessions target the host browser explicitly.
  • Optional allowlists gate target: "custom": allowedControlUrls, allowedControlHosts, allowedControlPorts.

Not sandboxed:

• The Gateway process itself.
• Any tool explicitly allowed to run on the host (e.g. tools.elevated).
  • Elevated bash runs on the host and bypasses sandboxing.
  • If sandboxing is off, tools.elevated does not change execution (already on host). See Elevated Mode.

Modes

agents.defaults.sandbox.mode controls when sandboxing is used:

• "off": no sandboxing.
• "non-main": sandbox only non-main sessions (default if you want normal chats on host).
• "all": every session runs in a sandbox. Note: "non-main" is based on session.mainKey (default "main"), not agent id. Group/channel sessions use their own keys, so they count as non-main and will be sandboxed.

Scope

agents.defaults.sandbox.scope controls how many containers are created:

• "session" (default): one container per session.
• "agent": one container per agent.
• "shared": one container shared by all sandboxed sessions.

Workspace access

agents.defaults.sandbox.workspaceAccess controls what the sandbox can see:

• "none" (default): tools see a sandbox workspace under ~/.clawdbot/sandboxes.
• "ro": mounts the agent workspace read-only at /agent (disables write/edit).
• "rw": mounts the agent workspace read/write at /workspace.

Inbound media is copied into the active sandbox workspace (media/inbound/*). Skills note: the read tool is sandbox-rooted. With workspaceAccess: "none", Clawdbot mirrors eligible skills into the sandbox workspace (.../skills) so they can be read. With "rw", workspace skills are readable from /workspace/skills.

Images + setup

Default image: clawdbot-sandbox:bookworm-slim

Build it once:

scripts/sandbox-setup.sh

Sandboxed browser image:

scripts/sandbox-browser-setup.sh

By default, sandbox containers run with no network. Override with agents.defaults.sandbox.docker.network.

Docker installs and the containerized gateway live here: Docker

Tool policy + escape hatches

Tool allow/deny policies still apply before sandbox rules. If a tool is denied globally or per-agent, sandboxing doesn’t bring it back.

tools.elevated is an explicit escape hatch that runs bash on the host.

Debugging:

• Use clawdbot sandbox explain to inspect effective sandbox mode, tool policy, and fix-it config keys.
• See Sandbox vs Tool Policy vs Elevated for the “why is this blocked?” mental model. Keep it locked down.

Multi-agent overrides

Each agent can override sandbox + tools: agents.list[].sandbox and agents.list[].tools (plus agents.list[].tools.sandbox.tools for sandbox tool policy). See Multi-Agent Sandbox & Tools for precedence.

Minimal enable example

{
  agents: {
    defaults: {
      sandbox: {
        mode: "non-main",
        scope: "session",
        workspaceAccess: "none"
      }
    }
  }
}

Related docs

• Sandbox Configuration
• Multi-Agent Sandbox & Tools
• Security