@quantumclaw/quantumclaw 2026.3.22

package/docs/gateway/sandbox-vs-tool-policy-vs-elevated.md

@@ -0,0 +1,134 @@
+---
+title: Sandbox vs Tool Policy vs Elevated
+summary: "Why a tool is blocked: sandbox runtime, tool allow/deny policy, and elevated exec gates"
+read_when: "You hit 'sandbox jail' or see a tool/elevated refusal and want the exact config key to change."
+status: active
+---
+
+# Sandbox vs Tool Policy vs Elevated
+
+QuantumClaw has three related (but different) controls:
+
+1. **Sandbox** (`agents.defaults.sandbox.*` / `agents.list[].sandbox.*`) decides **where tools run** (Docker vs host).
+2. **Tool policy** (`tools.*`, `tools.sandbox.tools.*`, `agents.list[].tools.*`) decides **which tools are available/allowed**.
+3. **Elevated** (`tools.elevated.*`, `agents.list[].tools.elevated.*`) is an **exec-only escape hatch** to run on the host when you’re sandboxed.
+
+## Quick debug
+
+Use the inspector to see what QuantumClaw is _actually_ doing:
+
+```bash
+quantumclaw sandbox explain
+quantumclaw sandbox explain --session agent:main:main
+quantumclaw sandbox explain --agent work
+quantumclaw sandbox explain --json
+```
+
+It prints:
+
+- effective sandbox mode/scope/workspace access
+- whether the session is currently sandboxed (main vs non-main)
+- effective sandbox tool allow/deny (and whether it came from agent/global/default)
+- elevated gates and fix-it key paths
+
+## Sandbox: where tools run
+
+Sandboxing is controlled by `agents.defaults.sandbox.mode`:
+
+- `"off"`: everything runs on the host.
+- `"non-main"`: only non-main sessions are sandboxed (common “surprise” for groups/channels).
+- `"all"`: everything is sandboxed.
+
+See [Sandboxing](/gateway/sandboxing) for the full matrix (scope, workspace mounts, images).
+
+### Bind mounts (security quick check)
+
+- `docker.binds` _pierces_ the sandbox filesystem: whatever you mount is visible inside the container with the mode you set (`:ro` or `:rw`).
+- Default is read-write if you omit the mode; prefer `:ro` for source/secrets.
+- `scope: "shared"` ignores per-agent binds (only global binds apply).
+- Binding `/var/run/docker.sock` effectively hands host control to the sandbox; only do this intentionally.
+- Workspace access (`workspaceAccess: "ro"`/`"rw"`) is independent of bind modes.
+
+## Tool policy: which tools exist/are callable
+
+Two layers matter:
+
+- **Tool profile**: `tools.profile` and `agents.list[].tools.profile` (base allowlist)
+- **Provider tool profile**: `tools.byProvider[provider].profile` and `agents.list[].tools.byProvider[provider].profile`
+- **Global/per-agent tool policy**: `tools.allow`/`tools.deny` and `agents.list[].tools.allow`/`agents.list[].tools.deny`
+- **Provider tool policy**: `tools.byProvider[provider].allow/deny` and `agents.list[].tools.byProvider[provider].allow/deny`
+- **Sandbox tool policy** (only applies when sandboxed): `tools.sandbox.tools.allow`/`tools.sandbox.tools.deny` and `agents.list[].tools.sandbox.tools.*`
+
+Rules of thumb:
+
+- `deny` always wins.
+- If `allow` is non-empty, everything else is treated as blocked.
+- Tool policy is the hard stop: `/exec` cannot override a denied `exec` tool.
+- `/exec` only changes session defaults for authorized senders; it does not grant tool access.
+  Provider tool keys accept either `provider` (e.g. `google-antigravity`) or `provider/model` (e.g. `openai/gpt-5.2`).
+
+### Tool groups (shorthands)
+
+Tool policies (global, agent, sandbox) support `group:*` entries that expand to multiple tools:
+
+```json5
+{
+  tools: {
+    sandbox: {
+      tools: {
+        allow: ["group:runtime", "group:fs", "group:sessions", "group:memory"],
+      },
+    },
+  },
+}
+```
+
+Available groups:
+
+- `group:runtime`: `exec`, `bash`, `process`
+- `group:fs`: `read`, `write`, `edit`, `apply_patch`
+- `group:sessions`: `sessions_list`, `sessions_history`, `sessions_send`, `sessions_spawn`, `session_status`
+- `group:memory`: `memory_search`, `memory_get`
+- `group:ui`: `browser`, `canvas`
+- `group:automation`: `cron`, `gateway`
+- `group:messaging`: `message`
+- `group:nodes`: `nodes`
+- `group:quantumclaw`: all built-in QuantumClaw tools (excludes provider plugins)
+
+## Elevated: exec-only "run on host"
+
+Elevated does **not** grant extra tools; it only affects `exec`.
+
+- If you’re sandboxed, `/elevated on` (or `exec` with `elevated: true`) runs on the host (approvals may still apply).
+- Use `/elevated full` to skip exec approvals for the session.
+- If you’re already running direct, elevated is effectively a no-op (still gated).
+- Elevated is **not** skill-scoped and does **not** override tool allow/deny.
+- `/exec` is separate from elevated. It only adjusts per-session exec defaults for authorized senders.
+
+Gates:
+
+- Enablement: `tools.elevated.enabled` (and optionally `agents.list[].tools.elevated.enabled`)
+- Sender allowlists: `tools.elevated.allowFrom.<provider>` (and optionally `agents.list[].tools.elevated.allowFrom.<provider>`)
+
+See [Elevated Mode](/tools/elevated).
+
+## Common "sandbox jail" fixes
+
+### "Tool X blocked by sandbox tool policy"
+
+Fix-it keys (pick one):
+
+- Disable sandbox: `agents.defaults.sandbox.mode=off` (or per-agent `agents.list[].sandbox.mode=off`)
+- Allow the tool inside sandbox:
+  - remove it from `tools.sandbox.tools.deny` (or per-agent `agents.list[].tools.sandbox.tools.deny`)
+  - or add it to `tools.sandbox.tools.allow` (or per-agent allow)
+
+### "I thought this was main, why is it sandboxed?"
+
+In `"non-main"` mode, group/channel keys are _not_ main. Use the main session key (shown by `sandbox explain`) or switch mode to `"off"`.
+
+## See also
+
+- [Sandboxing](/gateway/sandboxing) -- full sandbox reference (modes, scopes, backends, images)
+- [Multi-Agent Sandbox & Tools](/tools/multi-agent-sandbox-tools) -- per-agent overrides and precedence
+- [Elevated Mode](/tools/elevated)

