wirenboard-agent-vm/ARCHITECTURE.md

# agent-vm — ARCHITECTURE

How the rewrite is put together and *why*. Reading this top-to-bottom should
tell you what every nontrivial design choice in the codebase exists for.
Updated after each phase lands. Section per phase; subsection per major
decision.

## Phase 0 — Scaffolding

### Repository layout

```
microsandbox-rewrite/
├── PLAN.md                     # phased roadmap
├── ARCHITECTURE.md             # this file
├── Cargo.toml                  # workspace
├── crates/
│   └── agent-vm/
│       ├── Cargo.toml
│       └── src/main.rs         # hello-world sandbox boot
├── vendor/
│   └── microsandbox/           # git submodule, wirenboard/microsandbox
└── .gitmodules
```

### Why a Cargo workspace from day one

The binary is small today but we already know we'll need at least one
internal crate per concern (creds, image, session). A workspace lets us add
those without restructuring later, and keeps `vendor/microsandbox` out of
our crate's manifest noise.

### Why a git submodule for microsandbox (vs. crates.io, vs. path dep)

- **Phase 3 requires extending microsandbox.** The new `SecretValue::File`
  variant lives in `microsandbox-network`. A path dep against a sibling
  checkout works for one developer but not for CI or contributors. A submodule
  pinned to a branch on our fork (`wirenboard/microsandbox`) makes the
  checkout self-contained and the upstream diff reviewable.
- **`[patch]` against crates.io** also works, but it duplicates the source-of-
  truth pointer (Cargo.lock + patch table) and hides the fact that we are
  shipping a fork. Submodule is more explicit.

### Why depend on the path under `vendor/microsandbox` even before we fork

Phase 0 doesn't change microsandbox, but we point at the submodule path so
the build wiring we set up here is the same wiring Phase 3 uses. Avoids a
mid-rewrite refactor of `Cargo.toml`.

### Why `Sandbox::builder("hello").image("alpine")` for the smoke test

