From d55750189e2fcda550a5cbdd2342045239c38250 Mon Sep 17 00:00:00 2001 From: Peter Steinberger Date: Thu, 8 Jan 2026 21:49:26 +0100 Subject: [PATCH] docs: add sandboxing page and cross-links --- docs/gateway/configuration.md | 2 + docs/gateway/sandboxing.md | 91 +++++++++++++++++++++++++++++++ docs/gateway/security.md | 4 +- docs/install/docker.md | 4 ++ docs/multi-agent-sandbox-tools.md | 2 + 5 files changed, 102 insertions(+), 1 deletion(-) create mode 100644 docs/gateway/sandboxing.md diff --git a/docs/gateway/configuration.md b/docs/gateway/configuration.md index 97d3aa525..88ca0361a 100644 --- a/docs/gateway/configuration.md +++ b/docs/gateway/configuration.md @@ -1176,6 +1176,8 @@ per session key at a time). Default: 1. Optional **Docker sandboxing** for the embedded agent. Intended for non-main sessions so they cannot access your host system. +Details: [Sandboxing](/gateway/sandboxing) + Defaults (if enabled): - scope: `"agent"` (one container + workspace per agent) - Debian bookworm-slim based image diff --git a/docs/gateway/sandboxing.md b/docs/gateway/sandboxing.md new file mode 100644 index 000000000..8d4105a70 --- /dev/null +++ b/docs/gateway/sandboxing.md @@ -0,0 +1,91 @@ +--- +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. +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: +```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) diff --git a/docs/gateway/security.md b/docs/gateway/security.md index e09347746..e60206734 100644 --- a/docs/gateway/security.md +++ b/docs/gateway/security.md @@ -138,10 +138,12 @@ We may add a single `readOnlyMode` flag later to simplify this configuration. ## Sandboxing (recommended) +Dedicated doc: [Sandboxing](/gateway/sandboxing) + Two complementary approaches: - **Run the full Gateway in Docker** (container boundary): [Docker](/install/docker) -- **Tool sandbox** (`agent.sandbox`, host gateway + Docker-isolated tools): [Configuration](/gateway/configuration) +- **Tool sandbox** (`agent.sandbox`, host gateway + Docker-isolated tools): [Sandboxing](/gateway/sandboxing) Note: to prevent cross-agent access, keep `sandbox.scope` at `"agent"` (default) or `"session"` for stricter per-session isolation. `scope: "shared"` uses a diff --git a/docs/install/docker.md b/docs/install/docker.md index 29c934798..5647ad87b 100644 --- a/docs/install/docker.md +++ b/docs/install/docker.md @@ -13,6 +13,8 @@ This guide covers: - Containerized Gateway (full Clawdbot in Docker) - Per-session Agent Sandbox (host gateway + Docker-isolated agent tools) +Sandboxing details: [Sandboxing](/gateway/sandboxing) + ## Requirements - Docker Desktop (or Docker Engine) + Docker Compose v2 @@ -92,6 +94,8 @@ pnpm test:docker:qr ## Agent Sandbox (host gateway + Docker tools) +Deep dive: [Sandboxing](/gateway/sandboxing) + ### What it does When `agent.sandbox` is enabled, **non-main sessions** run tools inside a Docker diff --git a/docs/multi-agent-sandbox-tools.md b/docs/multi-agent-sandbox-tools.md index b9ee2bcdc..5b5604e95 100644 --- a/docs/multi-agent-sandbox-tools.md +++ b/docs/multi-agent-sandbox-tools.md @@ -18,6 +18,8 @@ This allows you to run multiple agents with different security profiles: - Family/work agents with restricted tools - Public-facing agents in sandboxes +For how sandboxing behaves at runtime, see [Sandboxing](/gateway/sandboxing). + --- ## Configuration Examples