clawdbot 2026.1.4-1

package/docs/discord.md

@@ -0,0 +1,293 @@
+---
+summary: "Discord bot support status, capabilities, and configuration"
+read_when:
+  - Working on Discord surface features
+---
+# Discord (Bot API)
+
+Updated: 2025-12-07
+
+Status: ready for DM and guild text channels via the official Discord bot gateway.
+
+## Goals
+- Talk to Clawdbot via Discord DMs or guild channels.
+- Share the same `main` session used by WhatsApp/Telegram/WebChat; guild channels stay isolated as `discord:group:<channelId>` (display names use `discord:<guildSlug>#<channelSlug>`).
+- Group DMs are ignored by default; enable via `discord.dm.groupEnabled` and optionally restrict by `discord.dm.groupChannels`.
+- Keep routing deterministic: replies always go back to the surface they arrived on.
+
+## How it works
+1. Create a Discord application → Bot, enable the intents you need (DMs + guild messages + message content), and grab the bot token.
+2. Invite the bot to your server with the permissions required to read/send messages where you want to use it.
+3. Configure Clawdbot with `DISCORD_BOT_TOKEN` (or `discord.token` in `~/.clawdbot/clawdbot.json`).
+4. Run the gateway; it auto-starts the Discord provider only when a `discord` config section exists **and** the token is set (unless `discord.enabled = false`).
+   - If you prefer env vars, still add `discord: { enabled: true }` to `~/.clawdbot/clawdbot.json` and set `DISCORD_BOT_TOKEN`.
+5. Direct chats: use `user:<id>` (or a `<@id>` mention) when delivering; all turns land in the shared `main` session.
+6. Guild channels: use `channel:<channelId>` for delivery. Mentions are required by default and can be set per guild or per channel.
+7. Optional DM control: set `discord.dm.enabled = false` to ignore all DMs, or `discord.dm.allowFrom` to allow specific users (ids or names). Use `discord.dm.groupEnabled` + `discord.dm.groupChannels` to allow group DMs.
+8. Optional guild rules: set `discord.guilds` keyed by guild id (preferred) or slug, with per-channel rules.
+9. Optional slash commands: enable `discord.slashCommand` to accept user-installed app commands (ephemeral replies). Slash invocations respect the same DM/guild allowlists.
+10. Optional guild context history: set `discord.historyLimit` (default 20) to include the last N guild messages as context when replying to a mention. Set `0` to disable.
+11. Reactions: the agent can trigger reactions via the `discord` tool (gated by `discord.actions.*`).
+    - The `discord` tool is only exposed when the current surface is Discord.
+12. Slash commands use isolated session keys (`${sessionPrefix}:${userId}`) rather than the shared `main` session.
+
+Note: Discord does not provide a simple username → id lookup without extra guild context, so prefer ids or `<@id>` mentions for DM delivery targets.
+Note: Slugs are lowercase with spaces replaced by `-`. Channel names are slugged without the leading `#`.
+Note: Guild context `[from:]` lines include `author.tag` + `id` to make ping-ready replies easy.
+
+## How to create your own bot
+
+This is the “Discord Developer Portal” setup for running Clawdbot in a server (guild) channel like `#help`.
+
+### 1) Create the Discord app + bot user
+1. Discord Developer Portal → **Applications** → **New Application**
+2. In your app:
+   - **Bot** → **Add Bot**
+   - Copy the **Bot Token** (this is what you put in `DISCORD_BOT_TOKEN`)
+
+### 2) Enable the gateway intents Clawdbot needs
+Discord blocks “privileged intents” unless you explicitly enable them.
+
+In **Bot** → **Privileged Gateway Intents**, enable:
+- **Message Content Intent** (required to read message text in most guilds; without it you’ll see “Used disallowed intents” or the bot will connect but not react to messages)
+- **Server Members Intent** (recommended; required for some member/user lookups and allowlist matching in guilds)
+
+You usually do **not** need **Presence Intent**.
+
+### 3) Generate an invite URL (OAuth2 URL Generator)
+In your app: **OAuth2** → **URL Generator**
+
+**Scopes**
+- ✅ `bot`
+- ✅ `applications.commands` (only if you want slash commands; otherwise leave unchecked)
+
+**Bot Permissions** (minimal baseline)
+- ✅ View Channels
+- ✅ Send Messages
+- ✅ Read Message History
+- ✅ Embed Links
+- ✅ Attach Files
+- ✅ Add Reactions (optional but recommended)
+- ✅ Use External Emojis / Stickers (optional; only if you want them)
+
+Avoid **Administrator** unless you’re debugging and fully trust the bot.
+
+Copy the generated URL, open it, pick your server, and install the bot.
+
+### 4) Get the ids (guild/user/channel)
+Discord uses numeric ids everywhere; Clawdbot config prefers ids.
+
+1. Discord (desktop/web) → **User Settings** → **Advanced** → enable **Developer Mode**
+2. Right-click:
+   - Server name → **Copy Server ID** (guild id)
+   - Channel (e.g. `#help`) → **Copy Channel ID**
+   - Your user → **Copy User ID**
+
+### 5) Configure Clawdbot
+
+#### Token
+Set the bot token via env var (recommended on servers):
+- `DISCORD_BOT_TOKEN=...`
+
+Or via config:
+
+```json5
+{
+  discord: {
+    enabled: true,
+    token: "YOUR_BOT_TOKEN"
+  }
+}
+```
+
+#### Allowlist + channel routing
+Example “single server, only allow me, only allow #help”:
+
+```json5
+{
+  discord: {
+    enabled: true,
+    dm: { enabled: false },
+    guilds: {
+      "YOUR_GUILD_ID": {
+        users: ["YOUR_USER_ID"],
+        requireMention: true,
+        channels: {
+          help: { allow: true, requireMention: true }
+        }
+      }
+    }
+  }
+}
+```
+
+Notes:
+- `requireMention: true` means the bot only replies when mentioned (recommended for shared channels).
+- If `channels` is present, any channel not listed is denied by default.
+
+### 6) Verify it works
+1. Start the gateway.
+2. In your server channel, send: `@Krill hello` (or whatever your bot name is).
+3. If nothing happens: check **Troubleshooting** below.
+
+### Troubleshooting
+- **“Used disallowed intents”**: enable **Message Content Intent** (and likely **Server Members Intent**) in the Developer Portal, then restart the gateway.
+- **Bot connects but never replies in a guild channel**:
+  - Missing **Message Content Intent**, or
+  - The bot lacks channel permissions (View/Send/Read History), or
+  - Your config requires mentions and you didn’t mention it, or
+  - Your guild/channel allowlist denies the channel/user.
+- **DMs don’t work**: `discord.dm.enabled` may be `false` or `discord.dm.allowFrom` doesn’t include you.
+
+## Capabilities & limits
+- DMs and guild text channels (threads are treated as separate channels; voice not supported).
+- Typing indicators sent best-effort; message chunking honors Discord’s 2k character limit.
+- File uploads supported up to the configured `discord.mediaMaxMb` (default 8 MB).
+- Mention-gated guild replies by default to avoid noisy bots.
+- Reply context is injected when a message references another message (quoted content + ids).
+- Native reply threading is **off by default**; enable with `discord.replyToMode` and reply tags.
+
+## Config
+
+```json5
+{
+  discord: {
+    enabled: true,
+    token: "abc.123",
+    mediaMaxMb: 8,
+    actions: {
+      reactions: true,
+      stickers: true,
+      polls: true,
+      permissions: true,
+      messages: true,
+      threads: true,
+      pins: true,
+      search: true,
+      memberInfo: true,
+      roleInfo: true,
+      roles: false,
+      channelInfo: true,
+      voiceStatus: true,
+      events: true,
+      moderation: false
+    },
+    replyToMode: "off",
+    slashCommand: {
+      enabled: true,
+      name: "clawd",
+      sessionPrefix: "discord:slash",
+      ephemeral: true
+    },
+    dm: {
+      enabled: true,
+      allowFrom: ["123456789012345678", "steipete"],
+      groupEnabled: false,
+      groupChannels: ["clawd-dm"]
+    },
+    guilds: {
+      "*": { requireMention: true },
+      "123456789012345678": {
+        slug: "friends-of-clawd",
+        requireMention: false,
+        reactionNotifications: "own",
+        users: ["987654321098765432", "steipete"],
+        channels: {
+          general: { allow: true },
+          help: { allow: true, requireMention: true }
+        }
+      }
+    }
+  }
+}
+```
+
+- `dm.enabled`: set `false` to ignore all DMs (default `true`).
+- `dm.allowFrom`: DM allowlist (user ids or names). Omit or set to `["*"]` to allow any DM sender.
+- `dm.groupEnabled`: enable group DMs (default `false`).
+- `dm.groupChannels`: optional allowlist for group DM channel ids or slugs.
+- `guilds`: per-guild rules keyed by guild id (preferred) or slug.
+- `guilds."*"`: default per-guild settings applied when no explicit entry exists.
+- `guilds.<id>.slug`: optional friendly slug used for display names.
+- `guilds.<id>.users`: optional per-guild user allowlist (ids or names).
+- `guilds.<id>.channels`: channel rules (keys are channel slugs or ids).
+- `guilds.<id>.requireMention`: per-guild mention requirement (overridable per channel).
+- `guilds.<id>.reactionNotifications`: reaction system event mode (`off`, `own`, `all`, `allowlist`).
+- `slashCommand`: optional config for user-installed slash commands (ephemeral responses).
+- `mediaMaxMb`: clamp inbound media saved to disk.
+- `historyLimit`: number of recent guild messages to include as context when replying to a mention (default 20, `0` disables).
+- `actions`: per-action tool gates; omit to allow all (set `false` to disable).
+  - `reactions` (covers react + read reactions)
+  - `stickers`, `polls`, `permissions`, `messages`, `threads`, `pins`, `search`
+  - `memberInfo`, `roleInfo`, `channelInfo`, `voiceStatus`, `events`
+  - `roles` (role add/remove, default `false`)
+  - `moderation` (timeout/kick/ban, default `false`)
+
+Reaction notifications use `guilds.<id>.reactionNotifications`:
+- `off`: no reaction events.
+- `own`: reactions on the bot's own messages (default).
+- `all`: all reactions on all messages.
+- `allowlist`: reactions from `guilds.<id>.users` on all messages (empty list disables).
+
+### Tool action defaults
+
+| Action group | Default | Notes |
+| --- | --- | --- |
+| reactions | enabled | React + list reactions + emojiList |
+| stickers | enabled | Send stickers |
+| polls | enabled | Create polls |
+| permissions | enabled | Channel permission snapshot |
+| messages | enabled | Read/send/edit/delete |
+| threads | enabled | Create/list/reply |
+| pins | enabled | Pin/unpin/list |
+| search | enabled | Message search (preview spec) |
+| memberInfo | enabled | Member info |
+| roleInfo | enabled | Role list |
+| channelInfo | enabled | Channel info + list |
+| voiceStatus | enabled | Voice state lookup |
+| events | enabled | List/create scheduled events |
+| roles | disabled | Role add/remove |
+| moderation | disabled | Timeout/kick/ban |
+- `replyToMode`: `off` (default), `first`, or `all`. Applies only when the model includes a reply tag.
+
+## Reply tags
+To request a threaded reply, the model can include one tag in its output:
+- `[[reply_to_current]]` — reply to the triggering Discord message.
+- `[[reply_to:<id>]]` — reply to a specific message id from context/history.
+Current message ids are appended to prompts as `[message_id: …]`; history entries already include ids.
+
+Behavior is controlled by `discord.replyToMode`:
+- `off`: ignore tags.
+- `first`: only the first outbound chunk/attachment is a reply.
+- `all`: every outbound chunk/attachment is a reply.
+
+Allowlist matching notes:
+- `allowFrom`/`users`/`groupChannels` accept ids, names, tags, or mentions like `<@id>`.
+- Prefixes like `discord:`/`user:` (users) and `channel:` (group DMs) are supported.
+- Use `*` to allow any sender/channel.
+- When `guilds.<id>.channels` is present, channels not listed are denied by default.
+
+Slash command notes:
+- Register a chat input command in Discord with at least one string option (e.g., `prompt`).
+- The first non-empty string option is treated as the prompt.
+- Slash commands honor the same allowlists as DMs/guild messages (`discord.dm.allowFrom`, `discord.guilds`, per-channel rules).
+- Clawdbot will auto-register `/clawd` (or the configured name) if it doesn't already exist.
+
+## Tool actions
+The agent can call `discord` with actions like:
+- `react` / `reactions` (add or list reactions)
+- `sticker`, `poll`, `permissions`
+- `readMessages`, `sendMessage`, `editMessage`, `deleteMessage`
+- `threadCreate`, `threadList`, `threadReply`
+- `pinMessage`, `unpinMessage`, `listPins`
+- `searchMessages`, `memberInfo`, `roleInfo`, `roleAdd`, `roleRemove`, `emojiList`
+- `channelInfo`, `channelList`, `voiceStatus`, `eventList`, `eventCreate`
+- `timeout`, `kick`, `ban`
+
+Discord message ids are surfaced in the injected context (`[discord message id: …]` and history lines) so the agent can target them.
+Emoji can be unicode (e.g., `✅`) or custom emoji syntax like `<:party_blob:1234567890>`.
+
+## Safety & ops
+- Treat the bot token like a password; prefer the `DISCORD_BOT_TOKEN` env var on supervised hosts or lock down the config file permissions.
+- Only grant the bot permissions it needs (typically Read/Send Messages).
+- If the bot is stuck or rate limited, restart the gateway (`clawdbot gateway --force`) after confirming no other processes own the Discord session.