package/docs/gateway/sandboxing.md

@@ -0,0 +1,469 @@
+---
+summary: "How QuantumClaw sandboxing works: modes, scopes, workspace access, and images"
+title: Sandboxing
+read_when: "You want a dedicated explanation of sandboxing or need to tune agents.defaults.sandbox."
+status: active
+---
+
+# Sandboxing
+
+QuantumClaw can run **tools inside sandbox backends** to reduce blast radius.
+This is **optional** and controlled by configuration (`agents.defaults.sandbox` or
+`agents.list[].sandbox`). If sandboxing is off, tools run on the host.
+The Gateway stays on the host; tool execution runs in an isolated sandbox
+when enabled.
+
+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 (`exec`, `read`, `write`, `edit`, `apply_patch`, `process`, etc.).
+- Optional sandboxed browser (`agents.defaults.sandbox.browser`).
+  - By default, the sandbox browser auto-starts (ensures CDP is reachable) when the browser tool needs it.
+    Configure via `agents.defaults.sandbox.browser.autoStart` and `agents.defaults.sandbox.browser.autoStartTimeoutMs`.
+  - By default, sandbox browser containers use a dedicated Docker network (`quantumclaw-sandbox-browser`) instead of the global `bridge` network.
+    Configure with `agents.defaults.sandbox.browser.network`.
+  - Optional `agents.defaults.sandbox.browser.cdpSourceRange` restricts container-edge CDP ingress with a CIDR allowlist (for example `172.21.0.1/32`).
+  - noVNC observer access is password-protected by default; QuantumClaw emits a short-lived token URL that serves a local bootstrap page and opens noVNC with password in URL fragment (not query/header logs).
+  - `agents.defaults.sandbox.browser.allowHostControl` lets sandboxed sessions target the host browser explicitly.
+  - Optional allowlists gate `target: "custom"`: `allowedControlUrls`, `allowedControlHosts`, `allowedControlPorts`.
+
+Not sandboxed:
+
+- The Gateway process itself.
+- Any tool explicitly allowed to run on the host (e.g. `tools.elevated`).
+  - **Elevated exec runs on the host and bypasses sandboxing.**
+  - If sandboxing is off, `tools.elevated` does not change execution (already on host). See [Elevated Mode](/tools/elevated).
+
+## Modes
+
+`agents.defaults.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.
+  Note: `"non-main"` is based on `session.mainKey` (default `"main"`), not agent id.
+  Group/channel sessions use their own keys, so they count as non-main and will be sandboxed.
+
+## Scope
+
+`agents.defaults.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.
+
+## Backend
+
+`agents.defaults.sandbox.backend` controls **which runtime** provides the sandbox:
+
+- `"docker"` (default): local Docker-backed sandbox runtime.
+- `"ssh"`: generic SSH-backed remote sandbox runtime.
+- `"openshell"`: OpenShell-backed sandbox runtime.
+
+SSH-specific config lives under `agents.defaults.sandbox.ssh`.
+OpenShell-specific config lives under `plugins.entries.openshell.config`.
+
+### Choosing a backend
+
+|                     | Docker                           | SSH                            | OpenShell                                           |
+| ------------------- | -------------------------------- | ------------------------------ | --------------------------------------------------- |
+| **Where it runs**   | Local container                  | Any SSH-accessible host        | OpenShell managed sandbox                           |
+| **Setup**           | `scripts/sandbox-setup.sh`       | SSH key + target host          | OpenShell plugin enabled                            |
+| **Workspace model** | Bind-mount or copy               | Remote-canonical (seed once)   | `mirror` or `remote`                                |
+| **Network control** | `docker.network` (default: none) | Depends on remote host         | Depends on OpenShell                                |
+| **Browser sandbox** | Supported                        | Not supported                  | Not supported yet                                   |
+| **Bind mounts**     | `docker.binds`                   | N/A                            | N/A                                                 |
+| **Best for**        | Local dev, full isolation        | Offloading to a remote machine | Managed remote sandboxes with optional two-way sync |
+
+### SSH backend
+
+Use `backend: "ssh"` when you want QuantumClaw to sandbox `exec`, file tools, and media reads on
+an arbitrary SSH-accessible machine.
+
+```json5
+{
+  agents: {
+    defaults: {
+      sandbox: {
+        mode: "all",
+        backend: "ssh",
+        scope: "session",
+        workspaceAccess: "rw",
+        ssh: {
+          target: "user@gateway-host:22",
+          workspaceRoot: "/tmp/quantumclaw-sandboxes",
+          strictHostKeyChecking: true,
+          updateHostKeys: true,
+          identityFile: "~/.ssh/id_ed25519",
+          certificateFile: "~/.ssh/id_ed25519-cert.pub",
+          knownHostsFile: "~/.ssh/known_hosts",
+          // Or use SecretRefs / inline contents instead of local files:
+          // identityData: { source: "env", provider: "default", id: "SSH_IDENTITY" },
+          // certificateData: { source: "env", provider: "default", id: "SSH_CERTIFICATE" },
+          // knownHostsData: { source: "env", provider: "default", id: "SSH_KNOWN_HOSTS" },
+        },
+      },
+    },
+  },
+}
+```
+
+How it works:
+
+- QuantumClaw creates a per-scope remote root under `sandbox.ssh.workspaceRoot`.
+- On first use after create or recreate, QuantumClaw seeds that remote workspace from the local workspace once.
+- After that, `exec`, `read`, `write`, `edit`, `apply_patch`, prompt media reads, and inbound media staging run directly against the remote workspace over SSH.
+- QuantumClaw does not sync remote changes back to the local workspace automatically.
+
+Authentication material:
+
+- `identityFile`, `certificateFile`, `knownHostsFile`: use existing local files and pass them through OpenSSH config.
+- `identityData`, `certificateData`, `knownHostsData`: use inline strings or SecretRefs. QuantumClaw resolves them through the normal secrets runtime snapshot, writes them to temp files with `0600`, and deletes them when the SSH session ends.
+- If both `*File` and `*Data` are set for the same item, `*Data` wins for that SSH session.
+
+This is a **remote-canonical** model. The remote SSH workspace becomes the real sandbox state after the initial seed.
+
+Important consequences:
+
+- Host-local edits made outside QuantumClaw after the seed step are not visible remotely until you recreate the sandbox.
+- `quantumclaw sandbox recreate` deletes the per-scope remote root and seeds again from local on next use.
+- Browser sandboxing is not supported on the SSH backend.
+- `sandbox.docker.*` settings do not apply to the SSH backend.
+
+### OpenShell backend
+
+Use `backend: "openshell"` when you want QuantumClaw to sandbox tools in an
+OpenShell-managed remote environment. For the full setup guide, configuration
+reference, and workspace mode comparison, see the dedicated
+[OpenShell page](/gateway/openshell).
+
+OpenShell reuses the same core SSH transport and remote filesystem bridge as the
+generic SSH backend, and adds OpenShell-specific lifecycle
+(`sandbox create/get/delete`, `sandbox ssh-config`) plus the optional `mirror`
+workspace mode.
+
+```json5
+{
+  agents: {
+    defaults: {
+      sandbox: {
+        mode: "all",
+        backend: "openshell",
+        scope: "session",
+        workspaceAccess: "rw",
+      },
+    },
+  },
+  plugins: {
+    entries: {
+      openshell: {
+        enabled: true,
+        config: {
+          from: "quantumclaw",
+          mode: "remote", // mirror | remote
+          remoteWorkspaceDir: "/sandbox",
+          remoteAgentWorkspaceDir: "/agent",
+        },
+      },
+    },
+  },
+}
+```
+
+OpenShell modes:
+
+- `mirror` (default): local workspace stays canonical. QuantumClaw syncs local files into OpenShell before exec and syncs the remote workspace back after exec.
+- `remote`: OpenShell workspace is canonical after the sandbox is created. QuantumClaw seeds the remote workspace once from the local workspace, then file tools and exec run directly against the remote sandbox without syncing changes back.
+
+Remote transport details:
+
+- QuantumClaw asks OpenShell for sandbox-specific SSH config via `openshell sandbox ssh-config <name>`.
+- Core writes that SSH config to a temp file, opens the SSH session, and reuses the same remote filesystem bridge used by `backend: "ssh"`.
+- In `mirror` mode only the lifecycle differs: sync local to remote before exec, then sync back after exec.
+
+Current OpenShell limitations:
+
+- sandbox browser is not supported yet
+- `sandbox.docker.binds` is not supported on the OpenShell backend
+- Docker-specific runtime knobs under `sandbox.docker.*` still apply only to the Docker backend
+
+#### Workspace modes
+
+OpenShell has two workspace models. This is the part that matters most in practice.
+
+##### `mirror`
+
+Use `plugins.entries.openshell.config.mode: "mirror"` when you want the **local workspace to stay canonical**.
+
+Behavior:
+
+- Before `exec`, QuantumClaw syncs the local workspace into the OpenShell sandbox.
+- After `exec`, QuantumClaw syncs the remote workspace back to the local workspace.
+- File tools still operate through the sandbox bridge, but the local workspace remains the source of truth between turns.
+
+Use this when:
+
+- you edit files locally outside QuantumClaw and want those changes to show up in the sandbox automatically
+- you want the OpenShell sandbox to behave as much like the Docker backend as possible
+- you want the host workspace to reflect sandbox writes after each exec turn
+
+Tradeoff:
+
+- extra sync cost before and after exec
+
+##### `remote`
+
+Use `plugins.entries.openshell.config.mode: "remote"` when you want the **OpenShell workspace to become canonical**.
+
+Behavior:
+
+- When the sandbox is first created, QuantumClaw seeds the remote workspace from the local workspace once.
+- After that, `exec`, `read`, `write`, `edit`, and `apply_patch` operate directly against the remote OpenShell workspace.
+- QuantumClaw does **not** sync remote changes back into the local workspace after exec.
+- Prompt-time media reads still work because file and media tools read through the sandbox bridge instead of assuming a local host path.
+- Transport is SSH into the OpenShell sandbox returned by `openshell sandbox ssh-config`.
+
+Important consequences:
+
+- If you edit files on the host outside QuantumClaw after the seed step, the remote sandbox will **not** see those changes automatically.
+- If the sandbox is recreated, the remote workspace is seeded from the local workspace again.
+- With `scope: "agent"` or `scope: "shared"`, that remote workspace is shared at that same scope.
+
+Use this when:
+
+- the sandbox should live primarily on the remote OpenShell side
+- you want lower per-turn sync overhead
+- you do not want host-local edits to silently overwrite remote sandbox state
+
+Choose `mirror` if you think of the sandbox as a temporary execution environment.
+Choose `remote` if you think of the sandbox as the real workspace.
+
+#### OpenShell lifecycle
+
+OpenShell sandboxes are still managed through the normal sandbox lifecycle:
+
+- `quantumclaw sandbox list` shows OpenShell runtimes as well as Docker runtimes
+- `quantumclaw sandbox recreate` deletes the current runtime and lets QuantumClaw recreate it on next use
+- prune logic is backend-aware too
+
+For `remote` mode, recreate is especially important:
+
+- recreate deletes the canonical remote workspace for that scope
+- the next use seeds a fresh remote workspace from the local workspace
+
+For `mirror` mode, recreate mainly resets the remote execution environment
+because the local workspace remains canonical anyway.
+
+## Workspace access
+
+`agents.defaults.sandbox.workspaceAccess` controls **what the sandbox can see**:
+
+- `"none"` (default): tools see a sandbox workspace under `~/.quantumclaw/sandboxes`.
+- `"ro"`: mounts the agent workspace read-only at `/agent` (disables `write`/`edit`/`apply_patch`).
+- `"rw"`: mounts the agent workspace read/write at `/workspace`.
+
+With the OpenShell backend:
+
+- `mirror` mode still uses the local workspace as the canonical source between exec turns
+- `remote` mode uses the remote OpenShell workspace as the canonical source after the initial seed
+- `workspaceAccess: "ro"` and `"none"` still restrict write behavior the same way
+
+Inbound media is copied into the active sandbox workspace (`media/inbound/*`).
+Skills note: the `read` tool is sandbox-rooted. With `workspaceAccess: "none"`,
+QuantumClaw mirrors eligible skills into the sandbox workspace (`.../skills`) so
+they can be read. With `"rw"`, workspace skills are readable from
+`/workspace/skills`.
+
+## Custom bind mounts
+
+`agents.defaults.sandbox.docker.binds` mounts additional host directories into the container.
+Format: `host:container:mode` (e.g., `"/home/user/source:/source:rw"`).
+
+Global and per-agent binds are **merged** (not replaced). Under `scope: "shared"`, per-agent binds are ignored.
+
+`agents.defaults.sandbox.browser.binds` mounts additional host directories into the **sandbox browser** container only.
+
+- When set (including `[]`), it replaces `agents.defaults.sandbox.docker.binds` for the browser container.
+- When omitted, the browser container falls back to `agents.defaults.sandbox.docker.binds` (backwards compatible).
+
+Example (read-only source + an extra data directory):
+
+```json5
+{
+  agents: {
+    defaults: {
+      sandbox: {
+        docker: {
+          binds: ["/home/user/source:/source:ro", "/var/data/myapp:/data:ro"],
+        },
+      },
+    },
+    list: [
+      {
+        id: "build",
+        sandbox: {
+          docker: {
+            binds: ["/mnt/cache:/cache:rw"],
+          },
+        },
+      },
+    ],
+  },
+}
+```
+
+Security notes:
+
+- Binds bypass the sandbox filesystem: they expose host paths with whatever mode you set (`:ro` or `:rw`).
+- QuantumClaw blocks dangerous bind sources (for example: `docker.sock`, `/etc`, `/proc`, `/sys`, `/dev`, and parent mounts that would expose them).
+- Sensitive mounts (secrets, SSH keys, service credentials) should be `:ro` unless absolutely required.
+- Combine with `workspaceAccess: "ro"` if you only need read access to the workspace; bind modes stay independent.
+- See [Sandbox vs Tool Policy vs Elevated](/gateway/sandbox-vs-tool-policy-vs-elevated) for how binds interact with tool policy and elevated exec.
+
+## Images + setup
+
+Default Docker image: `quantumclaw-sandbox:bookworm-slim`
+
+Build it once:
+
+```bash
+scripts/sandbox-setup.sh
+```
+
+Note: the default image does **not** include Node. If a skill needs Node (or
+other runtimes), either bake a custom image or install via
+`sandbox.docker.setupCommand` (requires network egress + writable root +
+root user).
+
+If you want a more functional sandbox image with common tooling (for example
+`curl`, `jq`, `nodejs`, `python3`, `git`), build:
+
+```bash
+scripts/sandbox-common-setup.sh
+```
+
+Then set `agents.defaults.sandbox.docker.image` to
+`quantumclaw-sandbox-common:bookworm-slim`.
+
+Sandboxed browser image:
+
+```bash
+scripts/sandbox-browser-setup.sh
+```
+
+By default, Docker sandbox containers run with **no network**.
+Override with `agents.defaults.sandbox.docker.network`.
+
+The bundled sandbox browser image also applies conservative Chromium startup defaults
+for containerized workloads. Current container defaults include:
+
+- `--remote-debugging-address=127.0.0.1`
+- `--remote-debugging-port=<derived from QUANTUMCLAW_BROWSER_CDP_PORT>`
+- `--user-data-dir=${HOME}/.chrome`
+- `--no-first-run`
+- `--no-default-browser-check`
+- `--disable-3d-apis`
+- `--disable-gpu`
+- `--disable-dev-shm-usage`
+- `--disable-background-networking`
+- `--disable-extensions`
+- `--disable-features=TranslateUI`
+- `--disable-breakpad`
+- `--disable-crash-reporter`
+- `--disable-software-rasterizer`
+- `--no-zygote`
+- `--metrics-recording-only`
+- `--renderer-process-limit=2`
+- `--no-sandbox` and `--disable-setuid-sandbox` when `noSandbox` is enabled.
+- The three graphics hardening flags (`--disable-3d-apis`,
+  `--disable-software-rasterizer`, `--disable-gpu`) are optional and are useful
+  when containers lack GPU support. Set `QUANTUMCLAW_BROWSER_DISABLE_GRAPHICS_FLAGS=0`
+  if your workload requires WebGL or other 3D/browser features.
+- `--disable-extensions` is enabled by default and can be disabled with
+  `QUANTUMCLAW_BROWSER_DISABLE_EXTENSIONS=0` for extension-reliant flows.
+- `--renderer-process-limit=2` is controlled by
+  `QUANTUMCLAW_BROWSER_RENDERER_PROCESS_LIMIT=<N>`, where `0` keeps Chromium's default.
+
+If you need a different runtime profile, use a custom browser image and provide
+your own entrypoint. For local (non-container) Chromium profiles, use
+`browser.extraArgs` to append additional startup flags.
+
+Security defaults:
+
+- `network: "host"` is blocked.
+- `network: "container:<id>"` is blocked by default (namespace join bypass risk).
+- Break-glass override: `agents.defaults.sandbox.docker.dangerouslyAllowContainerNamespaceJoin: true`.
+
+Docker installs and the containerized gateway live here:
+[Docker](/install/docker)
+
+For Docker gateway deployments, `scripts/docker/setup.sh` can bootstrap sandbox config.
+Set `QUANTUMCLAW_SANDBOX=1` (or `true`/`yes`/`on`) to enable that path. You can
+override socket location with `QUANTUMCLAW_DOCKER_SOCKET`. Full setup and env
+reference: [Docker](/install/docker#enable-agent-sandbox-for-docker-gateway-opt-in).
+
+## setupCommand (one-time container setup)
+
+`setupCommand` runs **once** after the sandbox container is created (not on every run).
+It executes inside the container via `sh -lc`.
+
+Paths:
+
+- Global: `agents.defaults.sandbox.docker.setupCommand`
+- Per-agent: `agents.list[].sandbox.docker.setupCommand`
+
+Common pitfalls:
+
+- Default `docker.network` is `"none"` (no egress), so package installs will fail.
+- `docker.network: "container:<id>"` requires `dangerouslyAllowContainerNamespaceJoin: true` and is break-glass only.
+- `readOnlyRoot: true` prevents writes; set `readOnlyRoot: false` or bake a custom image.
+- `user` must be root for package installs (omit `user` or set `user: "0:0"`).
+- Sandbox exec does **not** inherit host `process.env`. Use
+  `agents.defaults.sandbox.docker.env` (or a custom image) for skill API keys.
+
+## 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.
+
+`tools.elevated` is an explicit escape hatch that runs `exec` on the host.
+`/exec` directives only apply for authorized senders and persist per session; to hard-disable
+`exec`, use tool policy deny (see [Sandbox vs Tool Policy vs Elevated](/gateway/sandbox-vs-tool-policy-vs-elevated)).
+
+Debugging:
+
+- Use `quantumclaw sandbox explain` to inspect effective sandbox mode, tool policy, and fix-it config keys.
+- See [Sandbox vs Tool Policy vs Elevated](/gateway/sandbox-vs-tool-policy-vs-elevated) for the “why is this blocked?” mental model.
+  Keep it locked down.
+
+## Multi-agent overrides
+
+Each agent can override sandbox + tools:
+`agents.list[].sandbox` and `agents.list[].tools` (plus `agents.list[].tools.sandbox.tools` for sandbox tool policy).
+See [Multi-Agent Sandbox & Tools](/tools/multi-agent-sandbox-tools) for precedence.
+
+## Minimal enable example
+
+```json5
+{
+  agents: {
+    defaults: {
+      sandbox: {
+        mode: "non-main",
+        scope: "session",
+        workspaceAccess: "none",
+      },
+    },
+  },
+}
+```
+
+## Related docs
+
+- [OpenShell](/gateway/openshell) -- managed sandbox backend setup, workspace modes, and config reference
+- [Sandbox Configuration](/gateway/configuration-reference#agents-defaults-sandbox)
+- [Sandbox vs Tool Policy vs Elevated](/gateway/sandbox-vs-tool-policy-vs-elevated) -- debugging "why is this blocked?"
+- [Multi-Agent Sandbox & Tools](/tools/multi-agent-sandbox-tools) -- per-agent overrides and precedence
+- [Security](/gateway/security)