docs: add sandboxing page and cross-links

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

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)

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

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

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