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-execfor 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 defaultfor 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
NetworkPolicyraisesSandboxAllowlistUnsupportedrather 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 onmacos-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.