Smallest possible exercise of the SDK that proves we can talk to the runtime.
Alpine is in the microsandbox examples, downloads quickly, and exits cleanly.
No need to involve our own image (that's Phase 1).

### Phase 0 runtime validation

`cargo run -p agent-vm` was exercised end-to-end on a Linux KVM host:

- One-time setup required outside the source tree: `apt install libcap-ng-dev`
  (link-time dep pulled in transitively by `msb_krun`'s `capng` crate), and
  user membership in the `kvm` group so `/dev/kvm` is openable. Both are host
  prerequisites and don't belong in the repo.
- microsandbox's build script downloads its prebuilt runtime artifacts the
  first time `cargo check` runs against the workspace
  (`microsandbox@0.4.6: downloading microsandbox runtime dependencies`).
  Nothing in our crate has to opt into this; the `prebuilt` feature is on by
  default in `microsandbox-runtime`.
- Wall-clock for the full boot + `echo` + teardown with the alpine image
  already in cache: **2.7s** on a release build. Cold first run includes the
  OCI pull on top.

This is the latest point we can confirm we're talking to a real runtime before
adding our own scaffolding; pinning the validation here means a Phase 1 image
regression won't masquerade as an SDK-integration regression.

## Phase 1 — Base OCI image

### Layout

```
images/
├── Dockerfile        # Debian 13 slim + agents
└── build.sh          # ensures registry, docker build, docker push

crates/agent-vm/src/
├── main.rs           # clap entry; dispatches to subcommands
└── setup.rs          # `agent-vm setup`: invoke build.sh, then verify in microsandbox
```

### Image distribution: local Docker registry vs. alternatives

`RootfsSource` (microsandbox-side) supports three image origins:

1. `Oci(reference)` — pulled from a registry (Docker Hub, GHCR, local, etc.).
2. `Bind(path)` — host directory used as the rootfs directly.
3. `DiskImage(path)` — qcow2/raw/vmdk file.

We pick **(1) with a local `registry:2` container on 127.0.0.1:5000**, exposed
to the sandbox builder as `.image("localhost:5000/agent-vm:latest")
.registry(|r| r.insecure())`. Rationale:

- **Standard OCI semantics.** microsandbox's layer cache, GC, snapshotting,
  and metadata DB all key off OCI references. Going through the registry path
  means we get all of that for free instead of working around it.
- **Same wiring as a future remote registry.** When/if we publish images to
  GHCR, the launcher's `.image(...)` call doesn't change; only the tag does.
- **Bind would require write-through or COW management.** `RootfsSource::Bind`
  hands the host directory to the VM as the rootfs. The microsandbox example
  uses it for a single one-shot sandbox; we'd need an overlay on top to share
  a template across multiple concurrent invocations. The OCI path already
  handles this via the layer cache.
- **Disk-image (qcow2) would mean building rootfs images ourselves.** Doable
  with `debootstrap` + `mkfs.ext4`, but the build steps are less familiar
  than `docker build` and the rebuild loop is slower.

The price is that we now run a Docker daemon and a `registry:2` container on
the host. Acceptable: every dev who needs to *build* the image already needs
Docker, and the registry container is ~30 MB and starts in <1 s. End users who
only pull a prebuilt image won't run the local registry at all (Phase 9
distribution territory).

### Image content: deliberately minimal

The current Dockerfile installs only what each of the three agents needs to
run plus the dev tools that are universally useful:

- Base: `ca-certificates`, `curl`, `wget`, `git`, `jq`, `bash`,
  `python3`/`pip`, `ripgrep`, `fd-find`.
- Chromium + `fonts-liberation` + `sudo` + `libnss3-tools` for the
  Chrome DevTools MCP (Phase 7). Symlinks `/usr/bin/google-chrome` and
  `/opt/google/chrome/chrome` to `/usr/bin/chromium` so puppeteer's
  default discovery paths resolve. Dedicated `chrome` user (UID 9999)
  with home `/home/chrome`, empty NSS DB at `~/.pki/nssdb`, sudoers
  rule `root ALL=(chrome) NOPASSWD: ALL`, and a wrapper at
  `/usr/local/bin/agent-vm-chrome-mcp` that re-execs the MCP under
  that user. Pre-warmed npm cache for `chrome-devtools-mcp@1.0.1`
  under `/home/chrome/.npm/_npx/` so first launch is a cache hit.
- `gh` from cli.github.com/packages (Phase 6 — gh/git credential
  injection).
- Node.js 22 from NodeSource (needed by Claude Code, OpenCode, MCP servers).
- Agents installed via their canonical installer scripts so we track upstream
  release channels: `claude.ai/install.sh`, `opencode.ai/install`, and the
  Codex `install.sh` from GitHub releases.

Explicitly skipped in v1 (per PLAN.md scope cuts): Docker-in-VM, LSP
plugins, `mitmproxy` (microsandbox does the interception in Phase 3,
no in-VM proxy needed), GitHub Copilot CLI. Each line we keep is a
line that has to keep working through `apt-get update` churn, so the
bar to add anything is "needed by an in-scope agent flow."

Resulting image: a few GB uncompressed (chromium is the largest
contributor at ~400 MB, followed by Node.js and the agent CLIs;
re-measure with `docker images` when you care about exact bytes).
Registry layer count is bounded by the `RUN` granularity in the
Dockerfile.

### Image build is shelled to Bash, not done in Rust

`crates/agent-vm/src/setup.rs::run_build_script` spawns
`bash images/build.sh`. We don't talk to the Docker daemon directly because:

- Docker has a CLI that every developer already knows how to read, run, and
  debug. A Rust caller wrapping the API would only add a layer.
- The build script is the right place for host-shell idioms (volumes,
  port-forwarding the registry, `docker inspect` checks) and stays out of
  the way of the Rust binary's logic.
- Rebuilding the image doesn't require recompiling the binary, and vice
  versa.

The Rust side does own the **verify** step (boot from the freshly pushed
image, run the three `--version` commands), because that step is exactly the
microsandbox SDK call the launcher will make in Phase 2 — exercising it from
`setup` ensures we catch image/SDK-integration regressions before any user
session depends on them.

### `setup --no-verify` and `--image`

Two escape hatches surfaced from the start:

- `--no-verify` lets a developer iterate on the Dockerfile without paying for
  a sandbox boot each loop.
- `--image` / `AGENT_VM_IMAGE_TAG` lets us point at an alternative tag (a
  prebuilt image on GHCR, a developer's experimental tag, etc.) without
  touching `build.sh`. The default stays `localhost:5000/agent-vm:latest` so
  the happy path matches what `build.sh` produces.

## Phase 2 — Launcher MVP

### Layout

```
crates/agent-vm/src/
├── main.rs           # clap entry: setup | claude | codex | opencode | shell
├── setup.rs          # unchanged from Phase 1
├── run.rs            # `agent-vm <agent>`: build sandbox, attach or exec
└── session.rs        # project-dir hash, state dirs, sandbox name
```

### Project-scoped sandbox name + state dir

Each project gets:

- A short hash: first 6 bytes of `SHA256(canonical(cwd))` rendered as 12 hex
  chars (~48 bits — plenty for "no two project dirs on one host collide").
- A state directory at
  `${AGENT_VM_STATE_DIR-${XDG_STATE_HOME-$HOME/.local/state}/agent-vm}/<hash>/`.
- A sandbox name of `agent-vm-<hash>`.

The hash being short enough to fit in `<hostname>` is convenient when
debugging from inside the sandbox (`hostname` shows it). The sandbox name
being deterministic means a second `agent-vm claude` in the same project
*replaces* the first one (`.replace()` on the builder gives it 10 s to exit
gracefully, then SIGKILLs) instead of spawning a parallel VM.

The launcher prints a one-line banner on startup
(`==> agent-vm-<hash> in <cwd> (state: <dir>)`) so users always know which
project a given sandbox is bound to.

### Mounts: one for workspace, one for state, no third

When this layout was chosen, the microsandbox runtime was running with
libkrun's default in-kernel IOAPIC, which hands ~11 IRQs to virtio-mmio
devices total on x86_64. The OCI rootfs already consumes two slots (EROFS
lower + ext4 upper), plus virtio-net + vsock + console + agentd's
serial — adding a bind mount per agent state directory (claude, codex,
opencode) pushed us over and `RegisterBlockDevice(IrqsExhausted)` at boot
followed. We later lifted the underlying cap by enabling `msb_krun`'s
userspace split irqchip (see "Split irqchip and the virtio-IRQ ceiling"
below; cap is now ~219), but the one-workspace + one-state layout still
makes sense regardless: one virtio-fs server, one rootfs `patch` entry
per agent, and a stable on-host layout.

Resolution:

- One bind mount for `cwd → /workspace` (the project).
- One bind mount for `<state-dir> → /agent-vm-state` (everything else).
- The agents' expected paths are wired up *inside* the rootfs by Phase 1's
  `patch` API (rootfs symlinks baked into the upper overlay before VM start):
  - `/root/.claude → /agent-vm-state/claude`
  - `/root/.local/share/opencode → /agent-vm-state/opencode`
  - Codex uses the `CODEX_HOME=/agent-vm-state/codex` env var instead of a
    symlink, because `/root/.codex/packages/...` in the base image contains
    the codex binary itself and a symlink would shadow it.

This keeps us at two virtio bind mounts no matter how many agents we add
later, and leaves plenty of IRQ headroom for user-supplied `--mount`
arguments now that the split irqchip is on.

### Split irqchip and the virtio-IRQ ceiling

`msb_krun` exposes a `MachineBuilder::split_irqchip(bool)` knob. With it
off (default), libkrun uses KVM's in-kernel IOAPIC, which is hard-capped at
24 pins and only hands IRQs 5..=15 to virtio-mmio — about 11 usable IRQs
for the whole VM. That fills up fast: rootfs lower + rootfs upper +
virtio-net + virtio-vsock + virtio-console + virtio-fs (project) +
virtio-fs (state) already saturates it on this build, so an extra
`--mount` would trip `RegisterNetDevice(IrqsExhausted)` at boot.

With split_irqchip enabled, `msb_krun` runs a userspace IOAPIC backed by
an event-loop thread it spawns automatically. The pin count rises to 219,
which puts the practical ceiling on `--mount` well into the hundreds. The
trade-off is one extra worker thread per VM and a slightly hotter IRQ
delivery path; we accept it because the IRQ headroom is the difference
between "one or two extra mounts work" and "you can stop worrying about
the cap." aarch64/riscv64 ignore the knob — their GIC/AIA models already
expose >200 IRQs.

The runtime sets `split_irqchip(true)` unconditionally in
`vendor/microsandbox/crates/runtime/lib/vm.rs`. The user-facing
`--mount` doc and Phase 7's wiring in `crates/agent-vm/src/run.rs` were
updated to drop the pre-cap warning that previously fronted the limit.

The change also bumped `msb_krun` from 0.1.12 → 0.1.13 across the
vendor crates (`runtime`, `filesystem`, `network`). 0.1.12's userspace
IOAPIC was unusable in practice: its IRR was a single `u32` so any IRQ
delivered on pin ≥ 32 was dropped without notice, and the redirection-
table register-index calculation in `read`/`write` did an unchecked
`ioregsel - IOAPIC_REG_REDTBL_BASE` that wrapped on any access below
the redirection-table base — which the guest performs during normal
IOAPIC programming. Both fixes landed in 0.1.13, published 2026-05-26.
The PLAN's Discovered Upstream Issue #3 was originally attributed to
"the libkrun IRQ cap"; with hindsight, the cap is a real KVM-level
ceiling but the multi-mount boot failure that finally drove this work
was a separate, fixable bug inside `msb_krun_devices`'s userspace
IOAPIC, only ever reached once the split irqchip was turned on.

### Interactive attach vs. non-TTY exec

`Sandbox::attach()` requires a real controlling TTY: it puts stdin in raw
mode and opens `/dev/tty` for its non-blocking input fd. When stdin isn't a
TTY (pipe, redirect, smoke test under `sg`/`sudo -c`, CI), `attach` returns
ENXIO.

The launcher checks `std::io::stdin().is_terminal()` and branches:

- **TTY** → `attach(cmd, args)` — the agent's TUI gets a full PTY and is
  fully interactive.
- **No TTY** → `exec_with(cmd, |e| e.args(args).cwd("/workspace"))` — runs to
  completion, then forwards collected stdout/stderr and the exit code.

Non-TTY mode loses the live streaming TUI experience but gives the caller a
clean `stdout | other-tool` story. Streaming stdout/stderr during run landed
in the Phase 4 verification session (2026-05-24) — see PLAN.md.

### Credentials: env-var only, deliberately

Phase 2 reads `ANTHROPIC_API_KEY` and `OPENAI_API_KEY` from the host
environment and forwards them via `.env()`. This is the simplest possible
path that exercises everything else end-to-end. Phase 3 replaces this with
microsandbox's secret-substitution API backed by host-rooted token files,
and Phase 4 adds refresh semantics on top.

Concretely, the env-var path is intentionally insufficient for our real use
case (Claude Code's host OAuth, Codex's host ChatGPT auth, OpenCode's
OAuth flows). That gap stays open until Phase 3.

### `PATH` is set explicitly, not inherited

The Phase 1 Dockerfile puts the agent binaries on `PATH` via an `ENV`
directive, but that PATH only takes effect when an interactive shell sources
the image's profile. `attach()` and `exec()` both spawn the command via
`execve` directly, so we re-publish the same PATH on the sandbox builder
(`/root/.local/bin:/root/.claude/local/bin:/root/.opencode/bin:/usr/local/
bin:/usr/bin:/bin`). Otherwise `agent-vm claude` would `ENOENT` immediately.

### Tunables: env-var-driven for now

`AGENT_VM_IMAGE_TAG`, `AGENT_VM_MEMORY_MIB`, `AGENT_VM_CPUS` cover the three
knobs you actually want to change session-to-session. `--memory` and
`--cpus` were promoted to clap flags (`1817391`); `--image` and friends are
on the Phase 9 polish list. Env-var-only kept the
Phase 2 surface small and means we don't have to design the `--memory 4G`
vs `--memory 4096` ergonomics yet.

### What Phase 2 deliberately doesn't do

- **No live DoD smoke against the Anthropic API.** The Phase 2 DoD in
  PLAN.md calls for `agent-vm claude -p 'say hi'` returning a real Claude
  response, but on this host we only have a Claude OAuth credential (not an
  `ANTHROPIC_API_KEY`), and Phase 2 explicitly does *not* implement OAuth
  plumbing. We verified all of Phase 2's wiring end-to-end via the `shell`
  subcommand (workspace mount, state persistence, env propagation, all three
  agent CLIs resolvable on PATH) and explicitly chose to close the API-call
  gap during Phase 3's host-OAuth work rather than ferry an ephemeral API
  key through this session.

## Phase 3 — Host-rooted secrets

### Layout

```
vendor/microsandbox/  (branch: agent-vm-secret-file)
└── crates/network/lib/secrets/
    ├── config.rs            # new: SecretValue { Static, File } enum
    └── handler.rs           # resolves SecretValue at connection-setup

crates/agent-vm/src/
├── secrets.rs               # new: read host creds, write placeholders
├── run.rs                   # wire TLS intercept + secret_env per provider
└── main.rs                  # register secrets module
```

### Two-layer placeholder dance

Real tokens never enter the VM. The dance per provider:

1. **Host side.** agent-vm reads the host's credential file
   (`~/.claude/.credentials.json` for Claude,
   `~/.codex/auth.json` for Codex) at every launch. It extracts the
   access token, keeps it in a short-lived Rust `String`, and registers
   it as a microsandbox secret with a stable placeholder string
   (`msb-anthropic-placeholder-a-v2` and
   `msb-openai-placeholder-a-v2`). The placeholder *constants* live in
   `crates/agent-vm/src/secrets.rs` (`ANTHROPIC_ACCESS_PLACEHOLDER` etc.) —
   prefer the constant over the literal so a future rename doesn't drift.
2. **Guest side.** agent-vm writes a "placeholder credentials" JSON
   into the per-project state dir
   (`<state>/claude/.credentials.json`,
   `<state>/codex/auth.json`) using the placeholder string instead of
   the real token. Other fields (`expiresAt`, `scopes`, `account_id`,
   `last_refresh`, etc.) are copied from the host file so the in-VM
   agent sees a plausible JSON shape. `refreshToken` is set to a
   sentinel string — Phase 3 doesn't handle refresh.
3. **TLS interception.** microsandbox's network proxy intercepts the
   sandbox's HTTPS traffic. When the agent makes a request to any
   allowed host (`api.anthropic.com`, `platform.claude.com`,
   `api.openai.com`, `chatgpt.com`, `auth.openai.com`), the proxy
   sees `Authorization: Bearer msb-…-placeholder-…` in the outgoing
   request, splices in the real token from the secret config, then
   forwards.

The agent inside the VM never sees the real token in any form
(`/proc/$$/environ`, `cat ~/.claude/.credentials.json`, network
introspection inside the guest all show only the placeholder). It
gets the real token only as a header-mangled middlebox effect on the
way out — which is structurally what microsandbox was designed for.

### Upstream extension: `SecretValue { Static, File }`

Pre-Phase 3, `SecretEntry.value` was a `String` captured at builder
time. That worked for static API keys but precluded host-side OAuth
rotation — there was no way to surface a new token to a running
sandbox short of rebuilding it.

The `agent-vm-secret-file` branch of vendor/microsandbox adds
`SecretValue { Static(String), File(PathBuf) }` and changes
`SecretEntry.value` to that enum. The handler resolves `File` at
connection-setup time, so each new request to an allowed host sees the
current file contents. Wire format stays a single JSON string for
backward compatibility with the prebuilt `msb` daemon already on
users' hosts:

| Variant | Wire format |
|---|---|
| `Static(v)` | `"v"` — a bare JSON string, identical to the old `value: String` form |
| `File(p)` | `"\0msbfile:<path>"` — a NUL-prefixed sentinel string |

The NUL prefix is unforgeable in API tokens (always printable ASCII).
Old `msb` daemons that don't recognise the sentinel treat the whole
thing as an opaque string and substitute it verbatim — broken for
`File`, but never crashes.

### Phase 3 uses `Static` only

`SecretValue::File` is the right primitive for refresh-aware
substitution, but turning it on end-to-end requires a `msb` daemon
built from our forked source replacing the prebuilt one at
`~/.microsandbox/bin/msb`. Phase 3 doesn't ship that distribution
plumbing — it captures the host token as a `String` at launch time
and passes `SecretValue::Static(token)` to microsandbox. The sandbox
lives until the token's TTL (usually hours); rotation is a Phase 4
problem.

### Allowed-host lists

Per-provider, we allow the API host *and* the OAuth-token host. The
OAuth-token host doesn't actually need substitution in Phase 3 (we
don't intercept the refresh flow yet), but we have to allow it,
otherwise the in-VM agent's refresh attempt would trigger
microsandbox's secret-violation detector (placeholder going to a
disallowed host = `BlockAndLog` blocks the request). Letting the
placeholder reach the OAuth host means the upstream server just
rejects it normally, which is at least a comprehensible failure.

| Provider | Allowed hosts |
|---|---|
| Anthropic | `api.anthropic.com`, `platform.claude.com` |
| OpenAI    | `api.openai.com`, `chatgpt.com`, `auth.openai.com` |

### `IS_SANDBOX=1`

Claude Code refuses to run as root with
`--dangerously-skip-permissions` unless `IS_SANDBOX=1` is set. The
in-guest user is root, and the whole point of the microVM is that
the sandbox itself is the boundary — so we set `IS_SANDBOX=1` on
the builder. Same env var the original Bash agent-vm used.

### Smoke verification

End-to-end verified on a nested-VM test host (cwd
`/home/boger.linux/agent-vm-phase3-test`):

- `cat /root/.claude/.credentials.json` inside the guest shows the
  placeholder, not the real token. ✓
- `cat /proc/1/environ | tr '\0' '\n' | grep -i token` finds only
  `MSB_AGENT_VM_ANTHROPIC_UNUSED=msb-…-placeholder-…`. ✓
- TLS-intercepted curl to `https://api.anthropic.com` sees the
  microsandbox CA on the server cert (`CN=microsandbox CA`),
  confirming requests go through the substitution proxy. ✓
- `AGENT_VM_DEBUG_CONFIG=1` dumps the SandboxConfig JSON and the
  secret value is the host's real `accessToken` (which on this nested
  test host is itself a placeholder relayed to the outer host's real
  bridge — see below). ✓

