3.0 KiB
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.
This is optional and controlled by configuration (agent.sandbox or
routing.agents[id].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 (
agent.sandbox.browser).
Not sandboxed:
- The Gateway process itself.
- Any tool explicitly allowed to run on the host (e.g.
agent.elevated).- Elevated bash runs on the host and bypasses sandboxing.
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(disableswrite/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"
}
}
}