Apus can run tool execution inside a sandbox backend to reduce blast radius. Sandboxing is off by default and controlled by agents.defaults.sandbox (global), agents.entries.*.sandbox (per-agent), or a required creator-role sandbox policy. The Gateway process always stays on the host; only tool execution moves into the sandbox when enabled.

This is not a perfect security boundary, but it materially limits filesystem and process access when the model does something dumb.

Sandboxing pages

This page is an index. The sandbox reference is documented on twelve pages. Open the page that matches what you are configuring.

Page Read it when
What gets sandboxed You want to know exactly which execution moves into the sandbox.
Modes, scope, and backend You are deciding which sessions run sandboxed and how they share environments.
Supported capability matrix You are comparing Docker, SSH, and OpenShell before choosing a backend.
Docker backend You are running the default local backend or enabling the sandboxed browser.
Podman backend You are using Podman instead of Docker for sandboxed tool execution.
SSH backend You are offloading sandboxed tool execution to a remote machine over SSH.
OpenShell backend You are sandboxing tools in an OpenShell-managed remote environment.
Crabbox backend You want tool execution on a Crabbox-leased cloud box while the agent stays local.
Workspace access You are deciding what the sandbox can see of the agent workspace.
Multiple folders for one agent One sandboxed agent needs more than its primary workspace.
Images and setup You need to build or customize a sandbox image.
setupCommand (one-time container setup) You need to run one-time setup inside a newly created sandbox container.

Where each section moved

Every anchor this page used to publish is kept here, so an existing link such as /gateway/sandboxing#images-and-setup still resolves. Each entry points at the page that now holds the content.

Tool policy and 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 outside the sandbox (gateway by default, or node when the exec target is node). /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).

Debugging:

Multi-agent overrides

Each agent can override sandbox + tools: agents.entries.*.sandbox and agents.entries.*.tools (plus agents.entries.*.tools.sandbox.tools for sandbox tool policy). See Multi-Agent Sandbox & Tools for precedence.

Managed GitHub identity

Sandboxed execution excludes the agent's managed GitHub identity by default. Set agents.entries.<id>.tools.github.allowInSandbox: true on that agent's managed identity to allow it inside the agent's own Docker or Podman sandbox. Apus mounts the selected profile read-only at /apus/github, sets GH_CONFIG_DIR to that path, and provides the same managed token and Git author as host execution. The container needs gh installed for GitHub CLI commands.

This opt-in exposes credentials to code running in the sandbox; read-only mounting prevents profile edits, not credential reads. apus security audit emits a warning for every opted-in agent. Effective scope: "shared" refuses identity injection and logs a warning naming the agent, because that container can serve other agents. Role-required sandboxes retain their per-creator isolation and support the opt-in. Other sandbox backends reject provisioning with the opt-in enabled. See GitHub identity.

Minimal enable example

{
  agents: {
    defaults: {
      sandbox: {
        mode: "non-main",
        scope: "session",
        workspaceAccess: "none",
      },
    },
  },
}

Related