From 0e9837183d43632aa9e8125242a9ee16728ad999 Mon Sep 17 00:00:00 2001 From: Peter Steinberger Date: Wed, 7 Jan 2026 20:31:23 +0100 Subject: [PATCH] docs: expand per-agent sandbox profiles --- docs/gateway/configuration.md | 69 ++++++++++++++++++++++++++++ docs/gateway/security.md | 84 ++++++++++++++++++++++++++++++++--- docs/install/docker.md | 12 +++++ 3 files changed, 160 insertions(+), 5 deletions(-) diff --git a/docs/gateway/configuration.md b/docs/gateway/configuration.md index 8c4c22408..57c3cc955 100644 --- a/docs/gateway/configuration.md +++ b/docs/gateway/configuration.md @@ -359,6 +359,75 @@ Deterministic match order: Within each match tier, the first matching entry in `routing.bindings` wins. +#### Per-agent access profiles (multi-agent) + +Each agent can carry its own sandbox + tool policy. Use this to mix access +levels in one gateway: +- **Full access** (personal agent) +- **Read-only** tools + workspace +- **No filesystem access** (messaging/session tools only) + +See [Multi-Agent Sandbox & Tools](/multi-agent-sandbox-tools) for precedence and +additional examples. + +Full access (no sandbox): +```json5 +{ + routing: { + agents: { + personal: { + workspace: "~/clawd-personal", + sandbox: { mode: "off" } + } + } + } +} +``` + +Read-only tools + read-only workspace: +```json5 +{ + routing: { + agents: { + family: { + workspace: "~/clawd-family", + sandbox: { + mode: "all", + scope: "agent", + workspaceAccess: "ro" + }, + tools: { + allow: ["read", "sessions_list", "sessions_history", "sessions_send", "sessions_spawn"], + deny: ["write", "edit", "bash", "process", "browser"] + } + } + } + } +} +``` + +No filesystem access (messaging/session tools enabled): +```json5 +{ + routing: { + agents: { + public: { + workspace: "~/clawd-public", + sandbox: { + mode: "all", + scope: "agent", + workspaceAccess: "none" + }, + tools: { + allow: ["sessions_list", "sessions_history", "sessions_send", "sessions_spawn", "whatsapp", "telegram", "slack", "discord", "gateway"], + deny: ["read", "write", "edit", "bash", "process", "browser", "canvas", "nodes", "cron", "gateway", "image"] + } + } + } + } +} +``` + Example: two WhatsApp accounts → two agents: ```json5 diff --git a/docs/gateway/security.md b/docs/gateway/security.md index d12dde53b..e09347746 100644 --- a/docs/gateway/security.md +++ b/docs/gateway/security.md @@ -128,12 +128,13 @@ Consider running your AI on a separate phone number from your personal one: - Personal number: Your conversations stay private - Bot number: AI handles these, with appropriate boundaries -### 4. Read-Only Mode (Future) +### 4. Read-Only Mode (Today, via sandbox + tools) -We're considering a `readOnlyMode` flag that prevents the AI from: -- Writing files outside a sandbox -- Executing shell commands -- Sending messages +You can already build a read-only profile by combining: +- `sandbox.workspaceAccess: "ro"` (or `"none"` for no workspace access) +- tool allow/deny lists that block `write`, `edit`, `bash`, `process`, etc. + +We may add a single `readOnlyMode` flag later to simplify this configuration. ## Sandboxing (recommended) @@ -153,6 +154,79 @@ Also consider agent workspace access inside the sandbox: Important: `agent.elevated` is an explicit escape hatch that runs bash on the host. Keep `agent.elevated.allowFrom` tight and don’t enable it for strangers. +## Per-agent access profiles (multi-agent) + +With multi-agent routing, each agent can have its own sandbox + tool policy: +use this to give **full access**, **read-only**, or **no access** per agent. +See [Multi-Agent Sandbox & Tools](/multi-agent-sandbox-tools) for full details +and precedence rules. + +Common use cases: +- Personal agent: full access, no sandbox +- Family/work agent: sandboxed + read-only tools +- Public agent: sandboxed + no filesystem/shell tools + +### Example: full access (no sandbox) + +```json5 +{ + routing: { + agents: { + personal: { + workspace: "~/clawd-personal", + sandbox: { mode: "off" } + } + } + } +} +``` + +### Example: read-only tools + read-only workspace + +```json5 +{ + routing: { + agents: { + family: { + workspace: "~/clawd-family", + sandbox: { + mode: "all", + scope: "agent", + workspaceAccess: "ro" + }, + tools: { + allow: ["read"], + deny: ["write", "edit", "bash", "process", "browser"] + } + } + } + } +} +``` + +### Example: no filesystem/shell access (provider messaging allowed) + +```json5 +{ + routing: { + agents: { + public: { + workspace: "~/clawd-public", + sandbox: { + mode: "all", + scope: "agent", + workspaceAccess: "none" + }, + tools: { + allow: ["sessions_list", "sessions_history", "sessions_send", "sessions_spawn", "whatsapp", "telegram", "slack", "discord", "gateway"], + deny: ["read", "write", "edit", "bash", "process", "browser", "canvas", "nodes", "cron", "gateway", "image"] + } + } + } + } +} +``` + ## What to Tell Your AI Include security guidelines in your agent's system prompt: diff --git a/docs/install/docker.md b/docs/install/docker.md index ed06679e9..0f3879de4 100644 --- a/docs/install/docker.md +++ b/docs/install/docker.md @@ -86,6 +86,18 @@ container. The gateway stays on your host, but the tool execution is isolated: Warning: `scope: "shared"` disables cross-session isolation. All sessions share one container and one workspace. +### Per-agent sandbox profiles (multi-agent) + +If you use multi-agent routing, each agent can override sandbox + tool settings: +`routing.agents[id].sandbox` and `routing.agents[id].tools`. This lets you run +mixed access levels in one gateway: +- Full access (personal agent) +- Read-only tools + read-only workspace (family/work agent) +- No filesystem/shell tools (public agent) + +See [Multi-Agent Sandbox & Tools](/multi-agent-sandbox-tools) for examples, +precedence, and troubleshooting. + ### Default behavior - Image: `clawdbot-sandbox:bookworm-slim`