docs: add research note on Apple container as an alternative backend

Captures the surface area of the current Docker integration, how it maps to Apple's `container` framework, the dominant networking risk (pipelock multi-network attach), and the cost difference between a faithful port and a simplified VM-firewall variant. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
2026-05-10 02:36:11 -04:00
parent 1e6f254db5
commit e1efc64862
1 changed files with 130 additions and 0 deletions
@@ -0,0 +1,130 @@
+# Supporting Apple's `container` as an alternative backend
+
+Research into the cost and shape of adding Apple's `container` framework
+(per-container Linux microVMs on Apple Silicon, announced WWDC 2025) as
+an alternative backend alongside Docker. Motivated by the observation
+that Apple's tool gives VM-grade isolation "for free" on macOS — no
+Firecracker or Kata orchestration to deploy — and that the project's
+threat model already cares about the kernel boundary.
+
+## Summary
+
+Realistic effort: roughly two weeks of focused work for one person. The
+mechanical 80% (build / run / exec / cp) is a long-but-straightforward
+weekend. The remaining 20% is networking: the pipelock egress sidecar
+relies on Linux bridge-network multi-attach semantics that Apple's tool
+does not model the same way, and either has to be redesigned or
+simplified for the `container` path.
+
+The honest framing: a clean port of the easy parts plus a *different*
+networking story for the `container` backend (no sidecar, just VM-level
+firewall rules), end-to-end in 4–5 days. A faithful port that preserves
+pipelock semantics across both backends is closer to two weeks. Pick
+which version you want before starting.
+
+## Current Docker surface area
+
+The places claude-bottle shells out to `docker` today:
+
+- `build` — base image plus a per-cwd derived image
+  (`claude_bottle/docker.py:67-103`).
+- `run` — with `--runtime`, `--env-file`, `-e`, `--name`, `--network`,
+  and volume mounts (`claude_bottle/cli/start.py:217-261`).
+- `exec -it` / `exec -u 0` — for `claude` itself, file-ownership fixups,
+  and SSH provisioning (`claude_bottle/ssh.py`, `claude_bottle/skills.py`,
+  `claude_bottle/cli/start.py`).
+- `cp` — skills, SSH keys, the prompt file, the workspace `.git`,
+  and the pipelock config
+  (`claude_bottle/skills.py:73`, `claude_bottle/ssh.py:106`,
+  `claude_bottle/cli/start.py:279`, `claude_bottle/pipelock.py:218`).
+- `network create` / `connect` / `inspect` / `rm` — bottle network plus
+  multi-network attach for the pipelock sidecar
+  (`claude_bottle/network.py`, `claude_bottle/pipelock.py:227`).
+- `create` / `start` / `rm -f` — pipelock sidecar lifecycle
+  (`claude_bottle/pipelock.py:207-258`).
+- Misc preflight: `image inspect`, `ps -a -f name=^...$`, `info` for
+  registered runtimes (`claude_bottle/docker.py`).
+
+## Mapping to Apple's `container`
+
+| Capability | `container` story |
+|---|---|
+| build / run / exec / images | Direct equivalents, OCI-compatible |
+| `cp` | `container cp` exists, but recursion semantics (trailing `./`) need verifying against the Docker behavior the codebase relies on |
+| `--env-file` | Needs verification; may have to translate to repeated `-e` flags |
+| `--runtime=runsc` | **Becomes a no-op.** Every container is already in its own VM, so gVisor is redundant. This is a win — `require_runsc` collapses or the manifest unifies the concept (see "Manifest" below). |
+| User-defined networks | Limited — fewer knobs than Docker bridge networks |
+| **Multi-attach: `network connect` to a running container** | **The hard one.** The pipelock sidecar pattern attaches to two networks. Apple's tool does not model that the same way. |
+
+## Effort breakdown
+
+Roughly two weeks for one person, split as:
+
+1. **Backend abstraction (1–2 days).** `claude_bottle/docker.py` is
+   already a partial seam, but `claude_bottle/network.py`,
+   `claude_bottle/pipelock.py`, `claude_bottle/ssh.py`,
+   `claude_bottle/skills.py`, and `claude_bottle/cli/start.py` all call
+   `subprocess.run(["docker", ...])` directly. Define a `Backend`
+   protocol — `run`, `exec`, `cp`, `build`, `network_create`,
+   `network_connect`, `inspect`, `rm` — route every call through it,
+   keep Docker as the default impl. Mostly mechanical.
+
+2. **`container` backend impl (2–3 days).** The easy 80%: run, exec,
+   build, image inspect, cp. Plus a `require_container()` analogous to
+   `require_docker()`. Verify `container cp` recursion and `--env-file`
+   support against actual binary behavior, not docs.
+
+3. **Networking and pipelock (3–5 days, dominant risk).** The egress
+   sidecar design assumes Linux bridge-network semantics with multi-
+   network attach. On Apple's tool the likely redesign is one of:
+
+   - Run pipelock as a host-side process and have the bottle dial it
+     directly via the host loopback. Simpler, but loses the "egress
+     proxy is itself isolated" property.
+   - Keep pipelock in its own VM and wire the bottle's egress through
+     it via a different mechanism (port forwarding, shared network if
+     the tool grows that capability). Closer to current semantics, more
+     work.
+
+   Either way this is real design work, not a port. Worth a separate
+   PRD before code lands.
+
+4. **Manifest spec (½ day).** Collapse `runtime: "runsc"` and "use
+   `container` backend" into a single `sandbox: "shared-kernel" | "vm"`
+   field. Backend selection follows from the value. Documenting why the
+   `runsc` knob disappears on the `container` path matters more than
+   the code change.
+
+5. **Tests and docs (2–3 days).** The existing test suite mocks
+   `docker`; needs equivalents for `container`. Document which features
+   are macOS-only and what the `container` backend trades away
+   (currently: pipelock semantics, possibly some network introspection).
+
+## The recommended split
+
+Two distinct paths, each with a clear cost/benefit:
+
+- **Faithful port (~2 weeks).** Both backends offer the same egress
+  guarantees. Worth it if pipelock is load-bearing for the threat model
+  and the project intends to support `container` as a first-class peer
+  to Docker indefinitely.
+
+- **Simplified port (~4–5 days).** The `container` backend uses VM-level
+  firewall rules instead of pipelock; documentation calls out the
+  difference. Worth it if the VM kernel boundary is judged to make
+  pipelock less critical on the `container` path anyway, and the goal
+  is to get `container` working as an experimental backend without
+  blocking on a redesign.
+
+The simplified path is probably the right starting point. The kernel
+boundary that `container` provides was the original motivation for
+exploring this in the first place; pipelock's value-add on top of a
+real VM is smaller than it is on top of shared-kernel Docker.
+
+## Recommendation
+
+Don't start the implementation before deciding which split is intended,
+and don't start any of it before the `Backend` abstraction lands. The
+abstraction makes the language choice reversible (per the
+`bash-vs-python-vs-go` note) *and* makes adding a second backend
+mechanical. Skipping it means rewriting the same call sites twice.