Documentation menu
On this page

ADR 0005 — Worker runs inside a macOS Seatbelt sandbox (Q1-A, v2)

Date: 2026-06-11 · Status: accepted

Launch update

The original decision was macOS-first. The current launch build also supports Linux through the bubblewrap backend described in docs/sandboxing.md: deny-all network is enforced with a network namespace, writable paths are explicit binds, and concrete per-domain allowlists fail closed on Linux until an enforceable proxy namespace path exists.

Context

v1 gated the worker by policy: the worker enforced its own workspace boundary and the supervisor handed it a strict env allowlist (G2), but nothing physically stopped a worker from writing outside its worktree or opening a network socket. The decision record (Q1) committed to making this a real boundary at v2 with macOS Seatbelt, and to a hard honesty rule: the docs may only say "physically can't" once the mechanism actually enforces it.

Decision

The supervisor launches the worker under sandbox-exec with a per-task SBPL profile generated by skep/supervisor/sandbox.py. The profile is built around a network allowlist (decision D1) even though v1/v2 only ever pass deny-all: NetworkPolicy carries a domain list, () ≡ deny-all, and the policy derives from the task's permissions.network.

The profile (last-matching-rule-wins SBPL):

(version 1)
(allow default)            ; reads/exec/IPC stay working — the toolchain runs
(deny network*)            ; deny-all outbound (permissions.network = False)
(deny file-write*)         ; then confine writes…
(allow file-write* (subpath "<workspace>") (subpath "<results>") (subpath "<temp>"…))
(allow file-write* (literal "/dev/null") …)

The generated profile is written next to the worker log under audit/<task_id>/sandbox.profile.sb — the exact boundary that was enforced is part of the evidence chain.

What is physically enforced — and what is not (stated honestly)

  • Enforced: no outbound network; no file writes outside the workspace, the supervisor's result-file dir, and the OS temp roots. Proven by escape tests that run sandbox-exec for real (write-outside and an outbound socket both return EPERM) and by the full smoke + 10/10 reliability suite running the real worker under the sandbox with zero toolchain breakage.
  • Not enforced (deliberately, v2): read confinement. The profile uses allow default for reads so Python/git/pytest keep working; tightening reads is out of scope. Env-secret exposure — the high-value read target — is already closed by the G2 env allowlist, so the residual risk is a worker reading on-disk files it was not handed. Recorded as a gap, not hidden.
  • Not possible in pure Seatbelt: per-domain network allowlists. Seatbelt filters by IP/port, not DNS name. A concrete-domain NetworkPolicy raises SandboxAllowlistUnsupported rather than silently failing to enforce; the two shapes v2 uses (deny-all, allow-all) are both exact. Per-domain enforcement lands with the v3 proxy/container layer (Q1-B), which is also where the D1 network field stops being effectively deny-all.

Consequences

  • The claim follows the mechanism: docs now say the write/network boundary is physically enforced, scoped exactly as above — never broader.
  • macOS-first (G3): off macOS, sandbox.available() is False and the launch is unsandboxed. CI runs on macos-latest, so the gate exercises the real profile; a non-macOS run is the only place the physical claim does not hold, and it is explicit, not silent.
  • Re-verification (ADR 0006) reuses the same profile, so the supervisor's own patch-re-run is sandboxed too.