101 lines
3.4 KiB
Markdown
101 lines
3.4 KiB
Markdown
---
|
||
summary: "How Clawdbot sandboxing works: modes, scopes, workspace access, and images"
|
||
title: Sandboxing
|
||
read_when: "You want a dedicated explanation of sandboxing or need to tune agent.sandbox."
|
||
status: 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.**
|
||
- If sandboxing is off, `agent.elevated` does not change execution (already on host). See [Elevated Mode](/tools/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/*`).
|
||
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:
|
||
```bash
|
||
scripts/sandbox-setup.sh
|
||
```
|
||
|
||
Sandboxed browser image:
|
||
```bash
|
||
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](/install/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](/multi-agent-sandbox-tools) for precedence.
|
||
|
||
## Minimal enable example
|
||
```json5
|
||
{
|
||
agent: {
|
||
sandbox: {
|
||
mode: "non-main",
|
||
scope: "session",
|
||
workspaceAccess: "none"
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
## Related docs
|
||
- [Sandbox Configuration](/gateway/configuration#agent-sandbox)
|
||
- [Multi-Agent Sandbox & Tools](/multi-agent-sandbox-tools)
|
||
- [Security](/gateway/security)
|