Apus has three related but different controls:

1. Sandbox (agents.defaults.sandbox.*, agents.entries.*.sandbox.*, or a required creator-role policy) decides where tools run (sandbox backend vs host).
2. Tool policy (tools.*, tools.sandbox.tools.*, agents.entries.*.tools.*) decides which tools are available/allowed.
3. Elevated (tools.elevated.*, agents.entries.*.tools.elevated.*) is an exec-only escape hatch from ordinary sandboxing (gateway by default, or node when the exec target is configured to node). It cannot bypass a creator role's required sandbox.

Quick debug

Use the inspector to see what Apus is actually doing:

apus sandbox explain
apus sandbox explain --session agent:main:main
apus sandbox explain --agent work
apus 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": sessions run on the host unless their creator's operator role requires sandboxing.
• "non-main": only non-main sessions are sandboxed (common "surprise" for groups/channels).
• "all": everything is sandboxed.

agents.defaults.sandbox.workspaceAccess controls what the sandbox can see: "none", "ro", or "rw".

An operator role with sandbox: "required" overrides agent mode, cannot be escaped through elevated execution or host overrides, and fails closed when its sandbox cannot be provisioned. See Named operator roles.

See 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).
• Apus validates bind sources twice: first on the normalized source path, then again after resolving through the deepest existing ancestor. Symlink-parent escapes do not bypass blocked-path or allowed-root checks.
• Non-existent leaf paths are still checked safely. If /workspace/alias-out/new-file resolves through a symlinked parent to a blocked path or outside the configured allowed roots, the bind is rejected.
• Binding /var/run/docker.sock effectively hands host control to the sandbox; only do this intentionally.
• Workspace access (workspaceAccess) is independent of bind modes.

For a per-agent configuration with several host folders, access modes, and the external-source safety opt-in, see Multiple folders for one agent.

Tool policy: which tools exist/are callable

Five layers matter:

• Tool profile: tools.profile and agents.entries.*.tools.profile (base allowlist)
• Provider tool profile: tools.byProvider[provider].profile and agents.entries.*.tools.byProvider[provider].profile
• Global/per-agent tool policy: tools.allow/tools.deny and agents.entries.*.tools.allow/agents.entries.*.tools.deny
• Provider tool policy: tools.byProvider[provider].allow/deny and agents.entries.*.tools.byProvider[provider].allow/deny
• Sandbox tool policy (only applies when sandboxed): tools.sandbox.tools.allow/tools.sandbox.tools.deny and agents.entries.*.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.
• Tool policy filters tool availability by name; it does not inspect side effects inside exec. If exec is allowed, denying write, edit, or apply_patch does not make shell commands read-only.
• /exec only changes session defaults for authorized senders; it does not grant tool access.
• Provider tool keys accept either provider (e.g. anthropic) or provider/model (e.g. openai/gpt-5.4).
• Gateway logs include agents/tool-policy audit entries when a tool policy step removes tools or a sandbox tool policy blocks a call. Use apus logs to see the rule label, config key, and affected tool names.

Tool groups (shorthands)

Tool policies (global, agent, sandbox) support group:* entries that expand to multiple tools:

{
  tools: {
    sandbox: {
      tools: {
        allow: ["group:runtime", "group:fs", "group:sessions", "group:memory"],
      },
    },
  },
}

Available groups:

• group:runtime: exec, process, code_execution (bash is accepted as an alias for exec)
• group:fs: read, write, edit, apply_patch
• group:sessions: sessions, sessions_list, sessions_history, sessions_search, conversations_list, conversations_send, conversations_turn, sessions_send, sessions_spawn, sessions_yield, subagents, session_status, suggest_task, dismiss_task
• group:memory: memory_search, memory_get
• group:web: web_search, x_search, web_fetch
• group:ui: browser, screen, terminal, canvas, progress_card, show_widget
• group:automation: heartbeat_respond, cron, gateway
• group:messaging: message
• group:nodes: nodes, computer
• group:agents: agents_list, get_goal, create_goal, update_goal, progress_card, ask_user, skill_workshop
• group:media: view_image, image_generate, music_generate, video_generate, tts, pdf
• group:apus: most built-in Apus tools (excludes the read/write/edit/apply_patch/exec/process fs and runtime primitives, canvas, and provider plugins)
• group:plugins: all loaded plugin-owned tools, including configured MCP servers exposed through bundle-mcp

For read-only agents, deny group:runtime as well as mutating filesystem tools unless sandbox filesystem policy or a separate host boundary enforces the read-only constraint.

For sandboxed MCP servers, the sandbox tool policy is a second allow gate. If mcp.servers is configured but sandboxed turns only show built-in tools, add bundle-mcp, group:plugins, or a server-prefixed MCP tool name/glob such as outlook__send_mail or outlook__* to tools.sandbox.tools.alsoAllow, then restart/reload the gateway and recapture the tool list. Server globs use the provider-safe MCP server prefix: non-[A-Za-z0-9_-] characters become -, names that do not start with a letter get an mcp- prefix, and long or duplicate prefixes may be truncated or suffixed.

apus doctor currently checks this shape for Apus-managed servers in mcp.servers. MCP servers loaded from bundled plugin manifests or Claude .mcp.json use the same sandbox gate, but this diagnostic does not enumerate those sources yet; use the same allowlist entries if their tools disappear in sandboxed turns.

Elevated: exec-only "run on host"

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

• If you are ordinarily sandboxed, /elevated on (or exec with elevated: true) runs outside the sandbox (approvals may still apply). Creator-role-required sandboxes reject elevated execution.
• Use /elevated full to skip exec approvals for the session.
• If you are already running direct, elevated is effectively a no-op (still gated).
• Elevated is not skill-scoped and does not override tool allow/deny.
• Elevated does not grant arbitrary cross-host overrides from host=auto; it follows the normal exec target rules and only preserves node when the configured/session target is already node.
• /exec is separate from elevated. It only adjusts per-session exec defaults for authorized senders.

Gates:

• Enablement: tools.elevated.enabled (and optionally agents.entries.*.tools.elevated.enabled)
• Sender allowlists: tools.elevated.allowFrom.<provider> (and optionally agents.entries.*.tools.elevated.allowFrom.<provider>)

See Elevated Mode.

Common "sandbox jail" fixes

"Tool X blocked by sandbox tool policy"

Fix-it keys (pick one):

• Disable ordinary sandboxing: agents.defaults.sandbox.mode=off (or per-agent agents.entries.*.sandbox.mode=off); this does not override a creator role's required sandbox.
• Allow the tool inside sandbox:
  • remove it from tools.sandbox.tools.deny (or per-agent agents.entries.*.tools.sandbox.tools.deny)
  • or add it to tools.sandbox.tools.allow (or per-agent allow)
• Check apus logs for the agents/tool-policy entry. It records the sandbox mode and whether the allow or deny rule blocked the tool.

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

Related

• Session permission modes -- session roots and escalation reviewers
• Sandboxing -- full sandbox reference (modes, scopes, backends, images)
• Multi-Agent Sandbox & Tools -- per-agent overrides and precedence
• Elevated Mode
• OpenShell — a managed sandbox backend that runs the sandbox layer over SSH