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

title, summary, read_when, status

title	summary	read_when	status
Sandbox vs Tool Policy vs Elevated	Why a tool is blocked: sandbox runtime, tool allow/deny policy, and elevated bash gates	You hit 'sandbox jail' or see a tool/elevated refusal and want the exact config key to change.	active

Sandbox vs Tool Policy vs Elevated

Clawdbot 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 a bash-only escape hatch to run on the host when you’re sandboxed.

Quick debug

Use the inspector to see what Clawdbot is actually doing:

clawdbot sandbox explain
clawdbot sandbox explain --session agent:main:main
clawdbot sandbox explain --agent work
clawdbot 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 for the full matrix (scope, workspace mounts, images).

Tool policy: which tools exist/are callable

Two layers matter:

• Global/per-agent tool policy: tools.allow/tools.deny and agents.list[].tools.allow/agents.list[].tools.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.

Elevated: bash-only “run on host”

Elevated does not grant extra tools; it only affects bash.

• If you’re sandboxed, /elevated on (or bash with elevated: true) runs on the host.
• If you’re already running direct, elevated is effectively a no-op (still gated).

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.

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".