feat: replace Docker with Apple Container (macOS 26+ only)

[h1d3mun3]

Overview

Replace the Docker-based sandbox layer in augur with Apple's official container runtime apple/container. Target: macOS 26 (Tahoe) and later only — macOS 15 support is explicitly out of scope (see rationale below). The Docker mode can remain for Linux users as a separate path.

Background Research

The following is based on a deep research pass conducted in June 2026 (97 agents, 15 primary sources, 25 adversarially verified claims).

Apple Container Architecture

• Runs a separate lightweight Linux VM per container (Apple Virtualization.framework + vmnet) — not kernel namespaces
• Network isolation strength is equivalent to Docker's, despite the different model
• Runs OCI images (Linux containers) natively → existing Dockerfile can be reused as-is
• macOS-only (no Linux host support)

Why Drop macOS 15

The vmnet framework on macOS 15 cannot support container-to-container communication at all. container network create, --network, and --internal are macOS 26-only features (landed in PR #243). The Apple project explicitly states it has "no plan to address issues found with macOS 15 that cannot be reproduced on macOS 26."

What Works (High Confidence)

Docker feature	Apple Container equivalent	Source
docker network create --internal	container network create --internal	command-reference.md; confirmed by automated tests
docker run --network foo	container run --network foo	Same
--cap-drop NET_ADMIN	--cap-drop NET_ADMIN	Added in v0.12.0 (2026-04-27)
-v bind mounts, -e env vars	Same syntax	—
Sidecar proxy topology	Works	Apple contributor jglogan explicitly described and endorsed the pattern in discussion #1170; jamesmacaulay confirmed it with Squid

Gaps That Need Addressing

1. No container network connect (impact: high)

There is no command to attach a running container to a network after start. The current start_sidecar (augur:730) does:

docker run -d --name "$name" --network "$(egress_network_name)" ...
docker network connect bridge "$name"   # ← not available

Fix: Specify both networks at container startup:

container run -d --name "$name" \
    --network "$(egress_network_name)" \
    --network default \
    ...

Also need to confirm whether --subnet/--ip are supported. If not, the startup sequence must change: start sidecar → container inspect to get its IP → start agent container with that IP as HTTPS_PROXY. Small change (~5 lines).

2. No --dns flag (impact: low — effectively a non-issue)

There is no equivalent to --dns 192.0.2.1 --dns-search . (augur:928). However, DNS resolution is reportedly broken inside --internal networks by default (discussion #1170), which means external DNS already fails closed. The DNS self-test in verify_egress_locked (augur:752) should pass as-is. Fix: just delete the two --dns lines.

3. Host gateway reachable from --internal networks (impact: medium — security)

The host gateway IP (e.g. 192.168.128.1) remains reachable from --internal networks, creating a bypass path to any host service bound to 0.0.0.0. Confirmed by multiple community members (discussion #719).

Fix: Add a pf rule on the host:

block in quick from <container-subnet> to <host-gw>

Note: block out direction does not work for vmnet-bridged traffic — only block in is effective (confirmed by tomchuk and gcotone in the same thread). A container system pf subcommand draft exists (issue #1320) but is not yet merged.

This is the only change that requires sudo — the current Docker mode runs entirely without root.

What Does Not Need to Change

• Dockerfile: already a Linux container, reusable as-is
• ensure_linux_proxy: container run --rm -v ... swift build works the same way
• augur-proxy binary itself: no changes needed
• verify_egress_locked logic: swap docker exec → container exec; all three probes (proxy reachable, direct connection fails, DNS fails) should still pass

Implementation Plan

Scope

• In scope: macOS 26 (Tahoe) and later
• Out of scope: macOS 15, Linux hosts (keep Docker mode, or handle in a separate issue)
• augur --macos (augur-vm) continues to coexist as a separate mode

Tasks

1. Mechanical CLI rename (~40 occurrences)

   Docker	Apple Container
   docker build	container build
   docker run	container run
   docker exec	container exec
   docker ps	container list
   docker rm -f	container delete
   docker network rm	container network delete
   docker image inspect	container image inspect
   docker info	container system info (needs verification)

2. Refactor start_sidecar (~5–20 lines)

   • Remove docker network connect
   • Add --network default to container run at startup
   • If --subnet/--ip unsupported: inspect sidecar after start to get IP, then start agent

3. Remove --dns flags (2 lines)

4. Add pf rule management (~20 lines)

   • Add rule on augur up
   • Remove rule on augur down
   • Design the sudo UX (warn the user upfront)

5. Rename require_docker → require_container

6. Update tests

   • tests/10_construct_docker.sh: swap Docker shim for container shim
   • tests/20_docker_live.sh: update for live container CLI

Open Questions (Verify Before Starting)

• Does container network create support --subnet? Does container run support --ip?
• What is the exact equivalent of docker info (daemon health check)?
• How to handle the sudo requirement for pf rules — UX design?
• Monitor apple/container issue #1320 (container system pf) — if merged, sudo may no longer be needed

References

• apple/container repository
• technical-overview.md
• command-reference.md
• discussion #1170: network isolation on macOS 26 — Apple contributor describes the sidecar pattern
• discussion #719: egress filtering implementation report — pf rule direction findings
• PR #243: Adds container network for macOS 26

[h1d3mun3]

Update — implementation done on feat/apple-container-backend (with a corrected egress design)

Implemented the migration. During implementation, a primary-source + adversarial verification pass on the Apple container v1.0.0 CLI refuted the core assumption this issue was written on, so the egress architecture changed. Recording the correction here for posterity.

❌ What was wrong above: the dual-homed sidecar is impossible

Verified against apple/container docs + Flags.swift at tag 1.0.0:

• No --ip on run/create → can't pin a sidecar IP.
• Multiple --network is not supported (singular <network>, no repeat) → can't dual-home at create time.
• No container network connect → can't attach a second network post-start.

→ A container on Apple Container gets exactly one network. The Docker sidecar pattern (proxy on internal + bridge) cannot be reproduced. The "Gap 1 / network connect" section above is therefore moot.

✅ The replacement is actually a better fit

Verification surfaced a key semantic difference: Docker's --internal = no host, no internet; Apple's --internal = "host-only" = host reachable, internet blocked. That's exactly what a host-side proxy needs — and augur already ships one (the macOS-VM-mode augur-proxy).

Implemented egress (no sudo): agent on the --internal host-only network (--cap-drop NET_ADMIN, --no-dns) → HTTP_PROXY points at the host-only gateway → the host-side augur-proxy enforces the allowlist. A boot self-test fails closed.

Accepted trade-off: host-only also lets the agent reach other host services bound to 0.0.0.0 — weaker than Docker's airtight sidecar. Closing it would need host pf rules (sudo), which augur deliberately rejects. Documented, not enforced.

What landed

• Engine abstraction: AUGUR_ENGINE auto-selects Apple container on macOS 26+ (else Docker). Wrappers absorb the CLI deltas (ps→list, rm -f→delete --force, network rm→network delete, docker info→container system status, --no-dns). run/exec/build/network create --internal --subnet are identical argv on both engines.
• Docker path is byte-identical (Linux users unaffected; existing offline tests still green).
• Tests: a container shim + 11_construct_container.sh, 12_engine_select.sh, 21_container_live.sh (auto-skips off macOS 26). Full suite green on Linux.
• Adversarial review (4 dimensions) run; 7 findings fixed (proxy-probe set -e abort, pipefail-safety, stronger IP-literal egress probes, invalid-engine guard, etc.).

⚠️ Must be validated on macOS 26 hardware (couldn't be tested on Linux/CI)

• Host-only gateway IP is reachable & is the first-usable address (else set AUGUR_CONTAINER_GATEWAY).
• --no-dns leaves no usable resolver (so DNS-exfil stays closed).
• --internal truly severs internet routing for IP literals (self-test now probes 1.1.1.1/8.8.8.8 on :80/:443).
• container inspect exits non-zero for a missing container (used for running/exists checks).
• container build honors .dockerignore; container system start is sudo-free.

Tasks #4–#6 / "mechanical rename" in the original plan were superseded by the engine-abstraction approach (keeps Docker for Linux, per the Overview).

[h1d3mun3]

Done — closing as completed.

The Apple Container backend landed in #53 (merged 2026-06-30), realizing this issue's goal: on macOS 26+ the sandbox runs on apple/container — a per-container lightweight Linux VM, with a container network create --internal host-only network for egress, reusing the existing Dockerfile as-is. macOS 15 stays out of scope (the --internal / --network features are macOS 26-only).

Scope note: this issue planned to keep Docker for Linux as a separate path, but that decision was later superseded — #82 (merged 2026-07-08) dropped Docker entirely, so Apple Container is now the sole container engine (eng() { container "\$@"; } in augur). There is no remaining Docker code path.