The *final* leg ("api.anthropic.com returns a real response") can't
be verified on this host because we're running inside an outer
agent-vm whose own credential bridge intercepts requests on the outer
host's localhost — which our nested microsandbox can't reach. On a
non-nested host with a real Claude OAuth credential, the substituted
bearer reaches Anthropic verbatim and the response is real. The same
flow is structurally identical to how the original Bash agent-vm's
credential-proxy works.

### What Phase 3 deliberately doesn't do

- **No refresh.** Long sessions will hit a 401 when the captured
  access token expires (typically hours). Phase 4 closes this.
- **No `~/.microsandbox/bin/msb` replacement.** The `SecretValue::File`
  variant requires a `msb` rebuilt from our fork to actually re-read
  the file. Without that the Static path is what gets exercised, and
  it does work against unpatched `msb` (wire-format compatibility was
  the explicit design goal of the bare-string sentinel encoding).
- **No host-side OAuth token endpoint short-circuiting.** When the
  in-VM agent tries to refresh, the request goes upstream and is
  rejected by Anthropic/OpenAI because the placeholder refresh token
  isn't real. The original Bash agent-vm has logic to MITM the
  `platform.claude.com/v1/oauth/token` and `auth.openai.com/oauth/token`
  endpoints and forge responses from re-reads of the host file. That's
  Phase 4.

