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 agent.sandbox.	active

Sandboxing

Clawdbot can run tools inside Docker containers to reduce blast radius. The Gateway stays on the host; tool execution runs in an isolated sandbox.

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 (agent.sandbox.browser).

Not sandboxed:

• The Gateway process itself.
• Any tool explicitly allowed to run on the host (e.g. agent.elevated).

Modes

agent.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.

Scope

agent.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

agent.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/*).

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 agent.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.

agent.elevated is an explicit escape hatch that runs bash on the host. Keep it locked down.

Multi-agent overrides

Each agent can override sandbox + tools: routing.agents[id].sandbox and routing.agents[id].tools. See Multi-Agent Sandbox & Tools for precedence.

Minimal enable example

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

Related docs

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