[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M77K8A08HA7YNJB4PHPG1ADC":3,"skill-same:01M77K8A08HA7YNJB4PHPG1ADC":44},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":18,"publishedAt":19,"linkOnly":20,"markdownContent":21,"markdownBody":22,"frontMatter":23,"refName":24,"commitSha":25,"skillDirectory":26,"forksCount":14,"repositoryHtmlUrl":27,"repositoryHomepageUrl":6,"ownerHtmlUrl":28,"ownerBlogUrl":6,"ownerDescription":6,"updatedAt":29,"install":30,"resources":43},"01M77K8A08HA7YNJB4PHPG1ADC","claude-vm",null,"Launch Claude Code inside an isolated Linux micro-VM on macOS with config-driven egress, mounts, VM resources, guest environment variables (including third-party API keys forwarded by name from the host, never written into config), and repo isolation (clone or live). All non-secret knobs come from four-file YAML (a bake file + a boot file per tier, global + per-repo, all optional); the immutable base image is APFS-cloned per run so concurrent sessions never leak state. The guest authenticates with the host's claude.ai OAuth credential extracted from the macOS Keychain at launch, plus an identity seed (userID + oauthAccount from the host's ~\u002F.claude.json, plus synthesized onboarding\u002Fauto-update-off\u002Fversion keys) so the in-guest session comes up already onboarded, logged in, and with self-update disabled.","TheVoskamps\u002Fclaude-plugins-marketplace","TheVoskamps","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F235012489?v=4","01M77K5ZCP12QCJPQ85WVJSHTS","Irene and Edwin Voskamp","01M77K5ZDS7DB0PA1W8FM7G2QD",0,"GPL-3.0","https:\u002F\u002Fgithub.com\u002FTheVoskamps\u002Fclaude-plugins-marketplace\u002Fblob\u002Fmain\u002Fplugins\u002Fclaude-vm\u002Fskills\u002Fclaude-vm\u002FSKILL.md",[],[],"2026-11-15 14:19:17",false,"---\nname: claude-vm\ndescription: Launch Claude Code inside an isolated Linux micro-VM on macOS with config-driven egress, mounts, VM resources, guest environment variables (including third-party API keys forwarded by name from the host, never written into config), and repo isolation (clone or live). All non-secret knobs come from four-file YAML (a bake file + a boot file per tier, global + per-repo, all optional); the immutable base image is APFS-cloned per run so concurrent sessions never leak state. The guest authenticates with the host's claude.ai OAuth credential extracted from the macOS Keychain at launch, plus an identity seed (userID + oauthAccount from the host's ~\u002F.claude.json, plus synthesized onboarding\u002Fauto-update-off\u002Fversion keys) so the in-guest session comes up already onboarded, logged in, and with self-update disabled.\n---\n\n# claude-vm\n\nRun Claude Code inside an isolated Linux micro-VM on macOS. Every\nnon-secret operational knob — VM resources, the egress allowlist, extra\nmounts, the proxy, the guest's own environment variables, and how the\nrepo is made available to the guest — comes from layered **YAML config**\nrather than claude-vm's own environment variables.\nThe guest authenticates with the **host's live claude.ai OAuth\ncredential**, which the launcher extracts from the macOS Keychain at\nlaunch and shares into the guest (where the image's fstab mounts the\nshare `ro`), plus an **identity seed** the launcher builds from your host\n`~\u002F.claude.json` — the `userID` + `oauthAccount` selected from the host,\nplus synthesized\n`hasCompletedOnboarding` \u002F `autoUpdates: false` \u002F version keys — so the\ninteractive in-guest session comes up already onboarded, logged in, and\nwith self-update disabled (issue #88). Both are secrets, neither is\nwritten to config, and both ride the same transient shred-on-exit\nmount. No token environment variable is required — just be logged in to\nClaude Code on the host.\n\nThe entry point is `bin\u002Fclaude-vm` (issue #51), a preflight wrapper\nthat ships on PATH for the Bash tool; it forwards to the launcher and\nimage-build scripts, which ship as payloads under\n`${CLAUDE_PLUGIN_ROOT}\u002Fpayload\u002F`. This skill explains the config\nsurface and drives the launcher.\n\n## Quick start\n\n```bash\n# 1. Be logged in to Claude Code on this host. The launcher installs the\n#    host's live claude.ai OAuth credential (extracted from the macOS\n#    Keychain) AND seeds the guest's identity (userID + oauthAccount from\n#    your ~\u002F.claude.json, plus synthesized onboarding\u002Fauto-update-off\n#    keys) so the in-guest claude comes up already onboarded and logged\n#    in. Run `claude` once and complete the claude.ai login if you have\n#    not; the launcher aborts at a preflight if you are not logged in.\n#    No token environment variable is required.\n\n# 2. (Optional) drop a global config PAIR at\n#    ~\u002F.config\u002Fclaude-vm\u002Fconfig-bake.yml + config-boot.yml and\u002For a\n#    per-repo pair at \u003Crepo>\u002F.claude-vm\u002Fconfig-{bake,boot}.yml. A bake\n#    file holds image-bytes keys; a boot file holds run-time keys.\n#    Run \u002Fclaude-vm-config-global to write the global pair from the\n#    resolved defaults, and \u002Fclaude-vm-config-repo (from inside a repo)\n#    to write per-repo overrides (both idempotent), or see\n#    payload\u002Fconfig-bake.example.yml + config-boot.example.yml for a\n#    starting point. bin\u002Fclaude-vm below also offers to create the global\n#    config for you if it is missing. (A legacy single-file config.yml is\n#    no longer read -- the launcher aborts with a migration message.)\n\n# 3. Launch from inside the repo you want to run a VM for. bin\u002Fclaude-vm\n#    derives the repo name and root, names the run, and forwards to the\n#    launcher, which makes the repo available RW to the guest.\nclaude-vm [claude args...]\n```\n\nOn exit, the launcher copies the guest's changes back to the local\nsource by default (clone mode). The companion skills extract work\nexplicitly: `\u002Fclaude-vm-diff`, `\u002Fclaude-vm-apply-local`,\n`\u002Fclaude-vm-apply-remote`.\n\n## Config surface\n\n**Four files, all optional** (issue #179) — a **bake** file and a\n**boot** file per tier. Placement rule: a key that changes **bytes in\nthe guest `.raw` image** goes in a **bake** file; a key applied at **run\ntime** goes in a **boot** file. Placement IS the classification, made\nonce by the operator — a knob in the wrong file loudly does nothing\ninstead of silently poisoning the image cache.\n\n1. **Global bake**: `~\u002F.config\u002Fclaude-vm\u002Fconfig-bake.yml` — machine-wide\n   image-bytes defaults.\n2. **Global boot**: `~\u002F.config\u002Fclaude-vm\u002Fconfig-boot.yml` — machine-wide\n   run-time defaults.\n3. **Per-repo bake**: `\u003Crepo>\u002F.claude-vm\u002Fconfig-bake.yml` — this repo's\n   image-bytes overrides. Shipping this file gives the repo its OWN image.\n4. **Per-repo boot**: `\u003Crepo>\u002F.claude-vm\u002Fconfig-boot.yml` — this repo's\n   run-time overrides.\n\nRun `\u002Fclaude-vm-config-global` to create the global pair from the\nresolved defaults, and `\u002Fclaude-vm-config-repo` (from inside a repo) to\nwrite per-repo overrides; both are idempotent and never clobber an\nexisting file. A legacy single-file `config.yml` (either tier) is no\nlonger read — the launcher aborts with a migration message rather than\nsilently dropping the knobs it set.\n\n**What goes where:**\n\n- **bake file** — `packages:` (a flat list of apt packages baked into\n  the image), `apt_sources:` (third-party apt repos rendered into the\n  image), `image.root_headroom_mb`, `env.set` (guest environment\n  variables written INTO the image — literals only).\n- **boot file** — `cpus`, `mem`, `guest_image`, `repo.*`, `proxy.*`,\n  `egress.allow`, `mounts`, `provisioner`, `packages:` (here a flat\n  list installed AT BOOT), `update_at_boot`, `add_apt_uris_to_allowlist`,\n  `apt_sources:` (for a boot-time install; union+dedup with the bake\n  file's), `claude.*`, `github.*`, `env.*` (all three sub-keys;\n  `env.copy` and `env.files` are boot-ONLY and abort in a bake file).\n\n### Layering semantics\n\nThe effective config is the union of all four files (compose each tier's\nbake+boot, then merge global under repo):\n\n- **Scalars** (`cpus`, `mem`, `guest_image`, `image.root_headroom_mb`\n  [bake], `repo.mount`, `repo.copy_back`, `proxy.*`, `claude.version`,\n  `claude.renderer`, `update_at_boot`, `add_apt_uris_to_allowlist`,\n  `claude.permission_mode`, `claude.plugins.update_at_boot`,\n  `claude.plugins.add_marketplace_uris_to_allowlist`, `github.auth`):\n  repo overrides global; global fills gaps; a hardcoded default applies\n  only when neither layer sets the key.\n- **Scalar maps** (`claude.plugins.enabled`, `env.set`): repo overrides\n  global **per key** — each entry follows the scalar repo-wins rule\n  independently, so a repo can flip one plugin's enabled state, or one\n  environment variable's value, without restating the global map.\n- **Lists** (bake file: `packages`, `apt_sources`, `claude.marketplaces`,\n  `claude.plugins.bake`; boot file: `egress.allow`, `mounts`, `packages`,\n  `apt_sources`, `claude.marketplaces`, `claude.permissions.allow`,\n  `claude.permissions.ask`, `claude.permissions.deny`,\n  `claude.plugins.install_at_boot`, `env.copy`, `env.files`): **merged** —\n  the union of global + repo entries, de-duplicated. `apt_sources` and\n  `claude.marketplaces` are allowed in **both** file types; each is unioned\n  and deduped by `name`, and the same name with DIFFERING content\n  (`{repo, key_url}` \u002F `url`) aborts the launch (no silent shadowing).\n- **Placement guard**: `claude.plugins` is the one map that legitimately\n  appears in both file types, so a sub-key in the wrong file aborts the\n  launch with a message naming the file that carries it — `bake` belongs in\n  the bake file (it changes image bytes), and `install_at_boot` \u002F\n  `update_at_boot` \u002F `add_marketplace_uris_to_allowlist` \u002F `enabled` belong in\n  the boot file. A *presence* test, so a misplaced sub-key written empty (a\n  valueless `bake:`, or `bake: []` \u002F `\"\"` \u002F `{}`) aborts exactly like a\n  populated one.\n  `env` has the same shape and its own guard: `env.set` is allowed in both\n  file types, while `env.copy` and `env.files` are **boot-only** and abort in\n  a bake file — a *presence* test, so an empty or valueless `env.copy:`\n  aborts too. See *Guest environment variables* below for why.\n\n### Keys\n\n```yaml\n# The keys below are grouped by which FILE they live in (bake vs boot). A key\n# in the wrong file loudly does nothing rather than silently poisoning the cache.\n\n# --- BOOT file keys (config-boot.yml -- run-time; never rebuild the image) ---\ncpus: 4\nmem: 8192\nguest_image: \u002Fpath\u002Fto\u002Fguest.raw   # repo may override; SET = used verbatim\n                                  # (opts out of image-identity derivation);\n                                  # UNSET = derived guest+global\u003Chash>.raw\n                                  # (no repo-bake file) or\n                                  # guest+global\u003Chash>+\u003Creponame>-\u003Crepohash>.raw\n                                  # (repo ships a config-bake.yml)\n\nrepo:\n  mount: clone                    # clone (default) | live\n  copy_back: local                # local (default) | none\n\n# Boot-time apt: a flat `packages:` LIST installed AT BOOT (through the proxy,\n# blocking, before claude starts -- issue #106); update_at_boot runs\n# `apt-get update && upgrade`; add_apt_uris_to_allowlist derives apt egress;\n# apt_sources here feed a boot-time install (union+dedup by name with the bake\n# file's; a baked name is not re-rendered). Use install-at-boot packages for\n# things that change often (e.g. the AWS SDK\u002FCLI) so they stay fresh without a\n# rebuild. This requires `apt` in the guest, which mkosi does not provide for\n# free -- so `apt` is baked into every guest image's base Packages= list\n# unconditionally. The guest's baked apt sources are binary-only (main + updates\n# + security, no deb-src\u002Fdebug\u002FTranslations -- issue #106 real-run fix) to keep\n# the per-boot apt working set small; boot_apt_phase ends with `apt-get clean`.\n# The proxy that covers boot-time apt ALSO covers a mid-session interactive\n# apt-get: run.env exports lowercase http_proxy\u002Fhttps_proxy\u002Fno_proxy alongside\n# the uppercase forms (apt honors only lowercase; curl ignores uppercase\n# HTTP_PROXY for plain http:\u002F\u002F), and the boot launcher writes a persistent\n# \u002Fetc\u002Fapt\u002Fapt.conf.d\u002F99claude-vm-proxy so proxying does not depend on a shell\n# re-sourcing run.env.\npackages:                         # (in config-boot.yml) apt packages installed\n  - awscli                        # AT BOOT, through the proxy (a flat list)\nupdate_at_boot: true              # apt-get update && upgrade at boot (default true)\napt_sources: []                   # (boot) third-party repos a boot-time install\n                                  # pulls from: {name, repo, key_url}\nadd_apt_uris_to_allowlist: auto   # auto (default) | always -- adds\n                                  # deb.debian.org\u002Fsecurity.debian.org +\n                                  # apt_sources hosts to guest egress iff\n                                  # boot-time apt work is configured (auto),\n                                  # or unconditionally (always)\n\n# --- BAKE file keys (config-bake.yml -- image bytes; editing rebuilds) ---\n# In config-bake.yml, `packages:` is a flat LIST BAKED into the image (present\n# with no boot-time network), `apt_sources:` are rendered into the image at\n# build time, and image.root_headroom_mb sizes the root partition. The image\n# cache key + filename is a WHOLE-FILE, RAW-BYTE hash of the bake files -- no\n# key-picking, no canonicalization -- so editing a bake file (including only its\n# trailing newline, the documented force-rebuild lever) rebuilds the image;\n# editing a boot file never does. A repo that ships a config-bake.yml gets its\n# OWN image (its name in the filename); a repo without one shares\n# guest+global\u003Chash>.raw.\n#\n# packages:                       # (in config-bake.yml) apt packages BAKED in\n#   - jq\n#   - ripgrep\n# apt_sources: []                 # (bake) third-party repos rendered at build time\n#\n# image.root_headroom_mb: extra MiB of FREE SPACE the guest root filesystem is\n# sized ABOVE its base content (default 1024, repo overrides global). Real-\n# hardware testing hit ENOSPC twice in one short session on a tight-fit-sized\n# root -- boot-time apt working set + ordinary session growth both eat into a\n# root with zero margin. 1024 MB is roughly 20x the observed short-session\n# growth. It is a BAKE key: changing it changes the bake-file hash and triggers\n# a rebuild.\nimage:\n  root_headroom_mb: 1024\n\n# Marketplaces + BAKED plugins (BAKE file). The image build runs the\n# host-verified guest `claude` binary inside the build container with HOME\n# pointed at the image root and drives its own CLI (`claude plugin marketplace\n# add` \u002F `claude plugin install`), so the image ships a real\n# \u002Froot\u002F.claude\u002Fplugins that loads with NO marketplace egress at boot. A failed\n# add\u002Finstall FAILS THE BUILD rather than shipping an image without them --\n# for the marketplaces declared HERE and every `bake:` ref. A marketplace\n# declared only in the boot file is pre-registered as an optimization, and a\n# failure there only warns (the guest adds it at boot).\n# Placement here (not in the boot file) is what puts these under the whole-file\n# image-identity hash; writing `claude.plugins.bake` into a boot file aborts the\n# launch. Prefer an explicit https:\u002F\u002F url over the `owner\u002Frepo` shorthand so the\n# launcher can derive the marketplace's egress host. Shown commented out, like\n# the bake `packages:`\u002F`apt_sources:` above, because the boot file's own\n# `claude:` map follows below and one document cannot carry both.\n#\n# claude:\n#   marketplaces:\n#     - name: thevoskamps\n#       url: https:\u002F\u002Fgithub.com\u002FTheVoskamps\u002Fclaude-plugins-marketplace.git\n#   plugins:\n#     bake:\n#       - block-background-agents@thevoskamps\n#       # COMPILED HOOKS NEED NO TOOLCHAIN: the guardrails permission-gate\n#       # ships prebuilt, committed binaries (one per \u003Cgoos>-\u003Cgoarch>,\n#       # including the guest's linux-arm64), so baking it requires nothing\n#       # in this file's `packages:` -- no `golang`, nothing.\n#       # - guardrails@thevoskamps\n\n# --- BOOT file keys, continued ---\nclaude:\n  version: stable                 # stable (default) | latest | \u003Cpinned>\n                                  # host-side GPG-verified cache key\n  renderer: classic               # classic | fullscreen | (unset)\n                                  # terminal renderer on the interactive\n                                  # console; unset uses claude's own default\n  remote_control: false           # true | false (default) | (unset)\n                                  # opt-in Remote Control: true adds\n                                  # --remote-control + a date-stamped --name\n  permission_mode: bypassPermissions   # bypassPermissions (default) | default\n  permissions:\n    allow: []\n    ask: []\n    deny: []\n  marketplaces: []                # {name, url} entries. Allowed in BOTH file\n                                  # types (like apt_sources); `name` must match\n                                  # the marketplace's OWN manifest name. One\n                                  # declared HERE only has to be reachable from\n                                  # the GUEST -- a url the image build cannot\n                                  # reach warns and is added at boot instead.\n  plugins:\n    # bake: lives in the BAKE file -- see the bake-file block above.\n    install_at_boot: []           # plugin@marketplace refs installed at boot\n    update_at_boot: true          # refresh marketplaces + update the installed\n                                  # plugins at boot (default true). This is the\n                                  # freshness path for BAKED plugins: they are\n                                  # frozen at build time and the image-identity\n                                  # hash excludes marketplace HEAD, so a\n                                  # marketplace bump lands at the next boot with\n                                  # no rebuild.\n    add_marketplace_uris_to_allowlist: auto   # auto (default) | always\n    enabled:                      # OPTIONAL map, plugin ref -> boolean,\n                                  # mirroring settings.json's enabledPlugins.\n                                  # Every bake\u002Finstall_at_boot ref defaults\n                                  # enabled; list an entry only to override\n                                  # (false = installed-but-disabled). Keys must\n                                  # name an installed ref; values must be\n                                  # boolean; a typo aborts the launch.\n      show-loaded-rules@thevoskamps: false\n\nproxy:\n  cmd: \"\u003Cforward-proxy launch command>\"   # must read\n                                          # $CLAUDE_VM_EGRESS_ALLOWLIST\n  port: 3128\n  host_alias: 192.168.127.254\n\negress:\n  allow:                          # outbound hosts permitted via the proxy\n    - api.anthropic.com\n    - github.com\n    - claude.ai\n\nmounts:                           # extra mounts beyond the repo auto-mount\n  - source: ~\u002F.claude\u002Fpolicy      # ALWAYS read-write -- see below\n    tag: policy\n  - source: ~\u002Fdatasets\u002Ffoo\n    tag: data\n  - source: ~\u002F.gitconfig          # a single FILE works too\n    tag: gitconfig\n    path: \u002Froot\u002F.gitconfig        # optional guest mountpoint override\n\ngithub:\n  auth: none                      # none (default) | host-token\n\n# Guest environment variables (issue #135). `set` is allowed in BOTH file\n# types; `copy` and `files` are BOOT-ONLY and abort in a bake file (they read\n# the HOST environment at launch, which does not exist at build time, and\n# their values must never become image bytes). See \"Guest environment\n# variables\" below for the precedence chain and the egress pairing.\nenv:\n  set:                            # explicit literals; NON-SECRET only (these\n    FOO_ENDPOINT: https:\u002F\u002Ffoo.internal\u002Fv2   # values ARE committed config)\n  copy:                           # NAMES read from the environment claude-vm\n    - OPENROUTER_API_KEY          # is launched from; an unset\u002Fempty one aborts\n    - TAVILY_API_KEY\n  files:                          # host .env files parsed at launch; a later\n    - ~\u002F.config\u002Ffoo\u002Fprod.env      # file wins over an earlier one\n```\n\n- `egress.allow` is written to a newline-delimited file whose path is\n  exported as `CLAUDE_VM_EGRESS_ALLOWLIST`. When `proxy.cmd` is unset,\n  the launcher defaults to the bundled tinyproxy launcher\n  (`payload\u002Fproxy\u002Ftinyproxy-launch.sh`), which reads that file and binds\n  `CLAUDE_VM_PROXY_PORT`. A `proxy.cmd` override must likewise read that\n  file instead of a hand-maintained allowlist baked into the command.\n- `mounts` generates the extra `virtio-fs` device flags, and the guest\n  mounts each one at `path:` (default `\u002Fmnt\u002F\u003Ctag>`) before claude starts.\n  A leading `~` in `source` expands to `$HOME`. Both `source` and `tag`\n  are mandatory per entry — the guest mounts each share *by* its tag, so\n  an entry with an empty or omitted `tag:` is a share nobody can mount\n  and two of them would collide on one tag.\n\n  **Every extra mount is read-write, and pierces the VM isolation\n  boundary for that one path.** Guest writes land on the host path\n  **live** — no copy-back step, no review, no undo (`repo.copy_back`\n  governs the *repo* mount only). Everything else about the VM still\n  holds; that one path is simply outside it, on purpose.\n\n  **There is no read-only option, and no `mode:` key.** Read-only cannot\n  be enforced on this stack: vfkit's virtio-fs device has no read-only\n  export (it rejects `readOnly`\u002F`readonly`\u002F`ro` as unknown option keys —\n  verified against vfkit v0.6.4), and the guest session runs as root, so\n  a guest-side `ro` is undoable from inside the guest. A config that\n  still sets `mode:` **aborts the launch** rather than having the key\n  ignored, so nobody believes a share is read-only when it is not.\n  Enforced read-only at the hypervisor boundary is tracked as issue #233.\n  Never point a mount at anything you would mind an autonomous agent\n  rewriting; to give the guest read access to something you care about,\n  mount a disposable copy.\n\n  A single **file** `source` works as well as a directory: virtio-fs\n  shares directories only, so the launcher wraps the file in a per-entry\n  directory (hard-linking it, so writes still reach the host file) and\n  the guest bind-mounts just that one file onto `path:`.\n  Nothing else from the file's real parent directory reaches the guest.\n  A hard link cannot cross volumes: the wrap directory sits in the run\n  dir, and a file on another volume aborts the launch — mount its\n  directory instead.\n  A caveat a directory mount does not have: the kernel refuses a\n  `rename(2)` onto a file bind mount with `EBUSY`, so a single-file\n  mount takes in-place edits but **not** the write-a-temp-then-rename\n  pattern `git config`, `sed -i` and most editors use. Mount the\n  containing directory when the guest needs to replace the file.\n\n  Every mistake aborts the launch at config load rather than booting a VM\n  without the mount you asked for: a missing `source`\u002F`tag`, a `source`\n  that is not on the host, a **directory** `source` whose path carries a\n  `,`, a `tag` that is reserved\n  (`repo`\u002F`runconfig`\u002F`claudebin`\u002F`claudecreds`), outside\n  `[A-Za-z0-9._-]`, repeated, or unusable in the tag's other roles (see\n  below), a `mode` key, and a `path` that is relative, carries `..`,\n  overlaps one of claude-vm's own guest mountpoints — landing on one,\n  above one (`\u002Fmnt`, `\u002F`) or inside one (`\u002Fmnt\u002Frepo\u002Fsub`) — shadows a\n  guest OS path, or duplicates another entry's. The diagnostic names the\n  entry by its position in the merged boot config — `mounts` is a union\n  list, so that number counts through the global entries before the\n  per-repo ones and need not be the entry's position in either file on\n  its own — and by its path when it has one.\n\n  **A `tag` is not only a tag,** which is why the charset is necessary\n  but not sufficient. The same string is vfkit's `mountTag=`, a bare argv\n  word in the guest's `mount -t virtiofs -o rw \u003Ctag> \u003Cpath>`, a path\n  *component* in `\u002Fmnt\u002F\u003Ctag>` and in both the host and guest directories\n  a single-file mount is staged through, and a `mounts.tsv` field. So a\n  `tag` of `.` or `..` is rejected — it would walk one level up out of\n  each of those trees the entry reaches, and `path:`'s own `..` check\n  never sees a tag-derived mountpoint — and so is a `tag` beginning with\n  `-`, which the guest's `mount` reads as an option rather than as the\n  device.\n  `...`, `a..b` and `a-b` are ordinary names and pass. The `source` side\n  of the same device string is why a **directory** source may not carry a\n  comma: vfkit reads it as the start of another device option. That last\n  rule covers the `mounts` entries only — a *repo* path (or `$HOME`, or\n  `$TMPDIR`) carrying a comma breaks the built-in shares, the EFI store,\n  the disk, the console log or the gvproxy socket the same way and is not\n  checked; the launch fails loudly on the argument rather than booting, and\n  `payload\u002FREADME.md` → *The tag is not just a tag* records why it is left\n  there. The one such path this feature adds — the single-file wrap\n  directory (`$RUN\u002Fmount-wrap`) — is checked: the launcher aborts on a\n  comma there when it wraps a file, naming the run dir. That is an\n  earlier, cause-naming abort rather than a rescue; the other arguments\n  break the same launch anyway.\n\n  Those checks run on a **normalized** `path:`, so a mount cannot dodge\n  them by respelling its mountpoint: repeated slashes, a trailing slash\n  and `.` segments in any position (`\u002F.\u002Fetc`, `\u002Fmnt\u002F.\u002Frepo`, `\u002Fetc\u002F.`,\n  and `\u002F.` for the guest root) are collapsed first, which is why the\n  diagnostic names the collapsed path rather than what you wrote. A `..`\n  segment is the exception, rejected rather than resolved — where it\n  lands depends on the guest's filesystem, which the host cannot read.\n\n  **The guest OS's own paths are protected, by shape.** They are\n  `\u002Fbin \u002Fboot \u002Fdev \u002Fetc \u002Fhome \u002Flib` (and its `\u002Flib32`, `\u002Flib64`,\n  `\u002Flibx32` spellings), `\u002Fproc \u002Froot \u002Frun \u002Fsbin \u002Fsys \u002Ftmp \u002Fusr \u002Fvar` —\n  `CLAUDE_VM_GUEST_SYSTEM_PATHS` in `payload\u002Flib\u002Fconfig.sh` is the one\n  authoritative list. Linux stacks a\n  mount, so landing on one hides the image's own files for the whole\n  session, and the mount phase runs first, so the breakage surfaces later\n  as something unrelated. A **directory** source may not land on, above\n  or inside one of those paths — use `\u002Fmnt\u002F\u003Ctag>` (the default), `\u002Fsrv`\n  or `\u002Fopt`. A single **file** may not land on or above one, and may sit\n  inside only `\u002Froot`, `\u002Fhome` or `\u002Ftmp`, which is what makes\n  `path: \u002Froot\u002F.gitconfig` legal while `path: \u002Fetc\u002Fld.so.preload` is not.\n  The guest checks as well, since only it can see the image: a mountpoint\n  that already exists and is non-empty, or a single-file target that\n  exists at all, is warned about on the boot console and **skipped**\n  rather than mounted over.\n- `claude.version` selects which `claude` binary the host-side verified\n  cache fetches: `stable` (default), `latest`, or a pinned version\n  (`2.1.172`). The host resolves a channel to a concrete version,\n  downloads that version's GPG-signed manifest, verifies the signature\n  against the operator's pinned key, checksum-verifies the binary, caches\n  it keyed on the version, and shares it into the guest, where the image's\n  fstab mounts it `ro`. A failed `gpg --verify` or a checksum mismatch\n  **aborts the launch**. On a warm boot (already cached), the launcher\n  drops `claude.ai` \u002F\n  `downloads.claude.ai` from the guest egress allowlist. See the payload\n  README's \"Verified claude cache\" section for the operator's one-time\n  key-import step.\n- `claude.renderer` selects the in-guest claude's terminal renderer on\n  the interactive console (the vfkit `stdio` byte pipe). Both renderers\n  work over the console — this is a preference, not a workaround:\n  `classic` disables the alternate-screen buffer\n  (`CLAUDE_CODE_DISABLE_ALTERNATE_SCREEN=1`), `fullscreen` forces the\n  flicker-free fullscreen renderer (`CLAUDE_CODE_NO_FLICKER=1`), and\n  leaving it unset passes nothing so claude uses its own default. The\n  launcher writes the matching `CLAUDE_CODE_*` var into `run.env`. An\n  unrecognized value aborts the launch.\n- `claude.remote_control` is an opt-in boolean (default `false`\u002Funset).\n  When `true`, the launcher injects `--remote-control` into the in-guest\n  claude invocation (unless the CLI args already carry it) and, when\n  Remote Control is in effect but no `--name` was given, appends a\n  date-stamped `--name` (format like `Jul10-14:30`). When `false`\u002Funset,\n  claude runs without Remote Control and the CLI args pass through\n  unchanged. Accepts `true`\u002F`false` (or unset); any other value aborts\n  the launch. This is the config-driven equivalent of passing\n  `--remote-control` on the command line — see the interactive-session\n  section below.\n\n`claude.permission_mode`, `claude.permissions.*`,\n`claude.plugins.bake` \u002F `.install_at_boot` (as `enabledPlugins`), and\n`claude.plugins.enabled` are **consumed** by the guest `settings.json` render\n(issue #104) — the launcher renders `\u002Froot\u002F.claude\u002Fsettings.json`\nhost-side and shares it into the guest (see \"Guest Claude settings.json\"\nbelow). (There is no schema translation: the launcher merges the two bake\nfiles into one bake document and the two boot files into one boot document,\nand every reader consumes its tier's document at the file-schema path — a\nkey set per the documented schema is always read.) The bake document's\n`packages:` and `apt_sources:` are **consumed** by the guest-image build\n(issue #105 — see \"Guest image\" below). The boot document's `packages:`,\n`update_at_boot`, and `add_apt_uris_to_allowlist` are **consumed** by the\nguest boot launcher's boot-time apt phase (issue #106 — see \"Boot-time\npackage install\u002Fupdate\" in `payload\u002FREADME.md`). The bake document's\n`claude.marketplaces` + `claude.plugins.bake` are **consumed** by the\nimage build's plugin bake step, and the boot document's\n`claude.plugins.install_at_boot` \u002F `.update_at_boot` \u002F\n`.add_marketplace_uris_to_allowlist` by the guest boot launcher's plugin\nphase (issue #107 — see \"Marketplaces and plugins\" below). The remaining key\n(GitHub token seeding) is schema + merge only as of issue #103 — that consumer\nlands in a sibling slice under #39. It resolves correctly through\n`payload\u002Flib\u002Fconfig.sh` today; nothing downstream reads it yet.\n\n- The bake file's `packages:` (baked into the image) vs. the boot file's\n  `packages:` (installed at boot, blocking, before claude starts, through\n  the proxy) — the containing file's tier is what makes each a build-time\n  bake or a boot-time install (this replaces the old single-file\n  `packages.bake` \u002F `packages.install_at_boot` key split; each tier's\n  merged document keeps its own flat `packages:` list, read as written).\n  Both union global + repo entries. The\n  baked packages are present in the guest with no boot-time network, and\n  the image is cached per whole-file bake hash (see \"Guest image\" below).\n  The boot-install list runs `apt-get -y install \u003Clist>` at boot (issue\n  #106): use it for packages that change often (e.g. the AWS SDK\u002FCLI) so\n  they stay fresh without an image rebuild; a failed install warns loudly\n  and continues to claude rather than blocking the session.\n- The boot file's `update_at_boot` (default `true`) runs `apt-get update\n  && upgrade` at boot, through the proxy, before claude starts (issue\n  #106); a failed update warns loudly and continues. `apt_sources`\n  (allowed in BOTH files; union, deduped by `name`; conflicting content\n  under one name aborts) adds third-party apt repos as\n  `{name, repo, key_url}` entries. A **bake** file's apt_sources are\n  rendered at **image-build** time (issue #105 — baked into the mkosi\n  sandbox tree so baked packages from that repo install at build time). A\n  **boot** file's apt_sources (minus any name already baked) are rendered\n  at **boot** time into the guest's live `\u002Fetc\u002Fapt` whenever the boot\n  `packages:` install list is nonempty (issue #106 — reusing the exact\n  same keyring-fetch + sources.list.d-write shape, ported to plain bash\n  since the guest has no python3\u002Fjq).\n- The boot file's `add_apt_uris_to_allowlist` (`auto` default | `always`)\n  controls whether `deb.debian.org` + `security.debian.org` + every\n  `apt_sources` host are added to the guest's egress allowlist.\n  `auto` adds them only when boot-time package work needs them (the boot\n  `packages:` install list nonempty, or `update_at_boot` true); with\n  neither configured, `auto` derives nothing, leaving package repos\n  unreachable — by design, for a hard-secure all-baked config. `always`\n  adds them\n  unconditionally so in-session `apt-get install` also works. The knob\n  never removes URIs that scheduled boot-time work requires, and every\n  derived addition is logged.\n- **Marketplaces and plugins** (issue #107). `claude.marketplaces` (union of\n  `{name, url}`, allowed in both file types, deduped by `name`, conflicting\n  urls under one name abort, and — since issue #226 — an entry with a url but\n  no `name` aborts too, since the name is what every consumer matches on)\n  declares the marketplaces the guest knows.\n  `claude.plugins.bake` (BAKE file) is installed **into the image** at build\n  time; `claude.plugins.install_at_boot` (BOOT file) is installed **at boot**,\n  blocking, before claude starts.\n  - The bake path runs the host-verified guest `claude` binary inside the\n    build container with `HOME` pointed at the image root and drives its own\n    CLI (`claude plugin marketplace add` \u002F `claude plugin install`) — the\n    registry format is claude's and is never hand-written. A failed\n    add\u002Finstall **fails the build**, so a cached image never silently lacks a\n    configured plugin. That strictness covers what the image must **carry**:\n    every `bake:` ref and every marketplace declared in a bake file. A\n    marketplace declared only in a **boot** file is pre-registered here as an\n    optimization, and its url only has to be reachable from the *guest* — a\n    guest-local path (`\u002Fmnt\u002Frepo`), a private source, or an https host outside\n    the build container's egress. A boot-declared entry warns and leaves the\n    registration to the boot path on each of the paths that fail a\n    bake-declared one: no `url` at all, a failed add, or an add that registers\n    under a name other than the configured one (issue #226).\n  - The boot path ensures any marketplace the image does not already carry,\n    then (when `update_at_boot` is `true`, the default) refreshes the\n    marketplaces and updates the installed plugins, then installs the\n    `install_at_boot` refs. This is the freshness mechanism for **baked**\n    plugins: they are frozen at build time and the image-identity hash\n    deliberately excludes marketplace HEAD, so a marketplace bump lands at\n    the next boot with no rebuild. A failure warns loudly on the captured\n    console log and continues to claude. The guest image bakes `git`\n    unconditionally for this phase: the claude CLI shells out to **system\n    git** for every git-url marketplace operation, so without it the\n    add\u002Fupdate fails (fail-soft) and `update_at_boot` would be inert.\n  - `.add_marketplace_uris_to_allowlist` (`auto` default | `always`) mirrors\n    `add_apt_uris_to_allowlist`: under `auto`, marketplace hosts are added to\n    the guest egress allowlist only when boot-side work can actually run (a\n    nonempty `install_at_boot`, a marketplace declared in the boot file that is\n    not also bake-declared, or `update_at_boot` true with at least one\n    marketplace configured). The middle test reads the *declaration*, not the\n    image: the build's pre-registration of a boot-declared marketplace is\n    best-effort since #226 and the host cannot know whether it succeeded, so\n    the gate derives the host either way.\n    Everything bake-declared + `update_at_boot: false` + `auto` derives\n    **nothing** —\n    and the guest still has working plugins, because the baked ones need no\n    marketplace. Every derived addition is logged. A `owner\u002Frepo` shorthand\n    url yields no derivable host (keep `github.com` in `egress.allow`\n    yourself); the launcher says so rather than guessing.\n  - **Compiled hooks need no toolchain**: the guardrails permission-gate\n    ships prebuilt, committed binaries (one per `\u003Cgoos>-\u003Cgoarch>`, the\n    guest's being `linux-arm64`), so baking `guardrails@…` requires\n    **nothing** in the bake file's `packages:` — in particular no\n    `golang`. A platform with no committed binary makes the hook fail\n    closed (exit 2, tool call denied), never silently unadjudicated.\n- `github.auth` (`none` default | `host-token`) selects whether the\n  guest is seeded with a GitHub auth token derived from the host.\n\n### Guest environment variables (issue #135)\n\n`env:` is how a variable reaches the in-guest `claude` session — a plain\nnon-secret setting (`FOO_ENDPOINT`) or a **third-party API key**\n(`OPENROUTER_API_KEY`, `TAVILY_API_KEY`) for a tool, MCP server or model\nprovider other than Anthropic or GitHub. `github.auth` covers the host's\nGitHub token specifically and nothing else.\n\n**The tier a sub-key may be declared in follows from how its value is\nobtained**, not from operator preference:\n\n| Sub-key | Bake tier | Boot tier | Value source |\n| --------- | ----------- | ----------- | -------------- |\n| `env.set` | yes | yes | explicit literal in the config |\n| `env.copy` | no — hard abort | yes | host environment at launch |\n| `env.files` | no — hard abort | yes | host `.env` file at launch |\n\nA bake file's result is image **bytes** that persist across every run of that\nimage; a boot file's result is shredded on exit. `env.copy`\u002F`env.files`\nresolve against a host environment that does not exist at image-build time,\nand a value read from it is exactly the kind of secret that must never become\nimage bytes — so only explicitly written literals are bakeable. The bake-tier\nabort is a **presence** test: an empty or valueless `env.copy:` aborts too,\nsince ignoring it silently would leave you believing a host variable is\nforwarded into a persistent image.\n\n- `env.set` — a map of name → literal value, for **non-secret** settings only\n  (these values are committed config, and in a bake file they are also image\n  bytes). Merge: repo-over-global per key.\n- `env.copy` — a list of **names**. The launcher reads each from its own\n  environment at launch and forwards the value, so no secret is ever written\n  to config and the config stays committable. Keep supplying values however\n  you already do: shell profile, `direnv`, `op run`. Union merge.\n- `env.files` — a list of host `.env` files whose `NAME=value` lines are\n  parsed at launch and forwarded the same way. Union merge. Blank lines and\n  `#` comments are skipped, a leading `export` is dropped, and a value\n  wrapped in matching quotes is unwrapped; there is no variable expansion and\n  no escape processing.\n\n**Precedence**, lowest to highest:\n\n```text\nbake env.set  \u003C  boot env.files  \u003C  boot env.copy  \u003C  boot env.set\n```\n\nWithin each tier, repo-over-global (per key for `set`, union for\n`copy`\u002F`files`); within `env.files`, a later file wins over an earlier one.\nBoot beats bake throughout: bake is the image's baseline, boot is the\nper-launch override.\n\n**Carrier.** Two, one per tier — `run.env` is neither and stays\nlauncher-owned, deliberately a non-secret channel. Bake `env.set` is written\ninto the image at build time and persists. The **whole boot tier**, including\nthe non-secret `env.set` literals, rides the same transient `claudecreds`\nmount as the OAuth credential and identity seed (0600, mounted `ro`\nguest-side, shredded on exit); the guest **sources** it off that mount and\nnever copies it, so no forwarded value reaches the guest filesystem. One\ncarrier for the whole boot tier means the secret and non-secret boot paths\ncannot diverge.\n\n**Egress is the other half.** Forwarding a key does not make the service\nreachable: the guest is egress-confined, so the provider's host must also be\nin `egress.allow` (`openrouter.ai`, `api.tavily.com`, …) or the proxy blocks\nthe call and the failure is baffling. A variable *name* implies no hostname\nthe way an apt source's URI does, so nothing is derived automatically — there\nis no `add_apt_uris_to_allowlist` analogue. Add the pair together.\n\n**Every mistake aborts the launch**, rather than booting a guest that looks\nfine while lacking a key it was configured to have (which surfaces much later,\ndeep inside a tool call, as an opaque auth error naming nothing): `env.copy`\nor `env.files` in a bake file; an `env.copy` name unset **or empty** on the\nhost; an `env.files` path that is not on the host or does not parse; a name\noutside `[A-Za-z_][A-Za-z0-9_]*` from any source; a non-scalar `env.set`\nvalue, or a key left valueless (write `NAME: \"\"` for the empty string); and a\nname the launcher itself composes — every name in `run.env` (the proxy vars,\n`CLAUDE_ARGS`, the `*_TAG` mount vars, `IS_SANDBOX`, `DISABLE_AUTOUPDATER`,\nthe renderer `CLAUDE_CODE_*` vars, the terminal geometry, the\n`CLAUDE_VM_*_UPDATE_AT_BOOT` flags) plus `CLAUDE_VM_LAST_CLAUDE_STATUS` —\nbecause the guest sources `run.env` *before* both env files, so such an entry\nwould overwrite the launcher's own value (a different proxy, a renamed mount\ntag, a replaced `claude` argv) and break the boot rather than configure\nanything. `CLAUDE_VM_LAST_CLAUDE_STATUS` is the exception in the other\ndirection — the launcher exports it long *after* both files, so a config entry\nfor it would be silently overwritten instead — and refusing at load covers\nboth. The abort message lists the whole reserved set. No diagnostic ever\nprints a value.\n\n**Rebuilds.** No new trigger is needed: the image identity is already a\nwhole-file, raw-byte hash of the bake files, so changing a baked `env.set`\nvalue invalidates the cached image and the next launch rebuilds. Editing a\nboot file never rebuilds.\n\n### Guest Claude settings.json (issue #104)\n\nThe launcher renders the guest's `\u002Froot\u002F.claude\u002Fsettings.json`\nhost-side from the merged config and shares it into the guest over the\nexisting transient `claudecreds` mount (the same one the OAuth\ncredential and identity seed ride). The guest boot launcher installs it\nat `$HOME\u002F.claude\u002Fsettings.json`. The guest's **permission** and **plugin**\nsurface — everything the rendered file carries — is derived from the claude-vm\nconfigs **only**: the host's `~\u002F.claude\u002Fsettings.json` and the host's own\ninstalled plugins are never read, so the guest deliberately runs its own\n(possibly riskier) posture. (The host's `~\u002F.claude` *working rules* — the\nnon-policy layer of `CLAUDE.md`, `rules\u002F`, `agents\u002F`, `skills\u002F` and\n`keybindings.json` — **are** seeded in; see *Host working rules seeded into\nthe guest* below.) The rendered keys:\n\n- `permissions.allow` \u002F `.ask` \u002F `.deny` come verbatim from\n  `claude.permissions.*` (each a unioned list).\n- `permissions.defaultMode` comes from `claude.permission_mode`\n  (`bypassPermissions` default | `default`). Only those two values are\n  accepted — any other aborts the launch (it is a security-posture value\n  with no defined behavior for an unknown mode). YOLO-by-default: the VM is\n  the isolation boundary, so `bypassPermissions` is the default with the\n  deny list as backstop. The guest runs claude as **root**, which claude\n  refuses in `bypassPermissions` unless `IS_SANDBOX=1`; the launcher sets\n  `IS_SANDBOX=1` unconditionally in `run.env` (the guest *is* the\n  sandbox).\n- `enabledPlugins` maps every ref in\n  `claude.plugins.bake ++ claude.plugins.install_at_boot` to `true`\n  (de-duplicated), then the optional `claude.plugins.enabled` map\n  overrides those defaults per key. `enabled` mirrors `settings.json`'s\n  own `enabledPlugins` vocabulary (plugin ref → boolean): `false` marks a\n  plugin **installed-but-disabled** (re-enabling needs no reinstall — handy\n  for toggling debug plugins like `show-loaded-rules` \u002F `show-loaded-skills`\n  around a specific issue). The map is validated **once**: every value must\n  be boolean and every key must name an installed ref — an unknown key is a\n  typo and **aborts the launch**.\n- `extraKnownMarketplaces` maps every configured marketplace name (the\n  effective bake ++ boot set) to its source, in the shape claude itself\n  writes: an `https:\u002F\u002F` url renders as `{\"source\":\"git\",\"url\":…}`, an\n  `owner\u002Frepo` shorthand as `{\"source\":\"github\",\"repo\":…}`. This key is\n  rendered because `claude plugin install` was observed writing it into\n  `~\u002F.claude\u002Fsettings.json` alongside `enabledPlugins` — and the boot\n  launcher copies the host-rendered file over whatever the image baked, so\n  omitting it would drop the marketplace declarations the bake step's own\n  CLI run wrote. Rendering it from the same effective set the bake and boot\n  paths use keeps the three from drifting. It does **not** make claude\n  self-install a missing plugin (tested directly: a home dir with only this\n  settings.json and no `~\u002F.claude\u002Fplugins` tree installs nothing), which is\n  why the guest's explicit ensure\u002Finstall\u002Fupdate phase is load-bearing.\n\nclaude-vm has **no** own CLI flags: every post-repo argument is forwarded\nto the guest `claude` verbatim. Plugin enable\u002Fdisable state is set through\n`claude.plugins.enabled` in the config files, not on the command line.\n\n### Host working rules seeded into the guest (issue #108)\n\nThe section above is the **policy** layer, which the guest gets from the\nclaude-vm config rather than from the host. The operator's **\"who I am \u002F\nhow I work\"** layer goes the other way — it follows them into the VM. The\nlauncher stages copies of the host's `~\u002F.claude\u002FCLAUDE.md`, `rules\u002F`,\n`agents\u002F`, `skills\u002F` and `keybindings.json` onto the same transient\n`claudecreds` mount the credential, identity seed and rendered\n`settings.json` ride, and the boot launcher copies them **additively** into\nthe guest's `~\u002F.claude\u002F`: a directory is merged into whatever is already at\nthat path (the image's baked `plugins\u002F` is untouched) and a same-named file\nis overwritten. `CLAUDE.md` and `rules\u002F` travel together because the former\nreferences the latter as `@~\u002F.claude\u002Frules\u002F*.md`.\n\nThere is **no config key** for this — the list is fixed in the launcher and\nspelled again in the boot launcher it emits, so adding an entry is a\ndeliberate edit on both sides of the seam. And it is an **include list**: a\nhost `~\u002F.claude` accumulates directories claude-vm has never heard of, and\nan exclude list would leak every future one by default. Nothing else is\ncopied. Not the policy layer\n(`settings.json` is rendered, plugin state is config-driven), and not\nhost-scoped session state — `projects\u002F` (keyed by host paths the guest does\nnot have), `history.jsonl`, `todos\u002F`, `sessions\u002F`, `logs\u002F`, `statsig\u002F`,\n`shell-snapshots\u002F`, `ide\u002F`, `teams\u002F`, `usage-data\u002F`.\n\nYour host files are never touched: what the guest sees is a copy, staged\nunder `umask 077` in the run's shred-on-exit credential dir. Symlinks are\n**dereferenced**, so a `~\u002F.claude` that is a checkout with `rules\u002F` or\n`skills\u002F` symlinked out of it still seeds real content rather than a\ndangling link. Every entry is optional — a host with no `keybindings.json`\nand no global `CLAUDE.md` launches normally and silently. A copy that\n*fails* prints a warning from the side that attempted it — on the launcher's\nstderr when the host cannot stage the entry (which then never reaches the\nguest at all), in the guest's `hvc0` diagnostic log when the guest cannot\ninstall it — and the launch continues: unlike the credential and\n`settings.json`, no copy failure in this layer aborts a boot. The guest half\ntherefore guards **every** command it runs on an entry, its `mkdir -p` as\nmuch as its copies, since the boot launcher runs under `set -euo pipefail`.\n\nA failed entry is also **dropped**, not left half-copied: `cp -R` keeps going\npast a per-file error, and a partial `rules\u002F` tree is worse than an absent\none. The guest can only drop what this seed created, so a destination that\nalready existed in the image is left alone — with a warning that it may now\nhold a partial copy — rather than having baked content deleted under it.\n\n## Interactive session (the launching terminal IS the in-VM claude)\n\n`claude-vm \u003Crepo>` opens an **interactive** Claude Code session on the\nlaunching terminal — the terminal becomes the guest's `hvc1` console and\nyou drive the full REPL inside the micro-VM (detached clone + egress\nproxy). This is the product goal; headless one-shot is not. Pass\n`--remote-control --name \u003Cn>` straight through (`claude-vm \u003Crepo>\n--remote-control --name foo`) and the same session is *also*\nRemote-Control-attached for AFK observation\u002Freplies — those flags reach\nthe in-guest claude via the existing `CLAUDE_ARGS` plumbing; no extra\ntransport is involved.\n\nWays to turn on Remote Control:\n\n- **Per-launch, via CLI** — pass `--remote-control` (and optionally\n  `--name \u003Cn>`) after the repo path, as above.\n- **Opt-in by config** — set `claude.remote_control: true` in the global\n  or per-repo config. The launcher then injects `--remote-control` for\n  you (without duplicating it if you also pass it on the CLI). Either way,\n  if Remote Control is in effect but you gave no `--name`, the launcher\n  appends a date-stamped `--name` (format like `Jul10-14:30`) so the run\n  is named — matching the date-stamp default this skill documents. A\n  user-supplied `--name` (in either `--name \u003Cv>` or `--name=\u003Cv>` form) is\n  never overridden. Arbitrary CLI args survive verbatim: the launcher\n  quotes `CLAUDE_ARGS` per-argument into `run.env` and the guest boot\n  launcher reconstructs the exact argv, so a value like\n  `--name \"foo #7 micro-vm\"` (with spaces and a `#`) round-trips intact.\n\nTopology: vfkit attaches **two** virtio-serial consoles. The first\n(`logFilePath`, guest `hvc0`) captures all kernel\u002Fsystemd boot output to\n`$CLAUDE_VM_STATE_DIR\u002Flogs\u002F\u003Crun-id>\u002Fguest-console.log` (preserving the\nobservability from the guest-console capture); the second (`stdio`,\nguest `hvc1`) bridges the launching terminal. The guest runs claude as\nthe login program of an autologin `serial-getty@hvc1`, so claude *is*\nthe session with no shell in between. Boot diagnostics stay on `hvc0`\n(off your terminal).\n\nBecause the `stdio` console is a byte pipe that needs a real controlling\nTTY on the host, **launch `claude-vm` from a real terminal**, not from a\npipe. The console carries no live window-resize channel, so the launcher\nseeds the guest tty geometry once from the host's `stty size` at launch;\nthere is no live resize.\n\n## Repo mount strategy (`repo.mount`)\n\nHow the repo is made available RW to the guest:\n\n- **`clone` (default)**: `git clone --no-hardlinks` the repo into a\n  **persistent** worktree, mounted RW. The guest never touches the live\n  working tree or `.git`. The worktree lives under\n  `$CLAUDE_VM_RUNS_DIR\u002F\u003Crunid>\u002Fworktree` — the runs root, `runs\u002F`\n  under the state root `lib\u002Fconfig.sh` resolves — whether or not the\n  argument is a git repo. It persists after the run so the companion\n  diff\u002Fapply skills can inspect and extract results; they find this\n  repo's runs by the `repo_src` line of each run's `run.meta`.\n- **`live`**: mount the live repo dir RW directly. More convenient,\n  less isolated. Opt-in.\n\n### Getting work back out (clone mode)\n\nAfter the guest exits, the launcher runs **copy-back to the local\nsource by default** (`repo.copy_back: local`). Set\n`repo.copy_back: none` to disable it and extract manually. The three\ncompanion skills handle extraction explicitly:\n\n- `\u002Fclaude-vm-diff` — read-only: show what changed in the VM worktree\n  vs. the local source.\n- `\u002Fclaude-vm-apply-local` — apply the VM worktree's changes to the\n  local source.\n- `\u002Fclaude-vm-apply-remote` — push the VM worktree's changes to the\n  remote.\n\n### Reaping a run whose launcher has exited\n\nA launcher killed with `kill -9` (or a crash, or a closed terminal)\nnever runs its exit trap, and its run dir keeps its guest-image clone.\nEach launcher holds a `lockf` lock on `$RUN\u002Frun.lock` for its lifetime,\nand no process it leaves running holds it, so a dead launcher is a\ndead run. A watcher the launcher starts beside vfkit waits on that\nlock and, the moment the launcher dies, stops vfkit, gvproxy and the\nproxy — so a `kill -9` of the launcher stops the VM too. The watcher\nsignals those three pids, and the launcher's own exit trap the\ngvproxy, proxy and watcher pids, only while each still carries the\nstart time recorded for it at launch.\n`bin\u002Fclaude-vm-cleanup`, run by hand, reaps the rest for every repo at\nonce: it reaps only a run whose lock it can take, whether that run\nexited normally or crashed — killing the pids its `run.meta` records\n(`vfkit_pid`, `gvproxy_pid`, `proxy_pid`, a backstop for a watcher that\nwas killed as well) while each still carries the start time recorded\nbeside it, so a pid since taken by another process is never signalled,\nand removing its gvproxy socket dir, its `creds\u002F` dir (the OAuth\ncredential and identity seed), any raw Keychain blob\n(`.keychain-blob.raw.json`) and its `guest-clone.raw` — and leaves\nevery live run alone. It keeps the run\ndir, `worktree\u002F`, `run.meta` and `run.lock` included, so the companion skills still\nfind the run, and it never removes `$CLAUDE_VM_STATE_DIR\u002Flogs\u002F`, where\neach run's console, gvproxy and proxy logs and egress capture are kept.\nIt reports each run it reaped, with its log dir and kept worktree, or\nspared.\n\n## Guest image — built on demand, version-pinned, claude verified host-side\n\nClaude Code updates daily, so the guest image does **not** bake in\n`claude`:\n\n- The baked image is a **stable base**: a pinned OS plus a boot launcher\n  that, on boot, loads the run environment and then runs the\n  **host-side GPG-verified `claude` binary** mounted RO at\n  `\u002Fmnt\u002Fclaudebin` against the repo at `\u002Fmnt\u002Frepo`, as an interactive\n  session on the `hvc1` console (issue #88). `claude` is never\n  baked in and never fetched-and-run inside the guest (no\n  `curl install.sh | bash` anywhere — there is no such fallback); the\n  host fetches, verifies, and caches it (see \"Verified claude cache\" in\n  the payload README). The base only changes when the base OS pin or the\n  launcher logic changes — not when claude does.\n- The base is **version-pinned** in `payload\u002Fbuild-guest-image.sh`\n  (`BASE_OS_REV` + `LAUNCHER_LOGIC_REV`; never the claude version).\n- **Baked packages (issue #105, re-keyed by #179).** A **bake** file's\n  `packages:` and `apt_sources:` ARE baked into the image (unlike\n  `claude`): the baked packages are present in the guest with no\n  boot-time network, and each `apt_sources` repo's `key_url` is fetched\n  into a keyring so its packages install (`signed-by` that key) at build\n  time. An `apt_sources` entry's `repo` may already carry its own apt\n  one-line `[options]` block (e.g. an operator-authored `signed-by=`);\n  the renderer adapts to the line's existing shape instead of\n  unconditionally appending a second `[options]` block (apt allows only\n  one, and two make the line unparseable) — no block gets one added, a\n  block without `signed-by=` gets it merged in, and a block that already\n  pins `signed-by=\u003Cpath>` is left verbatim with the fetched key written\n  to that path's staging equivalent. Baked `packages:` entries that are\n  null\u002Fempty (e.g. a stray `-` in the YAML list) are stripped during the\n  build render rather than baked in as a literal `\"None\"` package name.\n- **Immutable base + whole-file image identity (issue #179).** The image\n  cache key + filename is a **whole-file, raw-byte hash of the BAKE\n  files** — no key-picking, no canonicalization. Placement of a key in a\n  bake file IS the classification, made once by the operator: a knob in\n  the wrong file loudly does nothing instead of silently poisoning the\n  cache. Because the hash is over raw bytes, list order, key order,\n  whitespace, and even a **trailing-newline toggle** all change it — the\n  trailing-newline toggle is the documented force-rebuild lever. The\n  shape:\n  - a repo **without** a `.claude-vm\u002Fconfig-bake.yml` shares one image\n    keyed on the GLOBAL bake file's hash: `guest+global\u003Chash>.raw`,\n    version `BASE_OS_REV+launcherN+global\u003Chash>` (an absent global bake\n    file hashes to the `00000000` sentinel);\n  - a repo that **ships** a `.claude-vm\u002Fconfig-bake.yml` appends its own\n    segment — the repo NAME plus a hash of the repo bake file —\n    `guest+global\u003Chash>+\u003Creponame>-\u003Crepohash>.raw`, so the filename tells\n    you whose override runs where. The repo segment's PRESENCE is gated\n    on the bake FILE existing (not its content), so two repos with\n    byte-identical repo-bake files still get two images (the name\n    disambiguates): legibility over dedup, an explicit choice.\n\n  Editing a **boot** file never changes identity and never rebuilds;\n  editing a **bake** file (including only its trailing newline) does. The\n  `guest_image` scalar, when set, opts out of identity derivation and is\n  used verbatim.\n\n  The cached base `.raw` is **immutable** and is NEVER attached to a VM:\n  each run APFS-clones it (`cp -c`, instant zero-copy) into the run dir\n  and boots the CLONE. N concurrent sessions cost one base plus each\n  session's written blocks — no cross-session\u002Fcross-repo state leakage\n  (OAuth credential, identity seed, transcripts, boot-installed packages)\n  and no multi-writer corruption on a shared image. The clone is\n  discarded on a clean exit and retained (path logged) on an abnormal one\n  for forensics. There is no host-driven forced stop: the guest halts\n  itself and vfkit (running foreground) exits on its own, so the\n  launcher's `sync` in cleanup simply narrows the window in which writes\n  in flight to the clone are still unflushed when the guest goes away.\n- **Ending a session (issue #179).** The guest decides its own fate from\n  claude's exit status; there is no host→guest shutdown channel.\n  - **A deliberate quit powers the guest off.** `Ctrl-D Ctrl-D`, `\u002Fexit`,\n    and `Ctrl-C Ctrl-C` all exit claude 0, and on 0 the guest starts\n    systemd's ordered poweroff (SIGRTMIN+4 to PID 1 — the bus-less path,\n    so no spurious \"Failed to connect to bus\" error on a guest that ships\n    no dbus). vfkit then exits on its own, control returns to\n    the `claude-vm` launcher on the host, your terminal is restored, the\n    per-run clone is discarded, and the copy-back step runs. This is the\n    normal way to end a session — nothing on the host needs to be killed.\n  - **Ctrl-C belongs to the guest claude.** The launcher disables\n    `isig`\u002F`ixon` on the host tty for the session, so `Ctrl-C` (and\n    `Ctrl-Z`\u002F`Ctrl-\\`\u002F`Ctrl-S`\u002F`Ctrl-Q`) travel to the guest as bytes\n    instead of signalling host-side vfkit — the first `Ctrl-C` shows\n    claude's press-again warning, the second exits 0 and powers off, same\n    as `Ctrl-D Ctrl-D`. Consequence: the keyboard cannot abort a *wedged*\n    guest from that terminal; the recovery path is `kill \u003Cvfkit pid>`\n    from another terminal (vfkit tears the guest down within ~5s and the\n    launcher cleans up normally). The saved tty state is restored on\n    every exit path.\n  - **An abnormal claude death drops you into a guest shell.** If claude\n    exits nonzero (a crash, an OOM kill, or declining the\n    bypass-permissions dialog — the easy way to try this path), the guest\n    does **not** power off yet. The boot launcher hands you an\n    interactive **root login shell on the same console you were already\n    attached to**, so you can run a post-mortem inside the still-running\n    guest: inspect `\u002Fmnt\u002Frepo`, see how the clone diverged, read `dmesg`,\n    check whether the network wiring survived. claude is **not**\n    relaunched — there is no respawn loop. **Exiting that shell powers\n    the guest off** and returns control to the host launcher; the clone\n    is retained (its path is logged) for further forensics.\n- **Boot-time package install\u002Fupdate (issue #106).** A **boot** file's\n  `packages:` (install list) and `update_at_boot` do **not** feed the\n  image-identity hash — they\n  run a blocking phase in the boot launcher itself, right before claude launches,\n  through the same proxy the rest of the guest's egress goes through. The\n  base image DOES need one thing unconditionally to support this phase: `apt`\n  itself, baked into the base `Packages=` list regardless of whether\n  install_at_boot\u002Fupdate_at_boot are configured (mkosi does not otherwise put\n  apt\u002Fdpkg tooling into the guest rootfs, since it installs baked packages\n  from OUTSIDE the image with its own build-container apt) — this is covered\n  by `LAUNCHER_LOGIC_REV`, the base-version pin, not by the image-identity\n  hash. See \"Boot-time package\n  install\u002Fupdate\" and \"Mid-session apt proxying, metadata diet, and root\n  headroom\" in `payload\u002FREADME.md` for the full mechanics (the reused\n  `render_apt_source` shape, the proxy `-o Acquire::*::Proxy=` flags and\n  persistent `apt.conf.d` drop-in, the apt metadata diet, `apt-get clean`,\n  the failure policy, and the `add_apt_uris_to_allowlist` derived-egress\n  gate).\n- On startup, the launcher **ensures the image exists and matches the\n  pinned version**. If the resolved image is missing or version-mismatched,\n  it builds the image (`payload\u002Fbuild-guest-image.sh --output …`, passing the\n  merged bake config through `CLAUDE_VM_BAKE_CONFIG` and the pre-computed\n  image-identity segments through `CLAUDE_VM_IMAGE_IDENTITY_SEGMENTS`) rather\n  than erroring.\n  The image's pinned version is stamped at `\u003Cimage>.version`.\n- **No image artifact is committed to the repo**, and there is no\n  publish-prebuilt-image path. Every machine builds its own.\n\nThe provisioning step that produces the bootable raw image defaults to\nthe bundled `payload\u002Fprovisioners\u002Fpodman-mkosi.sh`: mkosi run inside a\nthrowaway rootless podman container (Debian Trixie build container,\nsystemd ≥ 254 for the offline, loop-device-free `RepartOffline=yes`\npath), emitting a raw EFI-bootable Debian guest with the boot launcher\nwired as the autologin `serial-getty@hvc1` login program (so claude\nbecomes the interactive `hvc1` console session — issue #88), plus an\nunlocked passwordless root (`RootPassword=hashed:`). vfkit boots it\n`--bootloader efi`. `build-guest-image.sh` pins the version and emits the\nboot launcher, then hands `\u003Cboot-launcher-path> \u003Coutput-image-path>` to\nthe provisioner. The `CLAUDE_VM_IMAGE_PROVISIONER` env var overrides the\nbundled default with your own script honoring the same two-argument\ncontract.\n\nThe launcher captures the booting guest's **boot** serial console\n(`hvc0`) to `$CLAUDE_VM_STATE_DIR\u002Flogs\u002F\u003Crun-id>\u002Fguest-console.log` via\nthe first vfkit `--device\nvirtio-serial,logFilePath=…`. The recipe `KernelCommandLine` sets\n`console=hvc0`, so all kernel\u002Fsystemd boot output — and the boot\nlauncher's diagnostic\u002Fseam lines, which it writes explicitly to\n`\u002Fdev\u002Fconsole` — are observable from the host instead of being\ndiscarded, while staying off the interactive `hvc1` terminal. The path\nis reported on exit and retained in the run's log dir, beside the\ngvproxy and proxy logs and the egress capture, where reaping the run\ndoes not reach it.\n\n## Authentication (secrets)\n\nThis section covers the two credentials the launcher handles itself: the\nhost's claude.ai OAuth credential, and (under `github.auth: host-token`) a\nGitHub token. Any **other** third-party key — an OpenRouter or Tavily key for\nan in-guest tool, MCP server or model provider — reaches the guest through\n`env.copy` \u002F `env.files` instead; see *Guest environment variables* above,\nwhich carries the same \"never in config, never in `run.env`, shredded on\nexit\" posture.\n\nThe guest authenticates claude with the **host operator's live claude.ai\nOAuth credential** — the full-scope login credential, not a scoped\ninference token — installed at `$HOME\u002F.claude\u002F.credentials.json`. That\nbearer token alone is **not** sufficient for the interactive TUI to treat\nitself as onboarded and logged in: current Claude Code also reads\nonboarding + identity state from `~\u002F.claude.json`, which a fresh throwaway\nguest lacks — so without it every launch hits the onboarding\u002Flogin wall\ndespite the mounted credential. Two keys matter beyond identity:\n`hasCompletedOnboarding` (absent → claude runs its onboarding flow) and\n`autoUpdates` (unset → claude tries to self-update and fails against its\nRO-mounted binary in the egress-confined guest).\n\nSo the launcher **also seeds the guest's identity + onboarding state**\n(issue #88): it reads your host `~\u002F.claude.json` and emits a seed carrying\n`userID` and `oauthAccount` selected from the host, plus four synthesized\nkeys: `hasCompletedOnboarding: true` (skip the wall), `autoUpdates: false`\n(no self-update), and `lastOnboardingVersion` \u002F `lastReleaseNotesSeen`\nstamped with the concrete resolved claude version. It **additively**\ncarries benign host UI keys when present — `installMethod`,\n`hasSeenTasksHint`, `hasUsedStash`, `tipsHistory` (each silently omitted\nwhen absent) — and seeds a **`projects` entry for the guest mount**\n(`\u002Fmnt\u002Frepo`) with `hasTrustDialogAccepted` \u002F `hasCompletedProjectOnboarding`\nforced `true` so the guest skips the \"Do you trust this folder? \u002Fmnt\u002Frepo\"\ndialog (if the host already has an entry for the launched repo, a **named\nallowlist** of benign per-project keys — `allowedTools` and friends —\nsurvives, rekeyed to `\u002Fmnt\u002Frepo` with those two flags forced true; the\noperator's prompt `history`, `lastSessionId`, and `mcpServers` are\ndeliberately dropped, and unrecognized future keys default to excluded).\nNothing else from `~\u002F.claude.json` (no other `projects{}` entries, no\ntelemetry, no `machineID`) is copied;\n`machineID` is deliberately **not** seeded — the guest mints its own. That\nobject is shared into the guest under the same `claudecreds` mount, and\nthe guest boot launcher installs it at `$HOME\u002F.claude.json` (mode `0600`)\nbefore launching `claude`, so the in-guest session comes up already\nonboarded, logged in, folder-trusted, and with self-update disabled. The\nseed is built via `lib\u002Fcredential.sh`'s `claude_vm_select_claude_json_seed`\n(using `python3`; unit-tested in `payload\u002Ftest\u002Fcredential-test.sh`) and\ncarries account identity, so it rides the same secret posture as the\ncredential: written under `umask 077` into the transient, owner-only\n(`0600`), shred-on-exit `claudecreds` mount, **never** into `run.env` or the\nverified-binary cache. A **preflight** aborts the run with an actionable\nmessage if the host `~\u002F.claude.json` is missing or lacks a usable\n`userID`\u002F`oauthAccount` (i.e. you are not logged in on the host).\n\nThe launcher also quiets claude's startup **install-health check**\n(issue #88): claude probes for a working `claude` at the native installer's\n`~\u002F.local\u002Fbin\u002Fclaude`, but the guest runs the RO-mounted binary from\n`\u002Fmnt\u002Fclaudebin`, so that path is empty and the TUI prints two `claude\ncommand at \u002Froot\u002F.local\u002Fbin\u002Fclaude missing or broken · run claude install to\nrepair` warnings. The guest boot launcher symlinks `$HOME\u002F.local\u002Fbin\u002Fclaude`\n→ the verified RO-mounted binary right after the claude-fetch seam validates\nit; the symlink target is the running binary, so the version comparison\npasses by construction and `autoUpdates: false` plus the RO mount prevent\nwrite-through (empirically confirmed to clear the warnings on real hardware).\nBelt-and-braces with the seeded `autoUpdates: false`, the launcher also\nwrites the documented `DISABLE_AUTOUPDATER=1` env knob into `run.env`.\n\nA second **credential-token preflight** guards against a degraded Keychain\nentry: the `claudeAiOauth` object can be structurally complete yet carry\n**empty** `accessToken` \u002F `refreshToken` strings (with `expiresAt: 0`) —\nwhich happens when your host claude sessions coast on the shared auth\ndaemon's in-memory tokens while the persisted Keychain entry has gone\nstale. Booting the guest with it lands at \"Not logged in · Run \u002Flogin\",\nand an in-guest `\u002Flogin` can trip OAuth reuse-detection and **revoke your\nother live sessions**. So after selecting the credential, the launcher\nvalidates both tokens are non-empty\n(`claude_vm_validate_claude_credential_tokens`) and aborts fast if not,\ntelling you to re-login on the **host** (`claude` then `\u002Flogin`, or restart\nClaude Code — either repairs the Keychain entry) rather than inside the\nguest.\n\nAt launch the launcher reads the credential from the macOS login\nKeychain by service name alone\n(`security find-generic-password -s \"Claude Code-credentials\" -w`).\nThat Keychain item is **not** only the claude.ai login — its JSON also\ncarries sibling keys such as `mcpOAuth` (per-MCP-server OAuth). To avoid\nmounting unrelated MCP credentials into the guest, the launcher **selects\nonly the `claudeAiOauth` key** and writes a file in the shape `claude`\nexpects, `{\"claudeAiOauth\": { ... }}` (selection via `lib\u002Fcredential.sh`,\nusing `python3`; unit-tested in `payload\u002Ftest\u002Fcredential-test.sh`). The\nselected credential is written to a transient, owner-only (`0600`)\ntmpfile and shared into the guest under `mountTag=claudecreds`, **which the\nimage's fstab mounts `ro`**. The `ro` is guest-side, not host-side — vfkit's\nvirtio-fs device has no read-only export, so the host shares this exactly as\nit shares an extra mount, and the same caveat applies: a guest-side `ro`\nstops an accidental write, not a determined one, since the guest session is\nroot. Nothing rests on it — the guest boot launcher copies the file into\n`$HOME\u002F.claude\u002F.credentials.json` (mode `0600`) before launching\n`claude`.\n\nThe credential is a secret and is handled like one: it is **never**\nwritten to config, to `run.env`, or to the verified-binary cache; its\nhost-side tmpfile is created under a tightened `umask 077` and removed\nby the launcher's `cleanup()`\u002F`trap` on every exit. The full raw\nKeychain blob (before selection) lives only in a transient tmpfile\noutside the guest share and is removed immediately after selection.\n\n**Requirements:** macOS only (`security find-generic-password` is a\nmacOS Keychain tool; `python3`, used for credential and identity-seed\nselection, ships with macOS), and you must be logged in to Claude Code\non the host first. The launcher fails fast with an actionable message if\nthe host `~\u002F.claude.json` is missing or lacks a usable\n`userID`\u002F`oauthAccount`, or if the Keychain lookup returns empty or\nnon-zero, or the blob has no usable `claudeAiOauth` key. `egress.allow`\nmust include\nthe Anthropic API host (`api.anthropic.com`) so the in-guest `claude`\ncan reach it. See the payload README's \"Authentication\" section for the\nfull mechanic.\n\n## Requirements\n\n`yq` (mikefarah v4+), `git`, `python3` (stock on macOS; used to select\nthe `claudeAiOauth` key from the Keychain blob — see \"Authentication\"\nabove), `gpg` (`brew install gnupg`, for the host-side verified claude\ncache — see \"Verified claude cache\" in the payload README), a sha256\ntool (`shasum` \u002F `sha256sum`, both stock on macOS\u002FLinux), and — for an\nactual VM boot — `vfkit` and `tinyproxy` (for the bundled default\n`proxy.cmd`). A launch that has to **build** the guest image is the only\none that runs `podman`, for the bundled podman-mkosi provisioner; the\npodman *formula* is in practice a requirement of every launch regardless,\nbecause that is where `gvproxy` normally comes from (next paragraph). What\na build does\n**not** need is a started podman machine: the launcher inits and starts\none itself and stops it again at end of run if it was the one that\nstarted it (see \"The launcher manages the podman machine\" below). On a\nclean host:\n`brew install yq git gnupg vfkit podman tinyproxy`.\n\n`gvproxy` is **not** a separate install and need not be on PATH: it\nships inside the podman Homebrew formula at\n`\u003Cbrew-prefix>\u002Flibexec\u002Fpodman\u002Fgvproxy` and a stock `brew install podman`\ndoes not symlink it onto PATH. The launcher resolves it automatically\n(an explicit on-PATH `gvproxy` first, then podman's libexec), so\ninstalling podman is enough.\n\nBefore any image build, network call, or Keychain read, the launcher\nruns a **trust-path preflight** that checks the local, instant\npreconditions for the verified cache and credential selection up front:\n`gpg` on PATH, the `claude.signing_key_fingerprint` pinned in config,\nthat pinned fingerprint actually present in the gpg keyring, and\n`python3` on PATH. Immediately after, a separate **identity-seed\npreflight** aborts if the host `~\u002F.claude.json` is missing or lacks a\nusable `userID`\u002F`oauthAccount` (i.e. you are not logged in on the host).\nLater, once the credential is selected, a **credential-token check**\naborts if the selected `claudeAiOauth` carries empty `accessToken` \u002F\n`refreshToken` (the degraded-Keychain state described under\n\"Authentication\"), steering you to re-login on the host.\nEach failed check prints the exact remediation\ncommand(s) (e.g. `brew install gnupg`, the\n`curl … | gpg --import` + `gpg --fingerprint` pin steps). Without this\ngate, a cold boot would otherwise pay for a guest-image build and three\nnetwork fetches before aborting on a condition that was knowable at\nstartup. These are an additive early gate; the deep checks in the\nverified cache (gpg-on-PATH and unset-pin hard-abort) and credential\nselection (`python3`) remain as defense-in-depth.\n\nAfter the trust-path preflight, and still before any build\u002Fboot work,\nthe launcher runs a **dependency preflight** that checks the VM\ntoolchain up front (gvproxy resolvable, `vfkit` on PATH, and — only when\nthe bundled default proxy is in use — `tinyproxy`). It fails fast with\none actionable remediation line per missing piece rather than dying deep\nin the boot sequence. A custom `proxy.cmd` owns its own dependencies, so\nthe `tinyproxy` check is skipped then.\n\nThe config-resolution half (layering, scalar\u002Flist resolution) is\nexercisable without the virtualization stack; see\n`payload\u002Ftest\u002Fconfig-test.sh`, and the verified-cache logic (resolve \u002F\nverify \u002F checksum \u002F abort \u002F warm-boot) in\n`payload\u002Ftest\u002Fclaude-cache-test.sh`.\n\nThe per-run endpoint primitives (issue #179) are also exercisable\nwithout a VM: `payload\u002Ftest\u002Fendpoint-test.sh` covers free-TCP-port\nacquisition and TCP\u002Funix-socket liveness (a live listener vs a stale\nsocket-file corpse, the exact distinction the concurrency fix turns on),\nusing real `perl` listeners; `payload\u002Ftest\u002Fbin-config-check-test.sh`\nregression-tests `bin\u002Fclaude-vm`'s four-file bake\u002Fboot config-presence\ncheck so it no longer prints a false \"no global config\" when the\nmigrated pair is present. `payload\u002Ftest\u002Fcleanup-test.sh` covers the\nrun's `run.lock` across a `kill -9` of the launcher, the watcher\nstopping a vfkit stand-in after one, and `bin\u002Fclaude-vm-cleanup` over\ndead, live and lockless run dirs.\n\n`payload\u002Ftest\u002Fpodman-mkosi-test.sh` regression-tests the recipe the\ndefault provisioner generates (the literal `mkosi.conf` and\n`build-in-container.sh`), stubbing only `podman` at the container\nhandoff — added after a real end-to-end build caught failures (a\nbacktick-command-substitution bug corrupting `mkosi.conf`, and a missing\n`curl`\u002F`ca-certificates` in the build container) that no pure-function\n`config-test.sh` case could catch, since none of them render or execute\nthe actual generated recipe files.\n\nThe end-to-end acceptance test — default-provisioner build, vfkit boot\nto the claude-fetch seam (running the host-verified claude off the\nmount), egress confinement, and the host-side GPG-verified cache — is\n`payload\u002Ftest\u002Fhost-acceptance.sh`; it is host-gated by cause: it skips\ncleanly when a required binary is absent,\nbut a stopped or absent podman machine is not a skip — the test starts\nthe machine itself and tears down exactly what it changed on exit. A\nbring-up the test attempted that then fails (`podman machine\ninit`\u002F`start`) is a real failure, not a skip: the test exits non-zero\nrather than green-exiting with nothing proven. Diagnostics (including\nthe machine init\u002Fstart stderr) are retained under\n`$CLAUDE_VM_STATE_DIR\u002Flogs\u002F\u003Crun-id>\u002F` — the state root `lib\u002Fconfig.sh`\nresolves, `~\u002F.local\u002Fstate\u002Fclaude-vm` by default — so a failed run stays\ndiagnosable.\n\n`payload\u002Ftest\u002Fpodman-machine-test.sh` covers the launcher's own podman\nmachine management (issue #215) against a stateful stub podman, and — by\nslicing the build-or-reuse block out of `claude-vm.sh` and running it —\nthe scoping: a warm-cache launch invokes podman zero times, a\nbuild-needing one inits\u002Fstarts, builds, and stops again — including when\nthe bring-up leaves a machine up behind a failure, whether `podman\nmachine start` itself exits non-zero after bringing it up or the\nconfirmation that follows fails.\n\n## The launcher manages the podman machine\n\nThe dependency preflight deliberately checks neither the `podman` binary\nnor any machine state, because only a launch that **builds** the guest\nimage runs podman. A warm-cache launch — the image on disk already stamps\nthe pinned version — boots it with vfkit and invokes podman not once, so\nit neither gates on a started machine nor starts one. (The preflight does\ncheck `gvproxy`, which normally resolves out of podman's Homebrew formula,\nso a host with neither podman nor an on-PATH `gvproxy` still fails there.)\n\nOn the build path the launcher brings podman up itself rather than\nprinting two commands and refusing, since claude-vm is meant to be one\ncommand on a fresh host where podman has never been initialized. The\ndecision reads `podman machine list`: no machine listed gets a `podman\nmachine init` then a `podman machine start`; a listed-but-stopped machine\ngets a `start`; a running machine is left exactly as found. At end of run\nthe launcher stops the machine **iff it was the one that started it** — a\nmachine found running is left running, and an init'd machine is stopped\nrather than removed, so the next build reuses it.\n\nThere is no config surface for any of this: it is launcher plumbing, not\npolicy. Every init\u002Fstart\u002Fstop is logged to stderr as it happens, and\nthose log lines are its only trace. See the payload README's \"The\nlauncher manages the podman machine\" section for the mechanic.\n","# claude-vm\n\nRun Claude Code inside an isolated Linux micro-VM on macOS. Every\nnon-secret operational knob — VM resources, the egress allowlist, extra\nmounts, the proxy, the guest's own environment variables, and how the\nrepo is made available to the guest — comes from layered **YAML config**\nrather than claude-vm's own environment variables.\nThe guest authenticates with the **host's live claude.ai OAuth\ncredential**, which the launcher extracts from the macOS Keychain at\nlaunch and shares into the guest (where the image's fstab mounts the\nshare `ro`), plus an **identity seed** the launcher builds from your host\n`~\u002F.claude.json` — the `userID` + `oauthAccount` selected from the host,\nplus synthesized\n`hasCompletedOnboarding` \u002F `autoUpdates: false` \u002F version keys — so the\ninteractive in-guest session comes up already onboarded, logged in, and\nwith self-update disabled (issue #88). Both are secrets, neither is\nwritten to config, and both ride the same transient shred-on-exit\nmount. No token environment variable is required — just be logged in to\nClaude Code on the host.\n\nThe entry point is `bin\u002Fclaude-vm` (issue #51), a preflight wrapper\nthat ships on PATH for the Bash tool; it forwards to the launcher and\nimage-build scripts, which ship as payloads under\n`${CLAUDE_PLUGIN_ROOT}\u002Fpayload\u002F`. This skill explains the config\nsurface and drives the launcher.\n\n## Quick start\n\n```bash\n# 1. Be logged in to Claude Code on this host. The launcher installs the\n#    host's live claude.ai OAuth credential (extracted from the macOS\n#    Keychain) AND seeds the guest's identity (userID + oauthAccount from\n#    your ~\u002F.claude.json, plus synthesized onboarding\u002Fauto-update-off\n#    keys) so the in-guest claude comes up already onboarded and logged\n#    in. Run `claude` once and complete the claude.ai login if you have\n#    not; the launcher aborts at a preflight if you are not logged in.\n#    No token environment variable is required.\n\n# 2. (Optional) drop a global config PAIR at\n#    ~\u002F.config\u002Fclaude-vm\u002Fconfig-bake.yml + config-boot.yml and\u002For a\n#    per-repo pair at \u003Crepo>\u002F.claude-vm\u002Fconfig-{bake,boot}.yml. A bake\n#    file holds image-bytes keys; a boot file holds run-time keys.\n#    Run \u002Fclaude-vm-config-global to write the global pair from the\n#    resolved defaults, and \u002Fclaude-vm-config-repo (from inside a repo)\n#    to write per-repo overrides (both idempotent), or see\n#    payload\u002Fconfig-bake.example.yml + config-boot.example.yml for a\n#    starting point. bin\u002Fclaude-vm below also offers to create the global\n#    config for you if it is missing. (A legacy single-file config.yml is\n#    no longer read -- the launcher aborts with a migration message.)\n\n# 3. Launch from inside the repo you want to run a VM for. bin\u002Fclaude-vm\n#    derives the repo name and root, names the run, and forwards to the\n#    launcher, which makes the repo available RW to the guest.\nclaude-vm [claude args...]\n```\n\nOn exit, the launcher copies the guest's changes back to the local\nsource by default (clone mode). The companion skills extract work\nexplicitly: `\u002Fclaude-vm-diff`, `\u002Fclaude-vm-apply-local`,\n`\u002Fclaude-vm-apply-remote`.\n\n## Config surface\n\n**Four files, all optional** (issue #179) — a **bake** file and a\n**boot** file per tier. Placement rule: a key that changes **bytes in\nthe guest `.raw` image** goes in a **bake** file; a key applied at **run\ntime** goes in a **boot** file. Placement IS the classification, made\nonce by the operator — a knob in the wrong file loudly does nothing\ninstead of silently poisoning the image cache.\n\n1. **Global bake**: `~\u002F.config\u002Fclaude-vm\u002Fconfig-bake.yml` — machine-wide\n   image-bytes defaults.\n2. **Global boot**: `~\u002F.config\u002Fclaude-vm\u002Fconfig-boot.yml` — machine-wide\n   run-time defaults.\n3. **Per-repo bake**: `\u003Crepo>\u002F.claude-vm\u002Fconfig-bake.yml` — this repo's\n   image-bytes overrides. Shipping this file gives the repo its OWN image.\n4. **Per-repo boot**: `\u003Crepo>\u002F.claude-vm\u002Fconfig-boot.yml` — this repo's\n   run-time overrides.\n\nRun `\u002Fclaude-vm-config-global` to create the global pair from the\nresolved defaults, and `\u002Fclaude-vm-config-repo` (from inside a repo) to\nwrite per-repo overrides; both are idempotent and never clobber an\nexisting file. A legacy single-file `config.yml` (either tier) is no\nlonger read — the launcher aborts with a migration message rather than\nsilently dropping the knobs it set.\n\n**What goes where:**\n\n- **bake file** — `packages:` (a flat list of apt packages baked into\n  the image), `apt_sources:` (third-party apt repos rendered into the\n  image), `image.root_headroom_mb`, `env.set` (guest environment\n  variables written INTO the image — literals only).\n- **boot file** — `cpus`, `mem`, `guest_image`, `repo.*`, `proxy.*`,\n  `egress.allow`, `mounts`, `provisioner`, `packages:` (here a flat\n  list installed AT BOOT), `update_at_boot`, `add_apt_uris_to_allowlist`,\n  `apt_sources:` (for a boot-time install; union+dedup with the bake\n  file's), `claude.*`, `github.*`, `env.*` (all three sub-keys;\n  `env.copy` and `env.files` are boot-ONLY and abort in a bake file).\n\n### Layering semantics\n\nThe effective config is the union of all four files (compose each tier's\nbake+boot, then merge global under repo):\n\n- **Scalars** (`cpus`, `mem`, `guest_image`, `image.root_headroom_mb`\n  [bake], `repo.mount`, `repo.copy_back`, `proxy.*`, `claude.version`,\n  `claude.renderer`, `update_at_boot`, `add_apt_uris_to_allowlist`,\n  `claude.permission_mode`, `claude.plugins.update_at_boot`,\n  `claude.plugins.add_marketplace_uris_to_allowlist`, `github.auth`):\n  repo overrides global; global fills gaps; a hardcoded default applies\n  only when neither layer sets the key.\n- **Scalar maps** (`claude.plugins.enabled`, `env.set`): repo overrides\n  global **per key** — each entry follows the scalar repo-wins rule\n  independently, so a repo can flip one plugin's enabled state, or one\n  environment variable's value, without restating the global map.\n- **Lists** (bake file: `packages`, `apt_sources`, `claude.marketplaces`,\n  `claude.plugins.bake`; boot file: `egress.allow`, `mounts`, `packages`,\n  `apt_sources`, `claude.marketplaces`, `claude.permissions.allow`,\n  `claude.permissions.ask`, `claude.permissions.deny`,\n  `claude.plugins.install_at_boot`, `env.copy`, `env.files`): **merged** —\n  the union of global + repo entries, de-duplicated. `apt_sources` and\n  `claude.marketplaces` are allowed in **both** file types; each is unioned\n  and deduped by `name`, and the same name with DIFFERING content\n  (`{repo, key_url}` \u002F `url`) aborts the launch (no silent shadowing).\n- **Placement guard**: `claude.plugins` is the one map that legitimately\n  appears in both file types, so a sub-key in the wrong file aborts the\n  launch with a message naming the file that carries it — `bake` belongs in\n  the bake file (it changes image bytes), and `install_at_boot` \u002F\n  `update_at_boot` \u002F `add_marketplace_uris_to_allowlist` \u002F `enabled` belong in\n  the boot file. A *presence* test, so a misplaced sub-key written empty (a\n  valueless `bake:`, or `bake: []` \u002F `\"\"` \u002F `{}`) aborts exactly like a\n  populated one.\n  `env` has the same shape and its own guard: `env.set` is allowed in both\n  file types, while `env.copy` and `env.files` are **boot-only** and abort in\n  a bake file — a *presence* test, so an empty or valueless `env.copy:`\n  aborts too. See *Guest environment variables* below for why.\n\n### Keys\n\n```yaml\n# The keys below are grouped by which FILE they live in (bake vs boot). A key\n# in the wrong file loudly does nothing rather than silently poisoning the cache.\n\n# --- BOOT file keys (config-boot.yml -- run-time; never rebuild the image) ---\ncpus: 4\nmem: 8192\nguest_image: \u002Fpath\u002Fto\u002Fguest.raw   # repo may override; SET = used verbatim\n                                  # (opts out of image-identity derivation);\n                                  # UNSET = derived guest+global\u003Chash>.raw\n                                  # (no repo-bake file) or\n                                  # guest+global\u003Chash>+\u003Creponame>-\u003Crepohash>.raw\n                                  # (repo ships a config-bake.yml)\n\nrepo:\n  mount: clone                    # clone (default) | live\n  copy_back: local                # local (default) | none\n\n# Boot-time apt: a flat `packages:` LIST installed AT BOOT (through the proxy,\n# blocking, before claude starts -- issue #106); update_at_boot runs\n# `apt-get update && upgrade`; add_apt_uris_to_allowlist derives apt egress;\n# apt_sources here feed a boot-time install (union+dedup by name with the bake\n# file's; a baked name is not re-rendered). Use install-at-boot packages for\n# things that change often (e.g. the AWS SDK\u002FCLI) so they stay fresh without a\n# rebuild. This requires `apt` in the guest, which mkosi does not provide for\n# free -- so `apt` is baked into every guest image's base Packages= list\n# unconditionally. The guest's baked apt sources are binary-only (main + updates\n# + security, no deb-src\u002Fdebug\u002FTranslations -- issue #106 real-run fix) to keep\n# the per-boot apt working set small; boot_apt_phase ends with `apt-get clean`.\n# The proxy that covers boot-time apt ALSO covers a mid-session interactive\n# apt-get: run.env exports lowercase http_proxy\u002Fhttps_proxy\u002Fno_proxy alongside\n# the uppercase forms (apt honors only lowercase; curl ignores uppercase\n# HTTP_PROXY for plain http:\u002F\u002F), and the boot launcher writes a persistent\n# \u002Fetc\u002Fapt\u002Fapt.conf.d\u002F99claude-vm-proxy so proxying does not depend on a shell\n# re-sourcing run.env.\npackages:                         # (in config-boot.yml) apt packages installed\n  - awscli                        # AT BOOT, through the proxy (a flat list)\nupdate_at_boot: true              # apt-get update && upgrade at boot (default true)\napt_sources: []                   # (boot) third-party repos a boot-time install\n                                  # pulls from: {name, repo, key_url}\nadd_apt_uris_to_allowlist: auto   # auto (default) | always -- adds\n                                  # deb.debian.org\u002Fsecurity.debian.org +\n                                  # apt_sources hosts to guest egress iff\n                                  # boot-time apt work is configured (auto),\n                                  # or unconditionally (always)\n\n# --- BAKE file keys (config-bake.yml -- image bytes; editing rebuilds) ---\n# In config-bake.yml, `packages:` is a flat LIST BAKED into the image (present\n# with no boot-time network), `apt_sources:` are rendered into the image at\n# build time, and image.root_headroom_mb sizes the root partition. The image\n# cache key + filename is a WHOLE-FILE, RAW-BYTE hash of the bake files -- no\n# key-picking, no canonicalization -- so editing a bake file (including only its\n# trailing newline, the documented force-rebuild lever) rebuilds the image;\n# editing a boot file never does. A repo that ships a config-bake.yml gets its\n# OWN image (its name in the filename); a repo without one shares\n# guest+global\u003Chash>.raw.\n#\n# packages:                       # (in config-bake.yml) apt packages BAKED in\n#   - jq\n#   - ripgrep\n# apt_sources: []                 # (bake) third-party repos rendered at build time\n#\n# image.root_headroom_mb: extra MiB of FREE SPACE the guest root filesystem is\n# sized ABOVE its base content (default 1024, repo overrides global). Real-\n# hardware testing hit ENOSPC twice in one short session on a tight-fit-sized\n# root -- boot-time apt working set + ordinary session growth both eat into a\n# root with zero margin. 1024 MB is roughly 20x the observed short-session\n# growth. It is a BAKE key: changing it changes the bake-file hash and triggers\n# a rebuild.\nimage:\n  root_headroom_mb: 1024\n\n# Marketplaces + BAKED plugins (BAKE file). The image build runs the\n# host-verified guest `claude` binary inside the build container with HOME\n# pointed at the image root and drives its own CLI (`claude plugin marketplace\n# add` \u002F `claude plugin install`), so the image ships a real\n# \u002Froot\u002F.claude\u002Fplugins that loads with NO marketplace egress at boot. A failed\n# add\u002Finstall FAILS THE BUILD rather than shipping an image without them --\n# for the marketplaces declared HERE and every `bake:` ref. A marketplace\n# declared only in the boot file is pre-registered as an optimization, and a\n# failure there only warns (the guest adds it at boot).\n# Placement here (not in the boot file) is what puts these under the whole-file\n# image-identity hash; writing `claude.plugins.bake` into a boot file aborts the\n# launch. Prefer an explicit https:\u002F\u002F url over the `owner\u002Frepo` shorthand so the\n# launcher can derive the marketplace's egress host. Shown commented out, like\n# the bake `packages:`\u002F`apt_sources:` above, because the boot file's own\n# `claude:` map follows below and one document cannot carry both.\n#\n# claude:\n#   marketplaces:\n#     - name: thevoskamps\n#       url: https:\u002F\u002Fgithub.com\u002FTheVoskamps\u002Fclaude-plugins-marketplace.git\n#   plugins:\n#     bake:\n#       - block-background-agents@thevoskamps\n#       # COMPILED HOOKS NEED NO TOOLCHAIN: the guardrails permission-gate\n#       # ships prebuilt, committed binaries (one per \u003Cgoos>-\u003Cgoarch>,\n#       # including the guest's linux-arm64), so baking it requires nothing\n#       # in this file's `packages:` -- no `golang`, nothing.\n#       # - guardrails@thevoskamps\n\n# --- BOOT file keys, continued ---\nclaude:\n  version: stable                 # stable (default) | latest | \u003Cpinned>\n                                  # host-side GPG-verified cache key\n  renderer: classic               # classic | fullscreen | (unset)\n                                  # terminal renderer on the interactive\n                                  # console; unset uses claude's own default\n  remote_control: false           # true | false (default) | (unset)\n                                  # opt-in Remote Control: true adds\n                                  # --remote-control + a date-stamped --name\n  permission_mode: bypassPermissions   # bypassPermissions (default) | default\n  permissions:\n    allow: []\n    ask: []\n    deny: []\n  marketplaces: []                # {name, url} entries. Allowed in BOTH file\n                                  # types (like apt_sources); `name` must match\n                                  # the marketplace's OWN manifest name. One\n                                  # declared HERE only has to be reachable from\n                                  # the GUEST -- a url the image build cannot\n                                  # reach warns and is added at boot instead.\n  plugins:\n    # bake: lives in the BAKE file -- see the bake-file block above.\n    install_at_boot: []           # plugin@marketplace refs installed at boot\n    update_at_boot: true          # refresh marketplaces + update the installed\n                                  # plugins at boot (default true). This is the\n                                  # freshness path for BAKED plugins: they are\n                                  # frozen at build time and the image-identity\n                                  # hash excludes marketplace HEAD, so a\n                                  # marketplace bump lands at the next boot with\n                                  # no rebuild.\n    add_marketplace_uris_to_allowlist: auto   # auto (default) | always\n    enabled:                      # OPTIONAL map, plugin ref -> boolean,\n                                  # mirroring settings.json's enabledPlugins.\n                                  # Every bake\u002Finstall_at_boot ref defaults\n                                  # enabled; list an entry only to override\n                                  # (false = installed-but-disabled). Keys must\n                                  # name an installed ref; values must be\n                                  # boolean; a typo aborts the launch.\n      show-loaded-rules@thevoskamps: false\n\nproxy:\n  cmd: \"\u003Cforward-proxy launch command>\"   # must read\n                                          # $CLAUDE_VM_EGRESS_ALLOWLIST\n  port: 3128\n  host_alias: 192.168.127.254\n\negress:\n  allow:                          # outbound hosts permitted via the proxy\n    - api.anthropic.com\n    - github.com\n    - claude.ai\n\nmounts:                           # extra mounts beyond the repo auto-mount\n  - source: ~\u002F.claude\u002Fpolicy      # ALWAYS read-write -- see below\n    tag: policy\n  - source: ~\u002Fdatasets\u002Ffoo\n    tag: data\n  - source: ~\u002F.gitconfig          # a single FILE works too\n    tag: gitconfig\n    path: \u002Froot\u002F.gitconfig        # optional guest mountpoint override\n\ngithub:\n  auth: none                      # none (default) | host-token\n\n# Guest environment variables (issue #135). `set` is allowed in BOTH file\n# types; `copy` and `files` are BOOT-ONLY and abort in a bake file (they read\n# the HOST environment at launch, which does not exist at build time, and\n# their values must never become image bytes). See \"Guest environment\n# variables\" below for the precedence chain and the egress pairing.\nenv:\n  set:                            # explicit literals; NON-SECRET only (these\n    FOO_ENDPOINT: https:\u002F\u002Ffoo.internal\u002Fv2   # values ARE committed config)\n  copy:                           # NAMES read from the environment claude-vm\n    - OPENROUTER_API_KEY          # is launched from; an unset\u002Fempty one aborts\n    - TAVILY_API_KEY\n  files:                          # host .env files parsed at launch; a later\n    - ~\u002F.config\u002Ffoo\u002Fprod.env      # file wins over an earlier one\n```\n\n- `egress.allow` is written to a newline-delimited file whose path is\n  exported as `CLAUDE_VM_EGRESS_ALLOWLIST`. When `proxy.cmd` is unset,\n  the launcher defaults to the bundled tinyproxy launcher\n  (`payload\u002Fproxy\u002Ftinyproxy-launch.sh`), which reads that file and binds\n  `CLAUDE_VM_PROXY_PORT`. A `proxy.cmd` override must likewise read that\n  file instead of a hand-maintained allowlist baked into the command.\n- `mounts` generates the extra `virtio-fs` device flags, and the guest\n  mounts each one at `path:` (default `\u002Fmnt\u002F\u003Ctag>`) before claude starts.\n  A leading `~` in `source` expands to `$HOME`. Both `source` and `tag`\n  are mandatory per entry — the guest mounts each share *by* its tag, so\n  an entry with an empty or omitted `tag:` is a share nobody can mount\n  and two of them would collide on one tag.\n\n  **Every extra mount is read-write, and pierces the VM isolation\n  boundary for that one path.** Guest writes land on the host path\n  **live** — no copy-back step, no review, no undo (`repo.copy_back`\n  governs the *repo* mount only). Everything else about the VM still\n  holds; that one path is simply outside it, on purpose.\n\n  **There is no read-only option, and no `mode:` key.** Read-only cannot\n  be enforced on this stack: vfkit's virtio-fs device has no read-only\n  export (it rejects `readOnly`\u002F`readonly`\u002F`ro` as unknown option keys —\n  verified against vfkit v0.6.4), and the guest session runs as root, so\n  a guest-side `ro` is undoable from inside the guest. A config that\n  still sets `mode:` **aborts the launch** rather than having the key\n  ignored, so nobody believes a share is read-only when it is not.\n  Enforced read-only at the hypervisor boundary is tracked as issue #233.\n  Never point a mount at anything you would mind an autonomous agent\n  rewriting; to give the guest read access to something you care about,\n  mount a disposable copy.\n\n  A single **file** `source` works as well as a directory: virtio-fs\n  shares directories only, so the launcher wraps the file in a per-entry\n  directory (hard-linking it, so writes still reach the host file) and\n  the guest bind-mounts just that one file onto `path:`.\n  Nothing else from the file's real parent directory reaches the guest.\n  A hard link cannot cross volumes: the wrap directory sits in the run\n  dir, and a file on another volume aborts the launch — mount its\n  directory instead.\n  A caveat a directory mount does not have: the kernel refuses a\n  `rename(2)` onto a file bind mount with `EBUSY`, so a single-file\n  mount takes in-place edits but **not** the write-a-temp-then-rename\n  pattern `git config`, `sed -i` and most editors use. Mount the\n  containing directory when the guest needs to replace the file.\n\n  Every mistake aborts the launch at config load rather than booting a VM\n  without the mount you asked for: a missing `source`\u002F`tag`, a `source`\n  that is not on the host, a **directory** `source` whose path carries a\n  `,`, a `tag` that is reserved\n  (`repo`\u002F`runconfig`\u002F`claudebin`\u002F`claudecreds`), outside\n  `[A-Za-z0-9._-]`, repeated, or unusable in the tag's other roles (see\n  below), a `mode` key, and a `path` that is relative, carries `..`,\n  overlaps one of claude-vm's own guest mountpoints — landing on one,\n  above one (`\u002Fmnt`, `\u002F`) or inside one (`\u002Fmnt\u002Frepo\u002Fsub`) — shadows a\n  guest OS path, or duplicates another entry's. The diagnostic names the\n  entry by its position in the merged boot config — `mounts` is a union\n  list, so that number counts through the global entries before the\n  per-repo ones and need not be the entry's position in either file on\n  its own — and by its path when it has one.\n\n  **A `tag` is not only a tag,** which is why the charset is necessary\n  but not sufficient. The same string is vfkit's `mountTag=`, a bare argv\n  word in the guest's `mount -t virtiofs -o rw \u003Ctag> \u003Cpath>`, a path\n  *component* in `\u002Fmnt\u002F\u003Ctag>` and in both the host and guest directories\n  a single-file mount is staged through, and a `mounts.tsv` field. So a\n  `tag` of `.` or `..` is rejected — it would walk one level up out of\n  each of those trees the entry reaches, and `path:`'s own `..` check\n  never sees a tag-derived mountpoint — and so is a `tag` beginning with\n  `-`, which the guest's `mount` reads as an option rather than as the\n  device.\n  `...`, `a..b` and `a-b` are ordinary names and pass. The `source` side\n  of the same device string is why a **directory** source may not carry a\n  comma: vfkit reads it as the start of another device option. That last\n  rule covers the `mounts` entries only — a *repo* path (or `$HOME`, or\n  `$TMPDIR`) carrying a comma breaks the built-in shares, the EFI store,\n  the disk, the console log or the gvproxy socket the same way and is not\n  checked; the launch fails loudly on the argument rather than booting, and\n  `payload\u002FREADME.md` → *The tag is not just a tag* records why it is left\n  there. The one such path this feature adds — the single-file wrap\n  directory (`$RUN\u002Fmount-wrap`) — is checked: the launcher aborts on a\n  comma there when it wraps a file, naming the run dir. That is an\n  earlier, cause-naming abort rather than a rescue; the other arguments\n  break the same launch anyway.\n\n  Those checks run on a **normalized** `path:`, so a mount cannot dodge\n  them by respelling its mountpoint: repeated slashes, a trailing slash\n  and `.` segments in any position (`\u002F.\u002Fetc`, `\u002Fmnt\u002F.\u002Frepo`, `\u002Fetc\u002F.`,\n  and `\u002F.` for the guest root) are collapsed first, which is why the\n  diagnostic names the collapsed path rather than what you wrote. A `..`\n  segment is the exception, rejected rather than resolved — where it\n  lands depends on the guest's filesystem, which the host cannot read.\n\n  **The guest OS's own paths are protected, by shape.** They are\n  `\u002Fbin \u002Fboot \u002Fdev \u002Fetc \u002Fhome \u002Flib` (and its `\u002Flib32`, `\u002Flib64`,\n  `\u002Flibx32` spellings), `\u002Fproc \u002Froot \u002Frun \u002Fsbin \u002Fsys \u002Ftmp \u002Fusr \u002Fvar` —\n  `CLAUDE_VM_GUEST_SYSTEM_PATHS` in `payload\u002Flib\u002Fconfig.sh` is the one\n  authoritative list. Linux stacks a\n  mount, so landing on one hides the image's own files for the whole\n  session, and the mount phase runs first, so the breakage surfaces later\n  as something unrelated. A **directory** source may not land on, above\n  or inside one of those paths — use `\u002Fmnt\u002F\u003Ctag>` (the default), `\u002Fsrv`\n  or `\u002Fopt`. A single **file** may not land on or above one, and may sit\n  inside only `\u002Froot`, `\u002Fhome` or `\u002Ftmp`, which is what makes\n  `path: \u002Froot\u002F.gitconfig` legal while `path: \u002Fetc\u002Fld.so.preload` is not.\n  The guest checks as well, since only it can see the image: a mountpoint\n  that already exists and is non-empty, or a single-file target that\n  exists at all, is warned about on the boot console and **skipped**\n  rather than mounted over.\n- `claude.version` selects which `claude` binary the host-side verified\n  cache fetches: `stable` (default), `latest`, or a pinned version\n  (`2.1.172`). The host resolves a channel to a concrete version,\n  downloads that version's GPG-signed manifest, verifies the signature\n  against the operator's pinned key, checksum-verifies the binary, caches\n  it keyed on the version, and shares it into the guest, where the image's\n  fstab mounts it `ro`. A failed `gpg --verify` or a checksum mismatch\n  **aborts the launch**. On a warm boot (already cached), the launcher\n  drops `claude.ai` \u002F\n  `downloads.claude.ai` from the guest egress allowlist. See the payload\n  README's \"Verified claude cache\" section for the operator's one-time\n  key-import step.\n- `claude.renderer` selects the in-guest claude's terminal renderer on\n  the interactive console (the vfkit `stdio` byte pipe). Both renderers\n  work over the console — this is a preference, not a workaround:\n  `classic` disables the alternate-screen buffer\n  (`CLAUDE_CODE_DISABLE_ALTERNATE_SCREEN=1`), `fullscreen` forces the\n  flicker-free fullscreen renderer (`CLAUDE_CODE_NO_FLICKER=1`), and\n  leaving it unset passes nothing so claude uses its own default. The\n  launcher writes the matching `CLAUDE_CODE_*` var into `run.env`. An\n  unrecognized value aborts the launch.\n- `claude.remote_control` is an opt-in boolean (default `false`\u002Funset).\n  When `true`, the launcher injects `--remote-control` into the in-guest\n  claude invocation (unless the CLI args already carry it) and, when\n  Remote Control is in effect but no `--name` was given, appends a\n  date-stamped `--name` (format like `Jul10-14:30`). When `false`\u002Funset,\n  claude runs without Remote Control and the CLI args pass through\n  unchanged. Accepts `true`\u002F`false` (or unset); any other value aborts\n  the launch. This is the config-driven equivalent of passing\n  `--remote-control` on the command line — see the interactive-session\n  section below.\n\n`claude.permission_mode`, `claude.permissions.*`,\n`claude.plugins.bake` \u002F `.install_at_boot` (as `enabledPlugins`), and\n`claude.plugins.enabled` are **consumed** by the guest `settings.json` render\n(issue #104) — the launcher renders `\u002Froot\u002F.claude\u002Fsettings.json`\nhost-side and shares it into the guest (see \"Guest Claude settings.json\"\nbelow). (There is no schema translation: the launcher merges the two bake\nfiles into one bake document and the two boot files into one boot document,\nand every reader consumes its tier's document at the file-schema path — a\nkey set per the documented schema is always read.) The bake document's\n`packages:` and `apt_sources:` are **consumed** by the guest-image build\n(issue #105 — see \"Guest image\" below). The boot document's `packages:`,\n`update_at_boot`, and `add_apt_uris_to_allowlist` are **consumed** by the\nguest boot launcher's boot-time apt phase (issue #106 — see \"Boot-time\npackage install\u002Fupdate\" in `payload\u002FREADME.md`). The bake document's\n`claude.marketplaces` + `claude.plugins.bake` are **consumed** by the\nimage build's plugin bake step, and the boot document's\n`claude.plugins.install_at_boot` \u002F `.update_at_boot` \u002F\n`.add_marketplace_uris_to_allowlist` by the guest boot launcher's plugin\nphase (issue #107 — see \"Marketplaces and plugins\" below). The remaining key\n(GitHub token seeding) is schema + merge only as of issue #103 — that consumer\nlands in a sibling slice under #39. It resolves correctly through\n`payload\u002Flib\u002Fconfig.sh` today; nothing downstream reads it yet.\n\n- The bake file's `packages:` (baked into the image) vs. the boot file's\n  `packages:` (installed at boot, blocking, before claude starts, through\n  the proxy) — the containing file's tier is what makes each a build-time\n  bake or a boot-time install (this replaces the old single-file\n  `packages.bake` \u002F `packages.install_at_boot` key split; each tier's\n  merged document keeps its own flat `packages:` list, read as written).\n  Both union global + repo entries. The\n  baked packages are present in the guest with no boot-time network, and\n  the image is cached per whole-file bake hash (see \"Guest image\" below).\n  The boot-install list runs `apt-get -y install \u003Clist>` at boot (issue\n  #106): use it for packages that change often (e.g. the AWS SDK\u002FCLI) so\n  they stay fresh without an image rebuild; a failed install warns loudly\n  and continues to claude rather than blocking the session.\n- The boot file's `update_at_boot` (default `true`) runs `apt-get update\n  && upgrade` at boot, through the proxy, before claude starts (issue\n  #106); a failed update warns loudly and continues. `apt_sources`\n  (allowed in BOTH files; union, deduped by `name`; conflicting content\n  under one name aborts) adds third-party apt repos as\n  `{name, repo, key_url}` entries. A **bake** file's apt_sources are\n  rendered at **image-build** time (issue #105 — baked into the mkosi\n  sandbox tree so baked packages from that repo install at build time). A\n  **boot** file's apt_sources (minus any name already baked) are rendered\n  at **boot** time into the guest's live `\u002Fetc\u002Fapt` whenever the boot\n  `packages:` install list is nonempty (issue #106 — reusing the exact\n  same keyring-fetch + sources.list.d-write shape, ported to plain bash\n  since the guest has no python3\u002Fjq).\n- The boot file's `add_apt_uris_to_allowlist` (`auto` default | `always`)\n  controls whether `deb.debian.org` + `security.debian.org` + every\n  `apt_sources` host are added to the guest's egress allowlist.\n  `auto` adds them only when boot-time package work needs them (the boot\n  `packages:` install list nonempty, or `update_at_boot` true); with\n  neither configured, `auto` derives nothing, leaving package repos\n  unreachable — by design, for a hard-secure all-baked config. `always`\n  adds them\n  unconditionally so in-session `apt-get install` also works. The knob\n  never removes URIs that scheduled boot-time work requires, and every\n  derived addition is logged.\n- **Marketplaces and plugins** (issue #107). `claude.marketplaces` (union of\n  `{name, url}`, allowed in both file types, deduped by `name`, conflicting\n  urls under one name abort, and — since issue #226 — an entry with a url but\n  no `name` aborts too, since the name is what every consumer matches on)\n  declares the marketplaces the guest knows.\n  `claude.plugins.bake` (BAKE file) is installed **into the image** at build\n  time; `claude.plugins.install_at_boot` (BOOT file) is installed **at boot**,\n  blocking, before claude starts.\n  - The bake path runs the host-verified guest `claude` binary inside the\n    build container with `HOME` pointed at the image root and drives its own\n    CLI (`claude plugin marketplace add` \u002F `claude plugin install`) — the\n    registry format is claude's and is never hand-written. A failed\n    add\u002Finstall **fails the build**, so a cached image never silently lacks a\n    configured plugin. That strictness covers what the image must **carry**:\n    every `bake:` ref and every marketplace declared in a bake file. A\n    marketplace declared only in a **boot** file is pre-registered here as an\n    optimization, and its url only has to be reachable from the *guest* — a\n    guest-local path (`\u002Fmnt\u002Frepo`), a private source, or an https host outside\n    the build container's egress. A boot-declared entry warns and leaves the\n    registration to the boot path on each of the paths that fail a\n    bake-declared one: no `url` at all, a failed add, or an add that registers\n    under a name other than the configured one (issue #226).\n  - The boot path ensures any marketplace the image does not already carry,\n    then (when `update_at_boot` is `true`, the default) refreshes the\n    marketplaces and updates the installed plugins, then installs the\n    `install_at_boot` refs. This is the freshness mechanism for **baked**\n    plugins: they are frozen at build time and the image-identity hash\n    deliberately excludes marketplace HEAD, so a marketplace bump lands at\n    the next boot with no rebuild. A failure warns loudly on the captured\n    console log and continues to claude. The guest image bakes `git`\n    unconditionally for this phase: the claude CLI shells out to **system\n    git** for every git-url marketplace operation, so without it the\n    add\u002Fupdate fails (fail-soft) and `update_at_boot` would be inert.\n  - `.add_marketplace_uris_to_allowlist` (`auto` default | `always`) mirrors\n    `add_apt_uris_to_allowlist`: under `auto`, marketplace hosts are added to\n    the guest egress allowlist only when boot-side work can actually run (a\n    nonempty `install_at_boot`, a marketplace declared in the boot file that is\n    not also bake-declared, or `update_at_boot` true with at least one\n    marketplace configured). The middle test reads the *declaration*, not the\n    image: the build's pre-registration of a boot-declared marketplace is\n    best-effort since #226 and the host cannot know whether it succeeded, so\n    the gate derives the host either way.\n    Everything bake-declared + `update_at_boot: false` + `auto` derives\n    **nothing** —\n    and the guest still has working plugins, because the baked ones need no\n    marketplace. Every derived addition is logged. A `owner\u002Frepo` shorthand\n    url yields no derivable host (keep `github.com` in `egress.allow`\n    yourself); the launcher says so rather than guessing.\n  - **Compiled hooks need no toolchain**: the guardrails permission-gate\n    ships prebuilt, committed binaries (one per `\u003Cgoos>-\u003Cgoarch>`, the\n    guest's being `linux-arm64`), so baking `guardrails@…` requires\n    **nothing** in the bake file's `packages:` — in particular no\n    `golang`. A platform with no committed binary makes the hook fail\n    closed (exit 2, tool call denied), never silently unadjudicated.\n- `github.auth` (`none` default | `host-token`) selects whether the\n  guest is seeded with a GitHub auth token derived from the host.\n\n### Guest environment variables (issue #135)\n\n`env:` is how a variable reaches the in-guest `claude` session — a plain\nnon-secret setting (`FOO_ENDPOINT`) or a **third-party API key**\n(`OPENROUTER_API_KEY`, `TAVILY_API_KEY`) for a tool, MCP server or model\nprovider other than Anthropic or GitHub. `github.auth` covers the host's\nGitHub token specifically and nothing else.\n\n**The tier a sub-key may be declared in follows from how its value is\nobtained**, not from operator preference:\n\n| Sub-key | Bake tier | Boot tier | Value source |\n| --------- | ----------- | ----------- | -------------- |\n| `env.set` | yes | yes | explicit literal in the config |\n| `env.copy` | no — hard abort | yes | host environment at launch |\n| `env.files` | no — hard abort | yes | host `.env` file at launch |\n\nA bake file's result is image **bytes** that persist across every run of that\nimage; a boot file's result is shredded on exit. `env.copy`\u002F`env.files`\nresolve against a host environment that does not exist at image-build time,\nand a value read from it is exactly the kind of secret that must never become\nimage bytes — so only explicitly written literals are bakeable. The bake-tier\nabort is a **presence** test: an empty or valueless `env.copy:` aborts too,\nsince ignoring it silently would leave you believing a host variable is\nforwarded into a persistent image.\n\n- `env.set` — a map of name → literal value, for **non-secret** settings only\n  (these values are committed config, and in a bake file they are also image\n  bytes). Merge: repo-over-global per key.\n- `env.copy` — a list of **names**. The launcher reads each from its own\n  environment at launch and forwards the value, so no secret is ever written\n  to config and the config stays committable. Keep supplying values however\n  you already do: shell profile, `direnv`, `op run`. Union merge.\n- `env.files` — a list of host `.env` files whose `NAME=value` lines are\n  parsed at launch and forwarded the same way. Union merge. Blank lines and\n  `#` comments are skipped, a leading `export` is dropped, and a value\n  wrapped in matching quotes is unwrapped; there is no variable expansion and\n  no escape processing.\n\n**Precedence**, lowest to highest:\n\n```text\nbake env.set  \u003C  boot env.files  \u003C  boot env.copy  \u003C  boot env.set\n```\n\nWithin each tier, repo-over-global (per key for `set`, union for\n`copy`\u002F`files`); within `env.files`, a later file wins over an earlier one.\nBoot beats bake throughout: bake is the image's baseline, boot is the\nper-launch override.\n\n**Carrier.** Two, one per tier — `run.env` is neither and stays\nlauncher-owned, deliberately a non-secret channel. Bake `env.set` is written\ninto the image at build time and persists. The **whole boot tier**, including\nthe non-secret `env.set` literals, rides the same transient `claudecreds`\nmount as the OAuth credential and identity seed (0600, mounted `ro`\nguest-side, shredded on exit); the guest **sources** it off that mount and\nnever copies it, so no forwarded value reaches the guest filesystem. One\ncarrier for the whole boot tier means the secret and non-secret boot paths\ncannot diverge.\n\n**Egress is the other half.** Forwarding a key does not make the service\nreachable: the guest is egress-confined, so the provider's host must also be\nin `egress.allow` (`openrouter.ai`, `api.tavily.com`, …) or the proxy blocks\nthe call and the failure is baffling. A variable *name* implies no hostname\nthe way an apt source's URI does, so nothing is derived automatically — there\nis no `add_apt_uris_to_allowlist` analogue. Add the pair together.\n\n**Every mistake aborts the launch**, rather than booting a guest that looks\nfine while lacking a key it was configured to have (which surfaces much later,\ndeep inside a tool call, as an opaque auth error naming nothing): `env.copy`\nor `env.files` in a bake file; an `env.copy` name unset **or empty** on the\nhost; an `env.files` path that is not on the host or does not parse; a name\noutside `[A-Za-z_][A-Za-z0-9_]*` from any source; a non-scalar `env.set`\nvalue, or a key left valueless (write `NAME: \"\"` for the empty string); and a\nname the launcher itself composes — every name in `run.env` (the proxy vars,\n`CLAUDE_ARGS`, the `*_TAG` mount vars, `IS_SANDBOX`, `DISABLE_AUTOUPDATER`,\nthe renderer `CLAUDE_CODE_*` vars, the terminal geometry, the\n`CLAUDE_VM_*_UPDATE_AT_BOOT` flags) plus `CLAUDE_VM_LAST_CLAUDE_STATUS` —\nbecause the guest sources `run.env` *before* both env files, so such an entry\nwould overwrite the launcher's own value (a different proxy, a renamed mount\ntag, a replaced `claude` argv) and break the boot rather than configure\nanything. `CLAUDE_VM_LAST_CLAUDE_STATUS` is the exception in the other\ndirection — the launcher exports it long *after* both files, so a config entry\nfor it would be silently overwritten instead — and refusing at load covers\nboth. The abort message lists the whole reserved set. No diagnostic ever\nprints a value.\n\n**Rebuilds.** No new trigger is needed: the image identity is already a\nwhole-file, raw-byte hash of the bake files, so changing a baked `env.set`\nvalue invalidates the cached image and the next launch rebuilds. Editing a\nboot file never rebuilds.\n\n### Guest Claude settings.json (issue #104)\n\nThe launcher renders the guest's `\u002Froot\u002F.claude\u002Fsettings.json`\nhost-side from the merged config and shares it into the guest over the\nexisting transient `claudecreds` mount (the same one the OAuth\ncredential and identity seed ride). The guest boot launcher installs it\nat `$HOME\u002F.claude\u002Fsettings.json`. The guest's **permission** and **plugin**\nsurface — everything the rendered file carries — is derived from the claude-vm\nconfigs **only**: the host's `~\u002F.claude\u002Fsettings.json` and the host's own\ninstalled plugins are never read, so the guest deliberately runs its own\n(possibly riskier) posture. (The host's `~\u002F.claude` *working rules* — the\nnon-policy layer of `CLAUDE.md`, `rules\u002F`, `agents\u002F`, `skills\u002F` and\n`keybindings.json` — **are** seeded in; see *Host working rules seeded into\nthe guest* below.) The rendered keys:\n\n- `permissions.allow` \u002F `.ask` \u002F `.deny` come verbatim from\n  `claude.permissions.*` (each a unioned list).\n- `permissions.defaultMode` comes from `claude.permission_mode`\n  (`bypassPermissions` default | `default`). Only those two values are\n  accepted — any other aborts the launch (it is a security-posture value\n  with no defined behavior for an unknown mode). YOLO-by-default: the VM is\n  the isolation boundary, so `bypassPermissions` is the default with the\n  deny list as backstop. The guest runs claude as **root**, which claude\n  refuses in `bypassPermissions` unless `IS_SANDBOX=1`; the launcher sets\n  `IS_SANDBOX=1` unconditionally in `run.env` (the guest *is* the\n  sandbox).\n- `enabledPlugins` maps every ref in\n  `claude.plugins.bake ++ claude.plugins.install_at_boot` to `true`\n  (de-duplicated), then the optional `claude.plugins.enabled` map\n  overrides those defaults per key. `enabled` mirrors `settings.json`'s\n  own `enabledPlugins` vocabulary (plugin ref → boolean): `false` marks a\n  plugin **installed-but-disabled** (re-enabling needs no reinstall — handy\n  for toggling debug plugins like `show-loaded-rules` \u002F `show-loaded-skills`\n  around a specific issue). The map is validated **once**: every value must\n  be boolean and every key must name an installed ref — an unknown key is a\n  typo and **aborts the launch**.\n- `extraKnownMarketplaces` maps every configured marketplace name (the\n  effective bake ++ boot set) to its source, in the shape claude itself\n  writes: an `https:\u002F\u002F` url renders as `{\"source\":\"git\",\"url\":…}`, an\n  `owner\u002Frepo` shorthand as `{\"source\":\"github\",\"repo\":…}`. This key is\n  rendered because `claude plugin install` was observed writing it into\n  `~\u002F.claude\u002Fsettings.json` alongside `enabledPlugins` — and the boot\n  launcher copies the host-rendered file over whatever the image baked, so\n  omitting it would drop the marketplace declarations the bake step's own\n  CLI run wrote. Rendering it from the same effective set the bake and boot\n  paths use keeps the three from drifting. It does **not** make claude\n  self-install a missing plugin (tested directly: a home dir with only this\n  settings.json and no `~\u002F.claude\u002Fplugins` tree installs nothing), which is\n  why the guest's explicit ensure\u002Finstall\u002Fupdate phase is load-bearing.\n\nclaude-vm has **no** own CLI flags: every post-repo argument is forwarded\nto the guest `claude` verbatim. Plugin enable\u002Fdisable state is set through\n`claude.plugins.enabled` in the config files, not on the command line.\n\n### Host working rules seeded into the guest (issue #108)\n\nThe section above is the **policy** layer, which the guest gets from the\nclaude-vm config rather than from the host. The operator's **\"who I am \u002F\nhow I work\"** layer goes the other way — it follows them into the VM. The\nlauncher stages copies of the host's `~\u002F.claude\u002FCLAUDE.md`, `rules\u002F`,\n`agents\u002F`, `skills\u002F` and `keybindings.json` onto the same transient\n`claudecreds` mount the credential, identity seed and rendered\n`settings.json` ride, and the boot launcher copies them **additively** into\nthe guest's `~\u002F.claude\u002F`: a directory is merged into whatever is already at\nthat path (the image's baked `plugins\u002F` is untouched) and a same-named file\nis overwritten. `CLAUDE.md` and `rules\u002F` travel together because the former\nreferences the latter as `@~\u002F.claude\u002Frules\u002F*.md`.\n\nThere is **no config key** for this — the list is fixed in the launcher and\nspelled again in the boot launcher it emits, so adding an entry is a\ndeliberate edit on both sides of the seam. And it is an **include list**: a\nhost `~\u002F.claude` accumulates directories claude-vm has never heard of, and\nan exclude list would leak every future one by default. Nothing else is\ncopied. Not the policy layer\n(`settings.json` is rendered, plugin state is config-driven), and not\nhost-scoped session state — `projects\u002F` (keyed by host paths the guest does\nnot have), `history.jsonl`, `todos\u002F`, `sessions\u002F`, `logs\u002F`, `statsig\u002F`,\n`shell-snapshots\u002F`, `ide\u002F`, `teams\u002F`, `usage-data\u002F`.\n\nYour host files are never touched: what the guest sees is a copy, staged\nunder `umask 077` in the run's shred-on-exit credential dir. Symlinks are\n**dereferenced**, so a `~\u002F.claude` that is a checkout with `rules\u002F` or\n`skills\u002F` symlinked out of it still seeds real content rather than a\ndangling link. Every entry is optional — a host with no `keybindings.json`\nand no global `CLAUDE.md` launches normally and silently. A copy that\n*fails* prints a warning from the side that attempted it — on the launcher's\nstderr when the host cannot stage the entry (which then never reaches the\nguest at all), in the guest's `hvc0` diagnostic log when the guest cannot\ninstall it — and the launch continues: unlike the credential and\n`settings.json`, no copy failure in this layer aborts a boot. The guest half\ntherefore guards **every** command it runs on an entry, its `mkdir -p` as\nmuch as its copies, since the boot launcher runs under `set -euo pipefail`.\n\nA failed entry is also **dropped**, not left half-copied: `cp -R` keeps going\npast a per-file error, and a partial `rules\u002F` tree is worse than an absent\none. The guest can only drop what this seed created, so a destination that\nalready existed in the image is left alone — with a warning that it may now\nhold a partial copy — rather than having baked content deleted under it.\n\n## Interactive session (the launching terminal IS the in-VM claude)\n\n`claude-vm \u003Crepo>` opens an **interactive** Claude Code session on the\nlaunching terminal — the terminal becomes the guest's `hvc1` console and\nyou drive the full REPL inside the micro-VM (detached clone + egress\nproxy). This is the product goal; headless one-shot is not. Pass\n`--remote-control --name \u003Cn>` straight through (`claude-vm \u003Crepo>\n--remote-control --name foo`) and the same session is *also*\nRemote-Control-attached for AFK observation\u002Freplies — those flags reach\nthe in-guest claude via the existing `CLAUDE_ARGS` plumbing; no extra\ntransport is involved.\n\nWays to turn on Remote Control:\n\n- **Per-launch, via CLI** — pass `--remote-control` (and optionally\n  `--name \u003Cn>`) after the repo path, as above.\n- **Opt-in by config** — set `claude.remote_control: true` in the global\n  or per-repo config. The launcher then injects `--remote-control` for\n  you (without duplicating it if you also pass it on the CLI). Either way,\n  if Remote Control is in effect but you gave no `--name`, the launcher\n  appends a date-stamped `--name` (format like `Jul10-14:30`) so the run\n  is named — matching the date-stamp default this skill documents. A\n  user-supplied `--name` (in either `--name \u003Cv>` or `--name=\u003Cv>` form) is\n  never overridden. Arbitrary CLI args survive verbatim: the launcher\n  quotes `CLAUDE_ARGS` per-argument into `run.env` and the guest boot\n  launcher reconstructs the exact argv, so a value like\n  `--name \"foo #7 micro-vm\"` (with spaces and a `#`) round-trips intact.\n\nTopology: vfkit attaches **two** virtio-serial consoles. The first\n(`logFilePath`, guest `hvc0`) captures all kernel\u002Fsystemd boot output to\n`$CLAUDE_VM_STATE_DIR\u002Flogs\u002F\u003Crun-id>\u002Fguest-console.log` (preserving the\nobservability from the guest-console capture); the second (`stdio`,\nguest `hvc1`) bridges the launching terminal. The guest runs claude as\nthe login program of an autologin `serial-getty@hvc1`, so claude *is*\nthe session with no shell in between. Boot diagnostics stay on `hvc0`\n(off your terminal).\n\nBecause the `stdio` console is a byte pipe that needs a real controlling\nTTY on the host, **launch `claude-vm` from a real terminal**, not from a\npipe. The console carries no live window-resize channel, so the launcher\nseeds the guest tty geometry once from the host's `stty size` at launch;\nthere is no live resize.\n\n## Repo mount strategy (`repo.mount`)\n\nHow the repo is made available RW to the guest:\n\n- **`clone` (default)**: `git clone --no-hardlinks` the repo into a\n  **persistent** worktree, mounted RW. The guest never touches the live\n  working tree or `.git`. The worktree lives under\n  `$CLAUDE_VM_RUNS_DIR\u002F\u003Crunid>\u002Fworktree` — the runs root, `runs\u002F`\n  under the state root `lib\u002Fconfig.sh` resolves — whether or not the\n  argument is a git repo. It persists after the run so the companion\n  diff\u002Fapply skills can inspect and extract results; they find this\n  repo's runs by the `repo_src` line of each run's `run.meta`.\n- **`live`**: mount the live repo dir RW directly. More convenient,\n  less isolated. Opt-in.\n\n### Getting work back out (clone mode)\n\nAfter the guest exits, the launcher runs **copy-back to the local\nsource by default** (`repo.copy_back: local`). Set\n`repo.copy_back: none` to disable it and extract manually. The three\ncompanion skills handle extraction explicitly:\n\n- `\u002Fclaude-vm-diff` — read-only: show what changed in the VM worktree\n  vs. the local source.\n- `\u002Fclaude-vm-apply-local` — apply the VM worktree's changes to the\n  local source.\n- `\u002Fclaude-vm-apply-remote` — push the VM worktree's changes to the\n  remote.\n\n### Reaping a run whose launcher has exited\n\nA launcher killed with `kill -9` (or a crash, or a closed terminal)\nnever runs its exit trap, and its run dir keeps its guest-image clone.\nEach launcher holds a `lockf` lock on `$RUN\u002Frun.lock` for its lifetime,\nand no process it leaves running holds it, so a dead launcher is a\ndead run. A watcher the launcher starts beside vfkit waits on that\nlock and, the moment the launcher dies, stops vfkit, gvproxy and the\nproxy — so a `kill -9` of the launcher stops the VM too. The watcher\nsignals those three pids, and the launcher's own exit trap the\ngvproxy, proxy and watcher pids, only while each still carries the\nstart time recorded for it at launch.\n`bin\u002Fclaude-vm-cleanup`, run by hand, reaps the rest for every repo at\nonce: it reaps only a run whose lock it can take, whether that run\nexited normally or crashed — killing the pids its `run.meta` records\n(`vfkit_pid`, `gvproxy_pid`, `proxy_pid`, a backstop for a watcher that\nwas killed as well) while each still carries the start time recorded\nbeside it, so a pid since taken by another process is never signalled,\nand removing its gvproxy socket dir, its `creds\u002F` dir (the OAuth\ncredential and identity seed), any raw Keychain blob\n(`.keychain-blob.raw.json`) and its `guest-clone.raw` — and leaves\nevery live run alone. It keeps the run\ndir, `worktree\u002F`, `run.meta` and `run.lock` included, so the companion skills still\nfind the run, and it never removes `$CLAUDE_VM_STATE_DIR\u002Flogs\u002F`, where\neach run's console, gvproxy and proxy logs and egress capture are kept.\nIt reports each run it reaped, with its log dir and kept worktree, or\nspared.\n\n## Guest image — built on demand, version-pinned, claude verified host-side\n\nClaude Code updates daily, so the guest image does **not** bake in\n`claude`:\n\n- The baked image is a **stable base**: a pinned OS plus a boot launcher\n  that, on boot, loads the run environment and then runs the\n  **host-side GPG-verified `claude` binary** mounted RO at\n  `\u002Fmnt\u002Fclaudebin` against the repo at `\u002Fmnt\u002Frepo`, as an interactive\n  session on the `hvc1` console (issue #88). `claude` is never\n  baked in and never fetched-and-run inside the guest (no\n  `curl install.sh | bash` anywhere — there is no such fallback); the\n  host fetches, verifies, and caches it (see \"Verified claude cache\" in\n  the payload README). The base only changes when the base OS pin or the\n  launcher logic changes — not when claude does.\n- The base is **version-pinned** in `payload\u002Fbuild-guest-image.sh`\n  (`BASE_OS_REV` + `LAUNCHER_LOGIC_REV`; never the claude version).\n- **Baked packages (issue #105, re-keyed by #179).** A **bake** file's\n  `packages:` and `apt_sources:` ARE baked into the image (unlike\n  `claude`): the baked packages are present in the guest with no\n  boot-time network, and each `apt_sources` repo's `key_url` is fetched\n  into a keyring so its packages install (`signed-by` that key) at build\n  time. An `apt_sources` entry's `repo` may already carry its own apt\n  one-line `[options]` block (e.g. an operator-authored `signed-by=`);\n  the renderer adapts to the line's existing shape instead of\n  unconditionally appending a second `[options]` block (apt allows only\n  one, and two make the line unparseable) — no block gets one added, a\n  block without `signed-by=` gets it merged in, and a block that already\n  pins `signed-by=\u003Cpath>` is left verbatim with the fetched key written\n  to that path's staging equivalent. Baked `packages:` entries that are\n  null\u002Fempty (e.g. a stray `-` in the YAML list) are stripped during the\n  build render rather than baked in as a literal `\"None\"` package name.\n- **Immutable base + whole-file image identity (issue #179).** The image\n  cache key + filename is a **whole-file, raw-byte hash of the BAKE\n  files** — no key-picking, no canonicalization. Placement of a key in a\n  bake file IS the classification, made once by the operator: a knob in\n  the wrong file loudly does nothing instead of silently poisoning the\n  cache. Because the hash is over raw bytes, list order, key order,\n  whitespace, and even a **trailing-newline toggle** all change it — the\n  trailing-newline toggle is the documented force-rebuild lever. The\n  shape:\n  - a repo **without** a `.claude-vm\u002Fconfig-bake.yml` shares one image\n    keyed on the GLOBAL bake file's hash: `guest+global\u003Chash>.raw`,\n    version `BASE_OS_REV+launcherN+global\u003Chash>` (an absent global bake\n    file hashes to the `00000000` sentinel);\n  - a repo that **ships** a `.claude-vm\u002Fconfig-bake.yml` appends its own\n    segment — the repo NAME plus a hash of the repo bake file —\n    `guest+global\u003Chash>+\u003Creponame>-\u003Crepohash>.raw`, so the filename tells\n    you whose override runs where. The repo segment's PRESENCE is gated\n    on the bake FILE existing (not its content), so two repos with\n    byte-identical repo-bake files still get two images (the name\n    disambiguates): legibility over dedup, an explicit choice.\n\n  Editing a **boot** file never changes identity and never rebuilds;\n  editing a **bake** file (including only its trailing newline) does. The\n  `guest_image` scalar, when set, opts out of identity derivation and is\n  used verbatim.\n\n  The cached base `.raw` is **immutable** and is NEVER attached to a VM:\n  each run APFS-clones it (`cp -c`, instant zero-copy) into the run dir\n  and boots the CLONE. N concurrent sessions cost one base plus each\n  session's written blocks — no cross-session\u002Fcross-repo state leakage\n  (OAuth credential, identity seed, transcripts, boot-installed packages)\n  and no multi-writer corruption on a shared image. The clone is\n  discarded on a clean exit and retained (path logged) on an abnormal one\n  for forensics. There is no host-driven forced stop: the guest halts\n  itself and vfkit (running foreground) exits on its own, so the\n  launcher's `sync` in cleanup simply narrows the window in which writes\n  in flight to the clone are still unflushed when the guest goes away.\n- **Ending a session (issue #179).** The guest decides its own fate from\n  claude's exit status; there is no host→guest shutdown channel.\n  - **A deliberate quit powers the guest off.** `Ctrl-D Ctrl-D`, `\u002Fexit`,\n    and `Ctrl-C Ctrl-C` all exit claude 0, and on 0 the guest starts\n    systemd's ordered poweroff (SIGRTMIN+4 to PID 1 — the bus-less path,\n    so no spurious \"Failed to connect to bus\" error on a guest that ships\n    no dbus). vfkit then exits on its own, control returns to\n    the `claude-vm` launcher on the host, your terminal is restored, the\n    per-run clone is discarded, and the copy-back step runs. This is the\n    normal way to end a session — nothing on the host needs to be killed.\n  - **Ctrl-C belongs to the guest claude.** The launcher disables\n    `isig`\u002F`ixon` on the host tty for the session, so `Ctrl-C` (and\n    `Ctrl-Z`\u002F`Ctrl-\\`\u002F`Ctrl-S`\u002F`Ctrl-Q`) travel to the guest as bytes\n    instead of signalling host-side vfkit — the first `Ctrl-C` shows\n    claude's press-again warning, the second exits 0 and powers off, same\n    as `Ctrl-D Ctrl-D`. Consequence: the keyboard cannot abort a *wedged*\n    guest from that terminal; the recovery path is `kill \u003Cvfkit pid>`\n    from another terminal (vfkit tears the guest down within ~5s and the\n    launcher cleans up normally). The saved tty state is restored on\n    every exit path.\n  - **An abnormal claude death drops you into a guest shell.** If claude\n    exits nonzero (a crash, an OOM kill, or declining the\n    bypass-permissions dialog — the easy way to try this path), the guest\n    does **not** power off yet. The boot launcher hands you an\n    interactive **root login shell on the same console you were already\n    attached to**, so you can run a post-mortem inside the still-running\n    guest: inspect `\u002Fmnt\u002Frepo`, see how the clone diverged, read `dmesg`,\n    check whether the network wiring survived. claude is **not**\n    relaunched — there is no respawn loop. **Exiting that shell powers\n    the guest off** and returns control to the host launcher; the clone\n    is retained (its path is logged) for further forensics.\n- **Boot-time package install\u002Fupdate (issue #106).** A **boot** file's\n  `packages:` (install list) and `update_at_boot` do **not** feed the\n  image-identity hash — they\n  run a blocking phase in the boot launcher itself, right before claude launches,\n  through the same proxy the rest of the guest's egress goes through. The\n  base image DOES need one thing unconditionally to support this phase: `apt`\n  itself, baked into the base `Packages=` list regardless of whether\n  install_at_boot\u002Fupdate_at_boot are configured (mkosi does not otherwise put\n  apt\u002Fdpkg tooling into the guest rootfs, since it installs baked packages\n  from OUTSIDE the image with its own build-container apt) — this is covered\n  by `LAUNCHER_LOGIC_REV`, the base-version pin, not by the image-identity\n  hash. See \"Boot-time package\n  install\u002Fupdate\" and \"Mid-session apt proxying, metadata diet, and root\n  headroom\" in `payload\u002FREADME.md` for the full mechanics (the reused\n  `render_apt_source` shape, the proxy `-o Acquire::*::Proxy=` flags and\n  persistent `apt.conf.d` drop-in, the apt metadata diet, `apt-get clean`,\n  the failure policy, and the `add_apt_uris_to_allowlist` derived-egress\n  gate).\n- On startup, the launcher **ensures the image exists and matches the\n  pinned version**. If the resolved image is missing or version-mismatched,\n  it builds the image (`payload\u002Fbuild-guest-image.sh --output …`, passing the\n  merged bake config through `CLAUDE_VM_BAKE_CONFIG` and the pre-computed\n  image-identity segments through `CLAUDE_VM_IMAGE_IDENTITY_SEGMENTS`) rather\n  than erroring.\n  The image's pinned version is stamped at `\u003Cimage>.version`.\n- **No image artifact is committed to the repo**, and there is no\n  publish-prebuilt-image path. Every machine builds its own.\n\nThe provisioning step that produces the bootable raw image defaults to\nthe bundled `payload\u002Fprovisioners\u002Fpodman-mkosi.sh`: mkosi run inside a\nthrowaway rootless podman container (Debian Trixie build container,\nsystemd ≥ 254 for the offline, loop-device-free `RepartOffline=yes`\npath), emitting a raw EFI-bootable Debian guest with the boot launcher\nwired as the autologin `serial-getty@hvc1` login program (so claude\nbecomes the interactive `hvc1` console session — issue #88), plus an\nunlocked passwordless root (`RootPassword=hashed:`). vfkit boots it\n`--bootloader efi`. `build-guest-image.sh` pins the version and emits the\nboot launcher, then hands `\u003Cboot-launcher-path> \u003Coutput-image-path>` to\nthe provisioner. The `CLAUDE_VM_IMAGE_PROVISIONER` env var overrides the\nbundled default with your own script honoring the same two-argument\ncontract.\n\nThe launcher captures the booting guest's **boot** serial console\n(`hvc0`) to `$CLAUDE_VM_STATE_DIR\u002Flogs\u002F\u003Crun-id>\u002Fguest-console.log` via\nthe first vfkit `--device\nvirtio-serial,logFilePath=…`. The recipe `KernelCommandLine` sets\n`console=hvc0`, so all kernel\u002Fsystemd boot output — and the boot\nlauncher's diagnostic\u002Fseam lines, which it writes explicitly to\n`\u002Fdev\u002Fconsole` — are observable from the host instead of being\ndiscarded, while staying off the interactive `hvc1` terminal. The path\nis reported on exit and retained in the run's log dir, beside the\ngvproxy and proxy logs and the egress capture, where reaping the run\ndoes not reach it.\n\n## Authentication (secrets)\n\nThis section covers the two credentials the launcher handles itself: the\nhost's claude.ai OAuth credential, and (under `github.auth: host-token`) a\nGitHub token. Any **other** third-party key — an OpenRouter or Tavily key for\nan in-guest tool, MCP server or model provider — reaches the guest through\n`env.copy` \u002F `env.files` instead; see *Guest environment variables* above,\nwhich carries the same \"never in config, never in `run.env`, shredded on\nexit\" posture.\n\nThe guest authenticates claude with the **host operator's live claude.ai\nOAuth credential** — the full-scope login credential, not a scoped\ninference token — installed at `$HOME\u002F.claude\u002F.credentials.json`. That\nbearer token alone is **not** sufficient for the interactive TUI to treat\nitself as onboarded and logged in: current Claude Code also reads\nonboarding + identity state from `~\u002F.claude.json`, which a fresh throwaway\nguest lacks — so without it every launch hits the onboarding\u002Flogin wall\ndespite the mounted credential. Two keys matter beyond identity:\n`hasCompletedOnboarding` (absent → claude runs its onboarding flow) and\n`autoUpdates` (unset → claude tries to self-update and fails against its\nRO-mounted binary in the egress-confined guest).\n\nSo the launcher **also seeds the guest's identity + onboarding state**\n(issue #88): it reads your host `~\u002F.claude.json` and emits a seed carrying\n`userID` and `oauthAccount` selected from the host, plus four synthesized\nkeys: `hasCompletedOnboarding: true` (skip the wall), `autoUpdates: false`\n(no self-update), and `lastOnboardingVersion` \u002F `lastReleaseNotesSeen`\nstamped with the concrete resolved claude version. It **additively**\ncarries benign host UI keys when present — `installMethod`,\n`hasSeenTasksHint`, `hasUsedStash`, `tipsHistory` (each silently omitted\nwhen absent) — and seeds a **`projects` entry for the guest mount**\n(`\u002Fmnt\u002Frepo`) with `hasTrustDialogAccepted` \u002F `hasCompletedProjectOnboarding`\nforced `true` so the guest skips the \"Do you trust this folder? \u002Fmnt\u002Frepo\"\ndialog (if the host already has an entry for the launched repo, a **named\nallowlist** of benign per-project keys — `allowedTools` and friends —\nsurvives, rekeyed to `\u002Fmnt\u002Frepo` with those two flags forced true; the\noperator's prompt `history`, `lastSessionId`, and `mcpServers` are\ndeliberately dropped, and unrecognized future keys default to excluded).\nNothing else from `~\u002F.claude.json` (no other `projects{}` entries, no\ntelemetry, no `machineID`) is copied;\n`machineID` is deliberately **not** seeded — the guest mints its own. That\nobject is shared into the guest under the same `claudecreds` mount, and\nthe guest boot launcher installs it at `$HOME\u002F.claude.json` (mode `0600`)\nbefore launching `claude`, so the in-guest session comes up already\nonboarded, logged in, folder-trusted, and with self-update disabled. The\nseed is built via `lib\u002Fcredential.sh`'s `claude_vm_select_claude_json_seed`\n(using `python3`; unit-tested in `payload\u002Ftest\u002Fcredential-test.sh`) and\ncarries account identity, so it rides the same secret posture as the\ncredential: written under `umask 077` into the transient, owner-only\n(`0600`), shred-on-exit `claudecreds` mount, **never** into `run.env` or the\nverified-binary cache. A **preflight** aborts the run with an actionable\nmessage if the host `~\u002F.claude.json` is missing or lacks a usable\n`userID`\u002F`oauthAccount` (i.e. you are not logged in on the host).\n\nThe launcher also quiets claude's startup **install-health check**\n(issue #88): claude probes for a working `claude` at the native installer's\n`~\u002F.local\u002Fbin\u002Fclaude`, but the guest runs the RO-mounted binary from\n`\u002Fmnt\u002Fclaudebin`, so that path is empty and the TUI prints two `claude\ncommand at \u002Froot\u002F.local\u002Fbin\u002Fclaude missing or broken · run claude install to\nrepair` warnings. The guest boot launcher symlinks `$HOME\u002F.local\u002Fbin\u002Fclaude`\n→ the verified RO-mounted binary right after the claude-fetch seam validates\nit; the symlink target is the running binary, so the version comparison\npasses by construction and `autoUpdates: false` plus the RO mount prevent\nwrite-through (empirically confirmed to clear the warnings on real hardware).\nBelt-and-braces with the seeded `autoUpdates: false`, the launcher also\nwrites the documented `DISABLE_AUTOUPDATER=1` env knob into `run.env`.\n\nA second **credential-token preflight** guards against a degraded Keychain\nentry: the `claudeAiOauth` object can be structurally complete yet carry\n**empty** `accessToken` \u002F `refreshToken` strings (with `expiresAt: 0`) —\nwhich happens when your host claude sessions coast on the shared auth\ndaemon's in-memory tokens while the persisted Keychain entry has gone\nstale. Booting the guest with it lands at \"Not logged in · Run \u002Flogin\",\nand an in-guest `\u002Flogin` can trip OAuth reuse-detection and **revoke your\nother live sessions**. So after selecting the credential, the launcher\nvalidates both tokens are non-empty\n(`claude_vm_validate_claude_credential_tokens`) and aborts fast if not,\ntelling you to re-login on the **host** (`claude` then `\u002Flogin`, or restart\nClaude Code — either repairs the Keychain entry) rather than inside the\nguest.\n\nAt launch the launcher reads the credential from the macOS login\nKeychain by service name alone\n(`security find-generic-password -s \"Claude Code-credentials\" -w`).\nThat Keychain item is **not** only the claude.ai login — its JSON also\ncarries sibling keys such as `mcpOAuth` (per-MCP-server OAuth). To avoid\nmounting unrelated MCP credentials into the guest, the launcher **selects\nonly the `claudeAiOauth` key** and writes a file in the shape `claude`\nexpects, `{\"claudeAiOauth\": { ... }}` (selection via `lib\u002Fcredential.sh`,\nusing `python3`; unit-tested in `payload\u002Ftest\u002Fcredential-test.sh`). The\nselected credential is written to a transient, owner-only (`0600`)\ntmpfile and shared into the guest under `mountTag=claudecreds`, **which the\nimage's fstab mounts `ro`**. The `ro` is guest-side, not host-side — vfkit's\nvirtio-fs device has no read-only export, so the host shares this exactly as\nit shares an extra mount, and the same caveat applies: a guest-side `ro`\nstops an accidental write, not a determined one, since the guest session is\nroot. Nothing rests on it — the guest boot launcher copies the file into\n`$HOME\u002F.claude\u002F.credentials.json` (mode `0600`) before launching\n`claude`.\n\nThe credential is a secret and is handled like one: it is **never**\nwritten to config, to `run.env`, or to the verified-binary cache; its\nhost-side tmpfile is created under a tightened `umask 077` and removed\nby the launcher's `cleanup()`\u002F`trap` on every exit. The full raw\nKeychain blob (before selection) lives only in a transient tmpfile\noutside the guest share and is removed immediately after selection.\n\n**Requirements:** macOS only (`security find-generic-password` is a\nmacOS Keychain tool; `python3`, used for credential and identity-seed\nselection, ships with macOS), and you must be logged in to Claude Code\non the host first. The launcher fails fast with an actionable message if\nthe host `~\u002F.claude.json` is missing or lacks a usable\n`userID`\u002F`oauthAccount`, or if the Keychain lookup returns empty or\nnon-zero, or the blob has no usable `claudeAiOauth` key. `egress.allow`\nmust include\nthe Anthropic API host (`api.anthropic.com`) so the in-guest `claude`\ncan reach it. See the payload README's \"Authentication\" section for the\nfull mechanic.\n\n## Requirements\n\n`yq` (mikefarah v4+), `git`, `python3` (stock on macOS; used to select\nthe `claudeAiOauth` key from the Keychain blob — see \"Authentication\"\nabove), `gpg` (`brew install gnupg`, for the host-side verified claude\ncache — see \"Verified claude cache\" in the payload README), a sha256\ntool (`shasum` \u002F `sha256sum`, both stock on macOS\u002FLinux), and — for an\nactual VM boot — `vfkit` and `tinyproxy` (for the bundled default\n`proxy.cmd`). A launch that has to **build** the guest image is the only\none that runs `podman`, for the bundled podman-mkosi provisioner; the\npodman *formula* is in practice a requirement of every launch regardless,\nbecause that is where `gvproxy` normally comes from (next paragraph). What\na build does\n**not** need is a started podman machine: the launcher inits and starts\none itself and stops it again at end of run if it was the one that\nstarted it (see \"The launcher manages the podman machine\" below). On a\nclean host:\n`brew install yq git gnupg vfkit podman tinyproxy`.\n\n`gvproxy` is **not** a separate install and need not be on PATH: it\nships inside the podman Homebrew formula at\n`\u003Cbrew-prefix>\u002Flibexec\u002Fpodman\u002Fgvproxy` and a stock `brew install podman`\ndoes not symlink it onto PATH. The launcher resolves it automatically\n(an explicit on-PATH `gvproxy` first, then podman's libexec), so\ninstalling podman is enough.\n\nBefore any image build, network call, or Keychain read, the launcher\nruns a **trust-path preflight** that checks the local, instant\npreconditions for the verified cache and credential selection up front:\n`gpg` on PATH, the `claude.signing_key_fingerprint` pinned in config,\nthat pinned fingerprint actually present in the gpg keyring, and\n`python3` on PATH. Immediately after, a separate **identity-seed\npreflight** aborts if the host `~\u002F.claude.json` is missing or lacks a\nusable `userID`\u002F`oauthAccount` (i.e. you are not logged in on the host).\nLater, once the credential is selected, a **credential-token check**\naborts if the selected `claudeAiOauth` carries empty `accessToken` \u002F\n`refreshToken` (the degraded-Keychain state described under\n\"Authentication\"), steering you to re-login on the host.\nEach failed check prints the exact remediation\ncommand(s) (e.g. `brew install gnupg`, the\n`curl … | gpg --import` + `gpg --fingerprint` pin steps). Without this\ngate, a cold boot would otherwise pay for a guest-image build and three\nnetwork fetches before aborting on a condition that was knowable at\nstartup. These are an additive early gate; the deep checks in the\nverified cache (gpg-on-PATH and unset-pin hard-abort) and credential\nselection (`python3`) remain as defense-in-depth.\n\nAfter the trust-path preflight, and still before any build\u002Fboot work,\nthe launcher runs a **dependency preflight** that checks the VM\ntoolchain up front (gvproxy resolvable, `vfkit` on PATH, and — only when\nthe bundled default proxy is in use — `tinyproxy`). It fails fast with\none actionable remediation line per missing piece rather than dying deep\nin the boot sequence. A custom `proxy.cmd` owns its own dependencies, so\nthe `tinyproxy` check is skipped then.\n\nThe config-resolution half (layering, scalar\u002Flist resolution) is\nexercisable without the virtualization stack; see\n`payload\u002Ftest\u002Fconfig-test.sh`, and the verified-cache logic (resolve \u002F\nverify \u002F checksum \u002F abort \u002F warm-boot) in\n`payload\u002Ftest\u002Fclaude-cache-test.sh`.\n\nThe per-run endpoint primitives (issue #179) are also exercisable\nwithout a VM: `payload\u002Ftest\u002Fendpoint-test.sh` covers free-TCP-port\nacquisition and TCP\u002Funix-socket liveness (a live listener vs a stale\nsocket-file corpse, the exact distinction the concurrency fix turns on),\nusing real `perl` listeners; `payload\u002Ftest\u002Fbin-config-check-test.sh`\nregression-tests `bin\u002Fclaude-vm`'s four-file bake\u002Fboot config-presence\ncheck so it no longer prints a false \"no global config\" when the\nmigrated pair is present. `payload\u002Ftest\u002Fcleanup-test.sh` covers the\nrun's `run.lock` across a `kill -9` of the launcher, the watcher\nstopping a vfkit stand-in after one, and `bin\u002Fclaude-vm-cleanup` over\ndead, live and lockless run dirs.\n\n`payload\u002Ftest\u002Fpodman-mkosi-test.sh` regression-tests the recipe the\ndefault provisioner generates (the literal `mkosi.conf` and\n`build-in-container.sh`), stubbing only `podman` at the container\nhandoff — added after a real end-to-end build caught failures (a\nbacktick-command-substitution bug corrupting `mkosi.conf`, and a missing\n`curl`\u002F`ca-certificates` in the build container) that no pure-function\n`config-test.sh` case could catch, since none of them render or execute\nthe actual generated recipe files.\n\nThe end-to-end acceptance test — default-provisioner build, vfkit boot\nto the claude-fetch seam (running the host-verified claude off the\nmount), egress confinement, and the host-side GPG-verified cache — is\n`payload\u002Ftest\u002Fhost-acceptance.sh`; it is host-gated by cause: it skips\ncleanly when a required binary is absent,\nbut a stopped or absent podman machine is not a skip — the test starts\nthe machine itself and tears down exactly what it changed on exit. A\nbring-up the test attempted that then fails (`podman machine\ninit`\u002F`start`) is a real failure, not a skip: the test exits non-zero\nrather than green-exiting with nothing proven. Diagnostics (including\nthe machine init\u002Fstart stderr) are retained under\n`$CLAUDE_VM_STATE_DIR\u002Flogs\u002F\u003Crun-id>\u002F` — the state root `lib\u002Fconfig.sh`\nresolves, `~\u002F.local\u002Fstate\u002Fclaude-vm` by default — so a failed run stays\ndiagnosable.\n\n`payload\u002Ftest\u002Fpodman-machine-test.sh` covers the launcher's own podman\nmachine management (issue #215) against a stateful stub podman, and — by\nslicing the build-or-reuse block out of `claude-vm.sh` and running it —\nthe scoping: a warm-cache launch invokes podman zero times, a\nbuild-needing one inits\u002Fstarts, builds, and stops again — including when\nthe bring-up leaves a machine up behind a failure, whether `podman\nmachine start` itself exits non-zero after bringing it up or the\nconfirmation that follows fails.\n\n## The launcher manages the podman machine\n\nThe dependency preflight deliberately checks neither the `podman` binary\nnor any machine state, because only a launch that **builds** the guest\nimage runs podman. A warm-cache launch — the image on disk already stamps\nthe pinned version — boots it with vfkit and invokes podman not once, so\nit neither gates on a started machine nor starts one. (The preflight does\ncheck `gvproxy`, which normally resolves out of podman's Homebrew formula,\nso a host with neither podman nor an on-PATH `gvproxy` still fails there.)\n\nOn the build path the launcher brings podman up itself rather than\nprinting two commands and refusing, since claude-vm is meant to be one\ncommand on a fresh host where podman has never been initialized. The\ndecision reads `podman machine list`: no machine listed gets a `podman\nmachine init` then a `podman machine start`; a listed-but-stopped machine\ngets a `start`; a running machine is left exactly as found. At end of run\nthe launcher stops the machine **iff it was the one that started it** — a\nmachine found running is left running, and an init'd machine is stopped\nrather than removed, so the next build reuses it.\n\nThere is no config surface for any of this: it is launcher plumbing, not\npolicy. Every init\u002Fstart\u002Fstop is logged to stderr as it happens, and\nthose log lines are its only trace. See the payload README's \"The\nlauncher manages the podman machine\" section for the mechanic.\n",{"name":5,"description":7},"main","4b187366f06afb374243166f6a0f5fc1514fa579","plugins\u002Fclaude-vm\u002Fskills\u002Fclaude-vm","https:\u002F\u002Fgithub.com\u002FTheVoskamps\u002Fclaude-plugins-marketplace","https:\u002F\u002Fgithub.com\u002FTheVoskamps","2026-11-14 13:16:57",{"source":8,"skillName":5,"commands":31,"prompt":41,"zipAvailable":42},[32,35,38],{"tool":33,"command":34},"npx","npx skills add TheVoskamps\u002Fclaude-plugins-marketplace --skill claude-vm",{"tool":36,"command":37},"bunx","bunx skills add TheVoskamps\u002Fclaude-plugins-marketplace --skill claude-vm",{"tool":39,"command":40},"pnpm","pnpm dlx skills add TheVoskamps\u002Fclaude-plugins-marketplace --skill claude-vm","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002FTheVoskamps\u002Fclaude-plugins-marketplace\u002Fblob\u002Fmain\u002Fplugins\u002Fclaude-vm\u002Fskills\u002Fclaude-vm\u002FSKILL.md",true,[],[45,52,59,66,73,80],{"skillNo":46,"name":47,"nameZh":6,"description":48,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":49,"categories":50,"keywords":51,"publishedAt":19},"01M77KH3GAXPPXNQS96KDEEZBS","mask-inappropriate-language","Replace inappropriate language (profanity, slurs, strong insults) in provided text or a file with asterisks, character-for-character, preserving everything else.","https:\u002F\u002Fgithub.com\u002FTheVoskamps\u002Fclaude-plugins-marketplace\u002Fblob\u002Fmain\u002Fplugins\u002Fwriting-tools\u002Fskills\u002Fmask-inappropriate-language\u002FSKILL.md",[],[],{"skillNo":53,"name":54,"nameZh":6,"description":55,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":56,"categories":57,"keywords":58,"publishedAt":19},"01M77KGY5TZDQT8QR23Y0R8P7A","theorem-agents-interface","The interface between the sdlc reviewer and the theorem agents it spawns — what each double-dash brief parameter means, and what each consequence class means. Preloaded into every theorem agent (sdlc:theorem-generator, the disprover, and the verifier) via its skills frontmatter, and read by name by the sdlc:theorem-based-pr-reviewer agent for what its briefs' parameters mean; not invoked from the user's slash menu.","https:\u002F\u002Fgithub.com\u002FTheVoskamps\u002Fclaude-plugins-marketplace\u002Fblob\u002Fmain\u002Fplugins\u002Fsdlc\u002Fskills\u002Ftheorem-agents-interface\u002FSKILL.md",[],[],{"skillNo":60,"name":61,"nameZh":6,"description":62,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":63,"categories":64,"keywords":65,"publishedAt":19},"01M77KGT5HW0XAE500WSSM0PZY","sdlc-config-user","Interactively create or merge-update the repo user sdlc config, `\u003Crepo-root>\u002F.sdlc\u002Fuser-config.yml` (tier 3 — this user, this repo, never committed), and add it to the repo's tracked `.gitignore`.","https:\u002F\u002Fgithub.com\u002FTheVoskamps\u002Fclaude-plugins-marketplace\u002Fblob\u002Fmain\u002Fplugins\u002Fsdlc\u002Fskills\u002Fsdlc-config-user\u002FSKILL.md",[],[],{"skillNo":67,"name":68,"nameZh":6,"description":69,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":70,"categories":71,"keywords":72,"publishedAt":19},"01M77KGQGQVB0NYZX0WJRJPDEK","sdlc-config-repo","Interactively create or merge-update the shared repo sdlc config, `\u003Crepo-root>\u002F.sdlc\u002Frepo-config.yml` (tier 2 — tracked, every user of this repo).","https:\u002F\u002Fgithub.com\u002FTheVoskamps\u002Fclaude-plugins-marketplace\u002Fblob\u002Fmain\u002Fplugins\u002Fsdlc\u002Fskills\u002Fsdlc-config-repo\u002FSKILL.md",[],[],{"skillNo":74,"name":75,"nameZh":6,"description":76,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":77,"categories":78,"keywords":79,"publishedAt":19},"01M77KGKPEN7C5RCEDSEP3Z1XB","sdlc-config-global","Interactively create or merge-update the global user sdlc config, `$XDG_CONFIG_HOME\u002Fsdlc\u002Fuser-config.yml` (tier 1 — this user, every repo on this machine).","https:\u002F\u002Fgithub.com\u002FTheVoskamps\u002Fclaude-plugins-marketplace\u002Fblob\u002Fmain\u002Fplugins\u002Fsdlc\u002Fskills\u002Fsdlc-config-global\u002FSKILL.md",[],[],{"skillNo":81,"name":82,"nameZh":6,"description":83,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":84,"categories":85,"keywords":86,"publishedAt":19},"01M77KGFX95J2XEQBBD49QHTXK","pr-read-cli-interface","The contract for sdlc's PR-read CLIs — sdlc-pr-round, sdlc-pr-adjustments, sdlc-fixer-brief and sdlc-records-chain — their arguments, exit codes and output grammar. Preloaded into sdlc:theorem-based-pr-reviewer, sdlc:issue-fixer, sdlc:docs-writer and sdlc:pr-finalizer via their skills frontmatter; not invoked from the user's slash menu.","https:\u002F\u002Fgithub.com\u002FTheVoskamps\u002Fclaude-plugins-marketplace\u002Fblob\u002Fmain\u002Fplugins\u002Fsdlc\u002Fskills\u002Fpr-read-cli-interface\u002FSKILL.md",[],[]]