Support Eclipse Enclave as an optional container-level sandbox backend

[potiuk]

What

Support Eclipse Enclave as an optional container-level backend for Layer 1, alongside the existing bubblewrap (Linux) and Seatbelt (macOS) OS sandboxes.

bubblewrap and Seatbelt sandbox each Bash subprocess on the host. Enclave takes the container route instead: the whole agent session runs inside a container with its own filesystem, process tree, and network stack, so the host is never in scope to begin with. It is an Eclipse Foundation project (MIT-licensed), building a vendor-neutral runtime for executing agents in isolated, policy-controlled environments — with egress allowlisting, per-session audit trails, and git-worktree integration for parallel sessions. It treats agents as untrusted, replaceable workloads, which is the same premise as RFC-AI-0002.

Why it is worth having as an option

	Per-subprocess (bwrap / Seatbelt)	Container-level
Bypass blast radius	Straight onto the host — see residual risk 4 (X3, local sandbox override is unavoidable)	Still the container
Portability	Two profiles, visibly different failure modes (No such file or directory vs Operation not permitted)	One profile on both OSes
Agent's own Read / Edit / Write tools	Not covered — only permissions.deny stops them	Covered, they run inside the container

The bypass row is the interesting one. Residual risk 4 in our own threat model accepts that a maintainer editing .claude/settings.json locally cannot be prevented, and that the CI lint catches PR-shipped changes but not local overrides. A container backend does not fix the override, but it does bound what an overridden session can reach.

Trade-offs, stated plainly

• Requires a container runtime. Docker is the first supported backend; microVMs, rootless runtimes, and Kubernetes orchestration are named as future directions rather than shipping today.
• Coarser granularity. Per-subprocess sandboxing lets us allow one path to gh and deny it to everything else via sandbox.excludedCommands. A container is all-or-nothing at the session boundary, so layers 2 and 3 carry proportionally more weight.
• Incubating. The proposal is approved and the project created, but there is no released artefact.

What Magpie would require of any container backend

Worth agreeing this contract regardless of which backend eventually satisfies it:

1. Default-deny egress with an allowlist equivalent to sandbox.network.allowedDomains, enforced before a socket opens — not after a DNS lookup.
2. Credential exclusion — the Layer 0 guarantee must survive: no $GH_TOKEN, $AWS_*, $ANTHROPIC_API_KEY reaching the agent process, and no host credential paths mounted in.
3. Workspace scoping — the container sees the project tree (or a worktree of it) and nothing else of the host filesystem.
4. An auditable session record — what the session reached out to, retrievable afterwards. tools/egress-gateway/ provides this today; a container backend should subsume rather than duplicate it.
5. A documented escape hatch — the equivalent of sandbox.excludedCommands, so adopters do not disable the whole sandbox to unblock one command.

What is blocked, and on what

The docs half is written and pushed as a draft branch: feat/enclave-container-isolation — three files, prek green.

The executable half is deliberately not written, because Enclave is incubating and I could not find a published repository, CLI, or release. Specifically not done:

• No pinned-versions.toml entry. A pin needs a version and a released date to age through its cooldown. Neither exists, and inventing either would defeat the point of the manifest.
• No backend selector in agent-iso.sh, and no check in setup-isolated-setup-verify — both need an invocation surface that is not public yet.

Writing enclave run claude … into the setup document would have been fabricating an interface, so the branch states the contract instead.

Suggested next steps

1. Land the documentation as an option, so the contract above is written down and reviewable.
2. Track Enclave to a first release / published CLI.
3. Then wire it for real: backend selector, pin entry, verify check, and a setup-isolated-setup-doctor probe.

Anyone with a link to the Enclave repository or a working CLI — please drop it here; step 3 is small once the interface is known.

Related

• Threat model residual risks 4 and 9 (local sandbox override; skill-scope discipline is convention, not enforcement).
• tools/egress-gateway/ — the framework's current answer to auditable egress.