Skip to main content

​
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).
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. 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"
      }
    }
  }
}