docs(security): explain sandboxing options

docs/configuration.md

@@ -736,7 +736,7 @@ Defaults (if enabled):
 - Debian bookworm-slim based image
 - workspace per session under `~/.clawdbot/sandboxes`
 - auto-prune: idle > 24h OR age > 7d
-- tools: allow only `bash`, `process`, `read`, `write`, `edit` (deny wins)
+- tools: allow only `bash`, `process`, `read`, `write`, `edit`, `sessions_list`, `sessions_history`, `sessions_send`, `sessions_spawn` (deny wins)
 - optional sandboxed browser (Chromium + CDP, noVNC observer)
 - hardening knobs: `network`, `user`, `pidsLimit`, `memory`, `cpus`, `ulimits`, `seccompProfile`, `apparmorProfile`
 
@@ -782,7 +782,7 @@ Defaults (if enabled):
         enableNoVnc: true
       },
       tools: {
-        allow: ["bash", "process", "read", "write", "edit"],
+        allow: ["bash", "process", "read", "write", "edit", "sessions_list", "sessions_history", "sessions_send", "sessions_spawn"],
         deny: ["browser", "canvas", "nodes", "cron", "discord", "gateway"]
       },
       prune: {

docs/docker.md

@@ -88,7 +88,7 @@ container. The gateway stays on your host, but the tool execution is isolated:
 - 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 allow: `bash`, `process`, `read`, `write`, `edit`, `sessions_list`, `sessions_history`, `sessions_send`, `sessions_spawn`
 - Default deny: `browser`, `canvas`, `nodes`, `cron`, `discord`, `gateway`
 
 ### Enable sandboxing

docs/security.md

@@ -137,28 +137,56 @@ We're considering a `readOnlyMode` flag that prevents the AI from:
 - Executing shell commands
 - Sending messages
 
-## Container Isolation (Recommended)
+## Sandboxing Principles (Recommended)
 
-For maximum security, run CLAWDBOT in a container with limited access:
+If you let an agent execute commands, your best defense is to **reduce the blast
+radius**:
+- keep the filesystem the agent can touch small
+- default to “no network”
+- run with least privileges (no root, no caps, no new privileges)
+- keep “escape hatches” (like host-elevated bash) gated behind explicit allowlists
 
-```yaml
-# docker-compose.yml
-services:
-  clawdbot:
-    build: .
-    volumes:
-      - ./clawd-sandbox:/home/clawd  # Limited filesystem
-      - /tmp/clawdbot:/tmp/clawdbot    # Logs
-    environment:
-      - CLAWDBOT_SANDBOX=true
-    network_mode: bridge  # Limited network
-```
+Clawdbot supports two complementary sandboxing approaches:
 
-### Per-session sandbox (Clawdbot-native)
+### Option A: Run the full Gateway in Docker (containerized deployment)
 
-Clawdbot can also run **non-main sessions** inside per-session Docker containers
-(`agent.sandbox`). This keeps the gateway on your host while isolating agent
-tools in a hard wall container. See `docs/configuration.md` for the full config.
+This runs the Gateway (and its provider integrations) inside a Docker container.
+If you do this right, the container becomes the “host boundary”, and you only
+expose what you explicitly mount in.
+
+Docs: `docs/docker.md` (Docker Compose setup + onboarding).
+
+Hardening reminders:
+- Don’t mount your entire home directory.
+- Don’t pass long-lived secrets the agent doesn’t need.
+- Treat mounted volumes as “reachable by the agent”.
+
+### Option B: Per-session tool sandbox (host Gateway + Docker-isolated tools)
+
+This keeps the Gateway on your host, but runs **tool execution** for selected
+sessions inside per-session Docker containers (`agent.sandbox`).
+
+Typical usage: `agent.sandbox.mode: "non-main"` so group/channel sessions get a
+hard wall, while your main/admin session can keep full host access.
+
+What it isolates:
+- `bash` runs via `docker exec` inside the sandbox container.
+- file tools (`read`/`write`/`edit`) are restricted to the sandbox workspace.
+- sandbox paths enforce “no escape” and block symlink tricks.
+
+Default container hardening (configurable via `agent.sandbox.docker`):
+- read-only root filesystem
+- `--security-opt no-new-privileges`
+- `capDrop: ["ALL"]`
+- network `"none"` by default
+- per-session workspace mounted at `/workspace`
+
+Docs:
+- `docs/configuration.md` → `agent.sandbox`
+- `docs/docker.md` → “Per-session Agent 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.
 
 Expose only the services your AI needs:
 - ✅ WhatsApp Web session (Baileys) / Telegram Bot API / etc.