The default local backend: its restricted defaults, GPU and Docker-out-of-Docker constraints, and the sandboxed browser container.

Docker backend

The Docker backend runs tools locally through the docker CLI. Its selection and error behavior are unchanged; it does not check or fall back to Podman.

Defaults: network: "none" (no egress), readOnlyRoot: true, capDrop: ["ALL"], image apus-sandbox:bookworm-slim.

This explicit configuration keeps the agent workspace read-only and preserves the default restricted runtime posture:

{
  agents: {
    defaults: {
      sandbox: {
        mode: "all",
        backend: "docker",
        scope: "session",
        workspaceAccess: "ro",
        docker: {
          image: "apus-sandbox:bookworm-slim",
          readOnlyRoot: true,
          tmpfs: ["/tmp", "/var/tmp", "/run"],
          network: "none",
          capDrop: ["ALL"],
        },
      },
    },
  },
}

Apus also creates Docker sandbox containers with an init process and no-new-privileges. With workspaceAccess: "ro", the agent workspace is mounted read-only at /agent; write operations to the agent workspace are rejected, while the configured tmpfs paths remain writable.

File tools require a host-backed bind mount. A tmpfs or image volume can hide files below a workspace bind; file tools report those paths as container-only instead of reading the hidden host files. Use exec to access that storage. A deeper explicit bind restores file-tool access when it is visible in the container. Mount destinations reached through symlinks, or stacked mounts with different backing storage, also require exec when their host projection cannot be established from the container's mount table.

For recently used containers, changes to bind sources or access modes, or to tmpfs destinations or read-only modes below a bind, require scoped recreation. Other tmpfs options, such as size, mode, and uid, keep the normal configuration change behavior: a hot container stays running with a recreation notice, while a stopped or expired container is replaced. Recreate explicitly to apply those options immediately.

To expose host GPUs, set agents.defaults.sandbox.docker.gpus (or the per-agent override) to a value like "all" or "device=GPU-uuid". This is passed to the selected container engine's Docker-compatible --gpus flag and requires compatible host GPU setup. Podman requires version 5.0 or newer for this option.

Docker-out-of-Docker (DooD) constraints

If the Gateway runs in Docker, it creates sibling sandbox containers through the host's Docker socket. Keep workspace paths in apus.json relative to the Gateway filesystem, such as /home/node/.apus/workspace. Apus translates managed workspace, agent-workspace, and skill mounts into the Docker host's paths automatically. Shell and browser containers use the same mapping rules. Nested Gateway binds are projected too, with their read-only permissions preserved.

  • Bind-mount the workspace and Apus state directories into the Gateway. Their host and Gateway paths can differ.

  • Use the Docker daemon that runs the Gateway. Apus verifies its container identity before trusting the daemon's mount table.

  • Managed sources and their visible nested mounts must come from bind mounts. Named volumes, tmpfs, and files in the Gateway image are unsupported sources for sibling sandbox mounts.

  • A writable sandbox requires a writable Gateway bind. Use workspaceAccess: "ro" for read-only Gateway sources.

  • Explicit sandbox.docker.binds and sandbox.browser.binds retain their host-path contract. Apus does not translate these operator-supplied sources.

  • Restart the Gateway after changing its mounts or Docker connection. If an existing sandbox has different mounts, Apus reports a scoped sandbox recreate command. Recently used containers remain running until you recreate them, but Apus refuses to reuse their stale mounts.

  • Codex code mode: when an Apus sandbox is active, Apus disables Codex app-server native Code Mode, user MCP servers, and app-backed plugin execution for that turn (those run from the Gateway-host app-server process, not the Apus sandbox backend), unless the sandbox tool policy exposes the required tools and you opt into the experimental sandbox exec-server path. Shell access then routes through Apus sandbox-backed tools such as sandbox_exec and sandbox_process. Do not mount the host Docker socket into agent sandbox containers or custom Codex sandboxes. See Codex Harness for the full behavior.

On Ubuntu/AppArmor hosts with Docker sandbox mode enabled, Codex app-server workspace-write shell execution needs unprivileged user namespaces inside the sandbox container, and this can fail before shell startup when the service user cannot create them. This needs an unprivileged network namespace too when Docker sandbox egress is disabled (network: "none", the default). Common symptoms: bwrap: setting up uid map: Permission denied and bwrap: loopback: Failed RTM_NEWADDR: Operation not permitted.

These Codex bwrap checks run in standalone apus doctor and are omitted during apus update; run apus doctor after the update. Doctor checks the user namespace with unshare. When Docker sandbox egress is disabled and a local Codex runtime is configured, it also runs the configured Codex binary's own workspace-write sandbox with network access disabled, exercising Bubblewrap's loopback setup. Unrecognized check failures are reported as unverified rather than as a namespace diagnosis. If doctor reports a Codex bwrap namespace check failure, prefer an AppArmor profile that grants the required namespaces to the Apus service process. kernel.apparmor_restrict_unprivileged_userns=0 is a host-wide fallback with security tradeoffs; use it only when that host posture is acceptable. Do not grant broader Docker container privileges just to satisfy nested bwrap.

Sandboxed browser