package/docs/discovery.md

@@ -0,0 +1,112 @@
+---
+summary: "Node discovery and transports (Bonjour, Tailscale, SSH) for finding the gateway"
+read_when:
+  - Implementing or changing Bonjour discovery/advertising
+  - Adjusting remote connection modes (direct vs SSH)
+  - Designing bridge + pairing for remote nodes
+---
+# Discovery & transports
+
+Clawdbot has two distinct problems that look similar on the surface:
+
+1) **Operator remote control**: the macOS menu bar app controlling a gateway running elsewhere.
+2) **Node pairing**: iOS/Android (and future nodes) finding a gateway and pairing securely.
+
+The design goal is to keep all network discovery/advertising in the **Node Gateway** (`clawd` / `clawdbot gateway`) and keep clients (mac app, iOS) as consumers.
+
+## Terms
+
+- **Gateway**: the single, long-running gateway process that owns state (sessions, pairing, node registry) and runs providers.
+- **Gateway WS (loopback)**: the existing gateway WebSocket control endpoint on `127.0.0.1:18789`.
+- **Bridge (direct transport)**: a LAN/tailnet-facing endpoint owned by the gateway that allows authenticated clients/nodes to call a scoped subset of gateway methods. The bridge exists so the gateway can remain loopback-only.
+- **SSH transport (fallback)**: remote control by forwarding `127.0.0.1:18789` over SSH.
+
+## Why we keep both “direct” and SSH
+
+- **Direct bridge** is the best UX on the same network and within a tailnet:
+  - auto-discovery on LAN via Bonjour
+  - pairing tokens + ACLs owned by the gateway
+  - no shell access required; protocol surface can stay tight and auditable
+- **SSH** remains the universal fallback:
+  - works anywhere you have SSH access (even across unrelated networks)
+  - survives multicast/mDNS issues
+  - requires no new inbound ports besides SSH
+
+## Discovery inputs (how clients learn where the gateway is)
+
+### 1) Bonjour / mDNS (LAN only)
+
+Bonjour is best-effort and does not cross networks. It is only used for “same LAN” convenience.
+
+Target direction:
+- The **gateway** advertises its bridge via Bonjour.
+- Clients browse and show a “pick a gateway” list, then store the chosen endpoint.
+
+Troubleshooting and beacon details: `docs/bonjour.md`.
+
+#### Current implementation
+
+- Service types:
+  - `_clawdbot-bridge._tcp` (bridge transport beacon)
+- TXT keys (non-secret):
+  - `role=gateway`
+  - `lanHost=<hostname>.local`
+  - `sshPort=22` (or whatever is advertised)
+  - `gatewayPort=18789` (loopback WS port; informational)
+  - `bridgePort=18790` (when bridge is enabled)
+  - `canvasPort=18793` (default canvas host port; serves `/__clawdbot__/canvas/`)
+  - `cliPath=<path>` (optional; absolute path to a runnable `clawdbot` entrypoint or binary)
+  - `tailnetDns=<magicdns>` (optional hint; auto-detected when Tailscale is available)
+
+Disable/override:
+- `CLAWDBOT_DISABLE_BONJOUR=1` disables advertising.
+- `CLAWDBOT_BRIDGE_ENABLED=0` disables the bridge listener.
+- `bridge.bind` / `bridge.port` in `~/.clawdbot/clawdbot.json` control bridge bind/port (preferred).
+- `CLAWDBOT_BRIDGE_HOST` / `CLAWDBOT_BRIDGE_PORT` still work as a back-compat override when `bridge.bind` / `bridge.port` are not set.
+- `CLAWDBOT_SSH_PORT` overrides the SSH port advertised in the bridge beacon (defaults to 22).
+- `CLAWDBOT_TAILNET_DNS` publishes a `tailnetDns` hint (MagicDNS) in the bridge beacon (auto-detected if unset).
+
+### 2) Tailnet (cross-network)
+
+For London/Vienna style setups, Bonjour won’t help. The recommended “direct” target is:
+- Tailscale MagicDNS name (preferred) or a stable tailnet IP.
+
+If the gateway can detect it is running under Tailscale, it publishes `tailnetDns` as an optional hint for clients (including wide-area beacons).
+
+### 3) Manual / SSH target
+
+When there is no direct route (or direct is disabled), clients can always connect via SSH by forwarding the loopback gateway port.
+
+See `docs/remote.md`.
+
+## Transport selection (client policy)
+
+Recommended client behavior:
+
+1) If a paired direct endpoint is configured and reachable, use it.
+2) Else, if Bonjour finds a gateway on LAN, offer a one-tap “Use this gateway” choice and save it as the direct endpoint.
+3) Else, if a tailnet DNS/IP is configured, try direct.
+4) Else, fall back to SSH.
+
+## Pairing + auth (direct transport)
+
+The gateway is the source of truth for node/client admission.
+
+- Pairing requests are created/approved/rejected in the gateway (see `docs/gateway/pairing.md`).
+- The bridge enforces:
+  - auth (token / keypair)
+  - scopes/ACLs (bridge is not a raw proxy to every gateway method)
+  - rate limits
+
+## Where the code lives (target architecture)
+
+- Node gateway:
+  - advertises discovery beacons (Bonjour)
+  - owns pairing storage + decisions
+  - runs the bridge listener (direct transport)
+- macOS app:
+  - UI for picking a gateway, showing pairing prompts, and troubleshooting
+  - SSH tunneling only for the fallback path
+- iOS node:
+  - browses Bonjour (LAN) as a convenience only
+  - uses direct transport + pairing to connect to the gateway

