docs: add research note on stronger isolation alternatives

Surveys gVisor, Kata, Firecracker, and Apple Container as replacements
or complements to Docker+runc, with concrete file-level migration notes
for this codebase and a recommended rung-by-rung path.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

docs/research/stronger-isolation-alternatives.md

@@ -0,0 +1,243 @@
+# Stronger isolation alternatives: gVisor, Kata, Firecracker, Apple Container
+
+Research into what it would take to replace or augment Docker (with `runc`)
+as the agent runtime in claude-bottle, and what each option would actually
+buy in security terms vs. cost in launcher rewrite.
+
+## Summary
+
+There is a ladder, not a menu. Three realistic rungs, ordered by effort:
+
+1. **gVisor (`runsc`)** — flip a runtime flag per bottle. ~1–2 days. Adds a
+   userspace syscall boundary; blocks most kernel-CVE escape classes.
+2. **Kata Containers** — flip a runtime flag per bottle. Same Docker UX,
+   real microVM underneath. Linux-host only.
+3. **Firecracker direct** — replace Docker as the runtime entirely. Weeks
+   of work. Strongest boundary, no macOS support.
+
+A fourth option, **Apple Container**, is the right macOS-native answer to
+"I want Kata's isolation model without giving up MacBooks as the dev
+target." Probably the right v2 if claude-bottle keeps macOS in scope.
+
+The pipelock egress design is portable across all four: every option can
+provide a network primitive that means "no default route except through
+the proxy" (Docker `--internal`, Kata's virtualized bridge, TAP-only
+Firecracker, Apple Container's per-VM networking). Whichever rung is
+chosen, the security-load-bearing part of the v1 design survives.
+
+## Threat model recap
+
+The current v1 boundary is a single `node:22-slim` container running as
+uid 1000 under `runc`, sharing a kernel with the host. This protects
+against:
+
+- accidental host-filesystem access by Claude Code,
+- network egress not approved by the pipelock allowlist,
+- a misbehaving but uncoordinated agent.
+
+It does not protect against:
+
+- a kernel-level container escape (Dirty Pipe / runc CVE class),
+- a coordinated attacker with code execution inside the container who
+  targets the host kernel,
+- side channels accessible from the shared kernel.
+
+Stronger isolation closes the second column. Whether that's worth the
+effort depends on whether you trust the agent's code-execution surface
+more or less than you trust the host kernel.
+
+## Rung 1: gVisor (`runsc`)
+
+gVisor is a userspace kernel that registers as a Docker runtime. The
+agent's syscalls are intercepted and re-implemented in Go rather than
+forwarded to the host kernel.
+
+### What changes in this codebase
+
+- `claude_bottle/cli/start.py` (where `docker run` is assembled): add
+  `--runtime=runsc` to the container args when the bottle requests it.
+  Make it configurable: `bottles.<name>.runtime: "runsc" | "runc"`,
+  default `runc`.
+- `claude_bottle/docker.py`: add a `require_runsc()` check that runs
+  `docker info --format '{{.Runtimes}}'` once and dies with an install
+  pointer if `runsc` isn't registered.
+- `network.py`, `pipelock.py`, `skills.py`, `ssh.py`: **no changes**.
+  Docker networks, `docker exec`, `docker cp`, volume mounts, the
+  pipelock sidecar — all of it still works because gVisor is invisible
+  at the Docker API layer.
+
+### What you get
+
+- A second syscall boundary between the agent and the host kernel.
+  Most container-escape CVEs (Dirty Pipe / runc-escape class) stop at
+  `runsc`.
+- Roughly 2–10% perf hit on syscall-heavy workloads. `npm install` will
+  feel it; interactive `claude` typing will not.
+
+### Caveats
+
+- **macOS does not run `runsc` natively.** It needs a Linux kernel. On
+  Mac, gVisor would run inside Docker Desktop's Linux VM, so the
+  effective boundary becomes "agent ↔ runsc ↔ Docker Desktop's Linux VM
+  ↔ hypervisor ↔ macOS". The hypervisor was already doing the heavy
+  lifting; on Mac, runsc is mostly defense-in-depth. On a Linux host
+  it's a real win.
+- Some syscalls are unsupported (a small list — `io_uring` historically,
+  some `ptrace` shapes). For Claude Code + git + npm I expect zero
+  issues, but a smoke test (`claude --version && git status && npm
+  install`) inside the runsc image is worth it.
+
+### Effort
+
+~1–2 days, plus a paragraph in the README. Cleanest first step.
+
+## Rung 2: Kata Containers
+
+Kata also registers as a Docker/containerd runtime
+(`--runtime=kata-runtime`), but each container actually runs inside its
+own lightweight VM. The VMM under the hood is configurable: Firecracker,
+Cloud Hypervisor, or QEMU.
+
+### What changes in this codebase
+
+Essentially the same as the gVisor path: flip a runtime flag, add a
+require-check. **Pipelock keeps working unchanged**, because Kata
+virtualizes the network at the VM level but exposes it as a normal
+Docker network.
+
+### Tradeoffs vs. gVisor
+
+- Stronger boundary (real VM, not a syscall filter).
+- Slower cold start (hundreds of ms vs. tens). For interactive Claude
+  this is fine; for ephemeral batch agents you would notice.
+- Not natively supported on macOS at all — needs a Linux host or a Linux
+  VM you control. **This is the moment claude-bottle stops being "works
+  on a Mac dev laptop with Docker Desktop."**
+
+### When this is the right rung
+
+If the deployment target is "agents run on a small Linux server I
+administer," Kata is the sweet spot. If the target stays "users run this
+on their MacBook," skip to the Apple Container option.
+
+## Rung 3: Firecracker directly
+
+Firecracker is a VMM, not a container runtime. Adopting it means
+replacing Docker, not adding to it.
+
+### What you would lose / have to rebuild
+
+| Today | With Firecracker |
+| --- | --- |
+| `Dockerfile` → `node:22-slim` image | A rootfs (ext4 image) + a kernel (vmlinux) you build and pin |
+| `docker run --network …` | TAP devices on the host, connected to a Linux bridge or routed manually |
+| `docker exec -it` for the interactive TTY | vsock + a small in-guest agent, or SSH into the microVM |
+| `docker cp` for skills + pipelock YAML | Bake into the rootfs, mount a virtio-blk overlay, or 9p / virtiofs share |
+| Pipelock as a sidecar on a `--internal` network | Pipelock as a separate microVM (or on the host) with a TAP-only path between the two; the agent VM gets no host route |
+| `docker rm -f` on exit | A SIGTERM to firecracker + cleanup of TAPs, sockets, overlay disks |
+
+### Files in this repo that would change
+
+- `claude_bottle/docker.py` → replaced by a new `claude_bottle/firecracker.py`
+  that POSTs to the Firecracker API socket per microVM (`/boot-source`,
+  `/drives`, `/network-interfaces`, `/actions`).
+- `claude_bottle/network.py` → a host-side networking module that creates
+  a Linux bridge per agent, two TAPs (agent-side, pipelock-side), and
+  either iptables rules or no host route at all so the agent VM
+  literally cannot reach anything except pipelock.
+- `claude_bottle/pipelock.py` → instead of a sidecar container, run
+  pipelock as its own microVM (or on the host pinned to the bridge).
+  The hostname-allowlist semantics carry over; the implementation is
+  different.
+- `claude_bottle/skills.py`, `ssh.py` → can no longer use `docker cp`.
+  Bake skills into the rootfs at build time, or mount a virtiofs share
+  read-only.
+- `Dockerfile` → replaced by a rootfs builder. Realistically this means
+  using something like `firecracker-containerd` or building the rootfs
+  with `debootstrap` / `mkosi` and a kernel from upstream.
+
+### What you would gain
+
+- A real KVM boundary. The strongest isolation realistically achievable
+  on commodity hardware.
+- Sub-second cold starts (Firecracker boots in ~125 ms; rootfs prep
+  dominates).
+
+### What you would give up
+
+- macOS support. Firecracker is KVM-only. The only way back to Mac is to
+  nest a Linux VM hosting Firecracker, at which point the security
+  argument gets thin again.
+- Ecosystem ergonomics. No `docker logs`, no `docker exec`, no `docker
+  network inspect`. You write all of that yourself or adopt
+  `firecracker-containerd` or Ignite (which is unmaintained — verify
+  before committing).
+
+### Effort
+
+Realistically 2–4 weeks of focused work on the runtime layer. Forces
+dropping "v1 works on Mac" as a goal. PRD-worthy, not a side quest.
+
+## Rung 3.5: Apple Container (macOS-native VM-per-container)
+
+Apple Container is Apple's `container` CLI, native on Apple Silicon.
+Each container runs in its own Virtualization.framework VM. It is the
+macOS-native answer to "I want Kata's isolation model on my MacBook."
+
+### Why it matters here
+
+The CLI surface mirrors Docker closely (`container run`, `container
+network create`, etc.), so the launcher rewrite is far smaller than
+Firecracker's. On Linux hosts you would still take the gVisor or Kata
+path. The result is:
+
+- macOS: Apple Container (per-container VM via Virtualization.framework),
+- Linux: gVisor or Kata,
+- one Python launcher that switches on host OS.
+
+### Open questions before committing
+
+- Does Apple Container support a `--internal`-equivalent network with
+  no default gateway, so the pipelock topology is reproducible?
+- Image format: Apple Container uses OCI images, so the existing
+  `Dockerfile` should be reusable, but this needs verification.
+- `exec`-equivalent semantics: the launcher relies on `docker exec` to
+  attach a TTY after the container is up. Confirm `container exec`
+  behaves equivalently for interactive use.
+
+A short spike (~1 day) answering those three questions would unblock a
+PRD-level decision.
+
+## Recommendation
+
+If this were my project today, given the README still names macOS as in
+scope and the manifest example carries `/Users/didericis` paths:
+
+1. **Today.** Add `bottles.<name>.runtime` with `runc` / `runsc` options.
+   Land it as a one-day PR. README gets a small "Linux hosts can opt
+   into gVisor for stronger isolation" note. Mac users get nothing new
+   but lose nothing.
+2. **If VM-grade isolation on macOS becomes the goal.** Skip Firecracker
+   and look at Apple Container. Smaller launcher rewrite than
+   Firecracker; Linux stays on the gVisor / Kata path. Probably the
+   right v2.
+3. **Firecracker only if** claude-bottle's deployment target settles on
+   self-hosted Linux, not laptops — at which point the "non-goal:
+   self-hosted VMs" line in `CLAUDE.md` flips and the project's
+   identity changes.
+
+The pipelock egress design ports across all of these, so none of this
+work threatens the existing security-load-bearing piece of v1.
+
+## Caveats
+
+- gVisor's unsupported-syscall list shifts release-to-release; verify
+  against the version pinned in any future image.
+- Kata's default VMM is configurable; performance and CVE surface vary
+  by VMM choice.
+- Firecracker tooling has churned (Ignite is effectively unmaintained;
+  `firecracker-containerd` is the active path). Re-survey before
+  committing.
+- Apple Container is young; behavior around `--internal`-style networks
+  and `exec` semantics needs to be verified directly, not assumed.
+- Research conducted 2026-05-10.