## Phase 4 — OAuth refresh: file-backed secrets + interceptor hook

Phase 3 left a 401-then-die failure mode: when the captured access
token expires mid-session the in-VM agent gets 401 from the API, tries
to refresh against the OAuth endpoint with the placeholder refresh
token, and gets 401 again. The user has to exit and re-launch.

Phase 4 closes the loop end-to-end. Two upstream microsandbox
extensions plus an agent-vm subprocess handle it.

### Pieces

```
vendor/microsandbox/  (branch: agent-vm-secret-file)
└── crates/network/lib/
    ├── secrets/config.rs       # SecretValue::File (from Phase 3) is now actually used
    └── intercept/              # new: per-route request-interceptor hook
        ├── config.rs           #   InterceptConfig (rules + hook command)
        └── handler.rs          #   per-connection state machine

crates/agent-vm/src/
├── msb_install.rs              # new: build patched msb from vendor; point MSB_PATH at it
├── intercept_hook.rs           # new: `agent-vm _intercept-hook` subprocess
├── secrets.rs                  # switched from Static(token) to File(<state>.secrets/{anthropic,openai})
└── run.rs                      # registers the interceptor with two rules
```

### Patched `msb` shipped via `MSB_PATH`

`agent-vm setup` now runs
`cargo build --release -p microsandbox-cli --bin msb` in
`vendor/microsandbox` and leaves the artifact at
`vendor/microsandbox/target/release/msb`. At startup, every agent-vm
invocation sets `MSB_PATH` to that path (top of microsandbox's
resolution ladder), so the patched binary is what actually runs the
VM. The user's `~/.microsandbox/bin/msb` is never touched and
upstream-installed tooling on the same host keeps using its own
prebuilt.