package/docs/docker.md

@@ -0,0 +1,251 @@
+---
+summary: "Optional Docker-based setup and onboarding for Clawdbot"
+read_when:
+  - You want a containerized gateway instead of local installs
+  - You are validating the Docker flow
+---
+
+# Docker (optional)
+
+Docker is **optional**. Use it only if you want a containerized gateway or to validate the Docker flow.
+
+This guide covers:
+- Containerized Gateway (full Clawdbot in Docker)
+- Per-session Agent Sandbox (host gateway + Docker-isolated agent tools)
+
+## Requirements
+
+- Docker Desktop (or Docker Engine) + Docker Compose v2
+- Enough disk for images + logs
+
+## Containerized Gateway (Docker Compose)
+
+### Quick start (recommended)
+
+From repo root:
+
+```bash
+./docker-setup.sh
+```
+
+This script:
+- builds the gateway image
+- runs the onboarding wizard
+- runs WhatsApp login
+- starts the gateway via Docker Compose
+
+It writes config/workspace on the host:
+- `~/.clawdbot/`
+- `~/clawd`
+
+### Manual flow (compose)
+
+```bash
+docker build -t clawdbot:local -f Dockerfile .
+docker compose run --rm clawdbot-cli onboard
+docker compose run --rm clawdbot-cli login
+docker compose up -d clawdbot-gateway
+```
+
+### Health check
+
+```bash
+docker compose exec clawdbot-gateway node dist/index.js health --token "$CLAWDBOT_GATEWAY_TOKEN"
+```
+
+### E2E smoke test (Docker)
+
+```bash
+scripts/e2e/onboard-docker.sh
+```
+
+### Notes
+
+- Gateway bind defaults to `lan` for container use.
+- The gateway container is the source of truth for sessions (`~/.clawdbot/sessions`).
+
+## Per-session Agent Sandbox (host gateway + Docker tools)
+
+### What it does
+
+When `agent.sandbox` is enabled, **non-main sessions** run tools inside a Docker
+container. The gateway stays on your host, but the tool execution is isolated:
+- one container per session (hard wall)
+- per-session workspace folder mounted at `/workspace`
+- allow/deny tool policy (deny wins)
+
+### Default behavior
+
+- Image: `clawdbot-sandbox:bookworm-slim`
+- One container per session
+- Workspace per session under `~/.clawdbot/sandboxes`
+- Auto-prune: idle > 24h OR age > 7d
+- Network: `none` by default (explicitly opt-in if you need egress)
+- Default allow: `bash`, `process`, `read`, `write`, `edit`
+- Default deny: `browser`, `canvas`, `nodes`, `cron`, `discord`, `gateway`
+
+### Enable sandboxing
+
+```json5
+{
+  agent: {
+    sandbox: {
+      mode: "non-main", // off | non-main | all
+      perSession: true,
+      workspaceRoot: "~/.clawdbot/sandboxes",
+      docker: {
+        image: "clawdbot-sandbox:bookworm-slim",
+        workdir: "/workspace",
+        readOnlyRoot: true,
+        tmpfs: ["/tmp", "/var/tmp", "/run"],
+        network: "none",
+        user: "1000:1000",
+        capDrop: ["ALL"],
+        env: { LANG: "C.UTF-8" },
+        setupCommand: "apt-get update && apt-get install -y git curl jq",
+        pidsLimit: 256,
+        memory: "1g",
+        memorySwap: "2g",
+        cpus: 1,
+        ulimits: {
+          nofile: { soft: 1024, hard: 2048 },
+          nproc: 256
+        },
+        seccompProfile: "/path/to/seccomp.json",
+        apparmorProfile: "clawdbot-sandbox",
+        dns: ["1.1.1.1", "8.8.8.8"],
+        extraHosts: ["internal.service:10.0.0.5"]
+      },
+      tools: {
+        allow: ["bash", "process", "read", "write", "edit"],
+        deny: ["browser", "canvas", "nodes", "cron", "discord", "gateway"]
+      },
+      prune: {
+        idleHours: 24, // 0 disables idle pruning
+        maxAgeDays: 7  // 0 disables max-age pruning
+      }
+    }
+  }
+}
+```
+
+Hardening knobs live under `agent.sandbox.docker`:
+`network`, `user`, `pidsLimit`, `memory`, `memorySwap`, `cpus`, `ulimits`,
+`seccompProfile`, `apparmorProfile`, `dns`, `extraHosts`.
+
+### Build the default sandbox image
+
+```bash
+scripts/sandbox-setup.sh
+```
+
+This builds `clawdbot-sandbox:bookworm-slim` using `Dockerfile.sandbox`.
+
+### Sandbox common image (optional)
+If you want a sandbox image with common build tooling (Node, Go, Rust, etc.), build the common image:
+
+```bash
+scripts/sandbox-common-setup.sh
+```
+
+This builds `clawdbot-sandbox-common:bookworm-slim`. To use it:
+
+```json5
+{
+  agent: { sandbox: { docker: { image: "clawdbot-sandbox-common:bookworm-slim" } } }
+}
+```
+
+### Sandbox browser image
+
+To run the browser tool inside the sandbox, build the browser image:
+
+```bash
+scripts/sandbox-browser-setup.sh
+```
+
+This builds `clawdbot-sandbox-browser:bookworm-slim` using
+`Dockerfile.sandbox-browser`. The container runs Chromium with CDP enabled and
+an optional noVNC observer (headful via Xvfb).
+
+Notes:
+- Headful (Xvfb) reduces bot blocking vs headless.
+- Headless can still be used by setting `agent.sandbox.browser.headless=true`.
+- No full desktop environment (GNOME) is needed; Xvfb provides the display.
+
+Use config:
+
+```json5
+{
+  agent: {
+    sandbox: {
+      browser: { enabled: true }
+    }
+  }
+}
+```
+
+Custom browser image:
+
+```json5
+{
+  agent: {
+    sandbox: { browser: { image: "my-clawdbot-browser" } }
+  }
+}
+```
+
+When enabled, the agent receives:
+- a sandbox browser control URL (for the `browser` tool)
+- a noVNC URL (if enabled and headless=false)
+
+Remember: if you use an allowlist for tools, add `browser` (and remove it from
+deny) or the tool remains blocked.
+Prune rules (`agent.sandbox.prune`) apply to browser containers too.
+
+### Custom sandbox image
+
+Build your own image and point config to it:
+
+```bash
+docker build -t my-clawdbot-sbx -f Dockerfile.sandbox .
+```
+
+```json5
+{
+  agent: {
+    sandbox: { docker: { image: "my-clawdbot-sbx" } }
+  }
+}
+```
+
+### Tool policy (allow/deny)
+
+- `deny` wins over `allow`.
+- If `allow` is empty: all tools (except deny) are available.
+- If `allow` is non-empty: only tools in `allow` are available (minus deny).
+
+### Pruning strategy
+
+Two knobs:
+- `prune.idleHours`: remove containers not used in X hours (0 = disable)
+- `prune.maxAgeDays`: remove containers older than X days (0 = disable)
+
+Example:
+- Keep busy sessions but cap lifetime:
+  `idleHours: 24`, `maxAgeDays: 7`
+- Never prune:
+  `idleHours: 0`, `maxAgeDays: 0`
+
+### Security notes
+
+- Hard wall only applies to **tools** (bash/read/write/edit).  
+- Host-only tools like browser/camera/canvas are blocked by default.  
+- Allowing `browser` in sandbox **breaks isolation** (browser runs on host).
+
+## Troubleshooting
+
+- Image missing: build with `scripts/sandbox-setup.sh` or set `agent.sandbox.docker.image`.
+- Container not running: it will auto-create per session on demand.
+- Permission errors in sandbox: set `docker.user` to a UID:GID that matches your
+  mounted workspace ownership (or chown the workspace folder).