The real msb binary lives in the `microsandbox-cli` crate; the
`microsandbox` crate has a separate `microsandbox` binary that's
just a 5-line shim forwarding to `~/.microsandbox/bin/msb`. Building
the wrong target produces a 389 KB shim that boots silently then
hangs at VM init — about 30 minutes of debugging into a
no-VMM-symbols-in-the-binary surprise. Recorded here so the next
person doesn't redo it.

### `SecretValue::File`

Phase 3's per-launch snapshot becomes a per-launch *file write*. We
write the host's `accessToken` to a host-only secret file (see next
subsection for *where*) with 0600 perms via atomic-write-then-rename.
The launcher passes the file path to microsandbox as a
`SecretValue::File`.

The patched msb's TLS-intercept proxy calls `SecretValue::resolve()`
at *connection-setup* time — every new TCP connection re-reads the
file. So any host-side rotation (whether triggered by the user's
external `claude` use or by our interceptor hook below) is visible
to the very next request, without rebuilding the sandbox.

### Token files live *outside* the guest bind mount

The launcher bind-mounts the per-project `state_dir` into the guest at
`/agent-vm-state` as a *single* mount. The single-bind shape originally
fell out of libkrun's tight virtio-IRQ cap (one bind for all per-agent
state instead of one per agent — see "Mounts: one for workspace, one
for state, no third"), and we've kept it after lifting the cap because
it gives a stable on-host layout and a single virtio-fs server. That
makes mount placement security-critical: **anything under `state_dir`
is readable from inside the VM.**

The real access-token files therefore must *not* live under
`state_dir`. They sit in a sibling host-only directory
`${state_root}/<hash>.secrets/` (mode 0700), derived from `state_dir`
by `secrets::{anthropic,openai}_token_path` so the launcher and the
refresh hook agree on the path without passing it explicitly. The
microsandbox proxy reads these files on the *host* side via
`SecretValue::File`, so they never need to be mounted into the guest at
all.

This was a real leak found during Phase 4 end-to-end verification: the
first cut wrote the tokens to `<state>/tokens/{anthropic,openai}`, i.e.
*inside* the mount, so `cat /agent-vm-state/tokens/anthropic` in the
guest returned the host's real bearer — silently defeating the entire
"real tokens never enter the VM" guarantee. The nested test host masked
it (there the "real" token is itself the outer bridge's placeholder), so
it only surfaced once we grepped the guest filesystem for the token
during verification. A `token_files_live_outside_the_guest_mount` unit
test now guards the invariant.

### Request-interceptor hook (the OAuth refresh MITM)

`microsandbox-network` gained an `InterceptConfig` that the launcher
fills with:

```rust
.intercept(|i| i
    .hook(["…/agent-vm", "_intercept-hook", "--state-dir", "…"])
    .rule("platform.claude.com", "POST", "/v1/oauth/token")
    .rule("auth.openai.com",     "POST", "/oauth/token"))
```

When the in-VM agent posts an OAuth refresh request, the proxy:

1. Buffers the full request (it's tiny — <1 KB — so this is cheap
   and capped at 64 KiB).
2. Spawns the hook command with the request bytes on stdin and four
   env vars (`MSB_INTERCEPT_SNI/_HOST_RULE/_METHOD/_PATH_PREFIX`).
3. Reads the hook's stdout as the response and writes it back to the
   guest, encrypted under the forged TLS cert.
4. Closes the connection without ever touching the upstream server.

The hook (`agent-vm _intercept-hook`) is the same binary in a hidden
clap subcommand mode:

1. Reads the request from stdin (sanity-checks it's `POST …`).
2. Spawns `claude -p hi --model sonnet` (or `codex exec --skip-git-
   repo-check 'Reply OK'`) on the **host** so the host CLI rotates
   `~/.claude/.credentials.json` / `~/.codex/auth.json` the normal way.
3. Re-reads the rotated host file, rewrites the host-only token file
   (`<state>.secrets/{anthropic,openai}`) so the next non-refresh
   request from the guest gets the new bearer via `SecretValue::File`.
4. Synthesizes an OAuth refresh-response JSON shaped like what the
   upstream server would return, but with **placeholder** strings in
   the `access_token` / `refresh_token` fields. The in-VM agent
   updates its credentials.json to those placeholders and continues.
5. Writes the response to stdout, exits 0.

The guest never holds a real token at any layer:
- `~/.claude/.credentials.json` always contains placeholders (Phase 3).
- The real-token file is on the host *outside* the guest bind mount
  (see "Token files live outside the guest bind mount").
- The proxy substitutes real-for-placeholder on the way *out* (Phase 3).
- The OAuth refresh response also returns placeholders (Phase 4).
- The host CLI on the host is the only thing that ever touches real
  OAuth machinery, and it writes to a file we re-read.

### Hook-process boundary, not callback

The interceptor uses a subprocess (fork+exec per request) rather than
a callback into the SDK. Reasons:

- `Vec<Box<dyn RequestInterceptor>>` isn't serializable. The
  network config is JSON-piped from the SDK to a separate `msb`
  process, so anything we configure on the SDK side has to round-trip
  through JSON.
- Refresh requests are rare (once per hour at worst). Fork-per-request
  overhead is irrelevant against the latency of the host `claude`
  invocation that the hook does anyway.
- A subprocess can dispatch on any logic without us having to
  re-extend microsandbox each time we add a provider.

### Smoke verification

```
Inside the guest:
  POST https://platform.claude.com/v1/oauth/token
  body: {"grant_type":"refresh_token","refresh_token":"…PLACEHOLDER_REFRESH…"}

Response:
  HTTP 200 application/json
  {"access_token":"msb-anthropic-placeholder-a-v2",
   "refresh_token":"msb-anthropic-placeholder-r-v2",
   "expires_in":3499, "token_type":"Bearer",
   "scope":["user:file_upload","user:inference",…]}
```

Confirmed on the same nested-VM test host as Phase 3. The hook ran,
host `claude -p` rotated the host file, the new bearer landed in
`<state>.secrets/anthropic`, and the synthesized response reached the
guest. `expires_in: 3499` is the freshly-derived seconds-until-expiry
of the just-rotated token.

### What Phase 4 deliberately doesn't do

- **No proactive expiry timer.** Discussed and rejected: the
  guest's own refresh attempt at 401-time triggers our hook, which
  triggers the host-side refresh. If the user runs `claude` on the
  host between sessions, the host file is already fresh and the
  `SecretValue::File` re-read picks it up with no hook involved.
  A timer would be belt-and-suspenders.
- **No msb shipped via `~/.microsandbox/bin/msb`.** The MSB_PATH
  override is per-agent-vm-invocation only; other microsandbox SDK
  consumers on the same host keep using the upstream prebuilt.
- **No single-flight for concurrent in-guest refreshes.** Two
  concurrent refresh attempts could each spawn a host `claude -p`.
  The host CLI's own file lock prevents corruption, so the worst
  outcome is one extra `claude -p` invocation. If this becomes a
  pain point, a `<state>/tokens/.refresh.lock` flock around the host
  CLI invocation is two lines.