AGENT SKILL

claude-vm

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 ~/.claude.json, plus synthesized onboarding/auto-update-off/version keys) so the in-guest session comes up already onboarded, logged in, and with self-update disabled.

License 许可
GPL-3.0
最近更新
2026-11-14
Stars
★ 0
Forks
0

01 前言 Front Matter

name
claude-vm
description
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 ~/.claude.json, plus synthesized onboarding/auto-update-off/version keys) so the in-guest session comes up already onboarded, logged in, and with self-update disabled.

03 SKILL.md 正文

claude-vm

Run Claude Code inside an isolated Linux micro-VM on macOS. Every non-secret operational knob — VM resources, the egress allowlist, extra mounts, the proxy, the guest's own environment variables, and how the repo is made available to the guest — comes from layered YAML config rather than claude-vm's own environment variables. The guest authenticates with the host's live claude.ai OAuth credential, which the launcher extracts from the macOS Keychain at launch and shares into the guest (where the image's fstab mounts the share ro), plus an identity seed the launcher builds from your host ~/.claude.json — the userID + oauthAccount selected from the host, plus synthesized hasCompletedOnboarding / autoUpdates: false / version keys — so the interactive in-guest session comes up already onboarded, logged in, and with self-update disabled (issue #88). Both are secrets, neither is written to config, and both ride the same transient shred-on-exit mount. No token environment variable is required — just be logged in to Claude Code on the host.

The entry point is bin/claude-vm (issue #51), a preflight wrapper that ships on PATH for the Bash tool; it forwards to the launcher and image-build scripts, which ship as payloads under ${CLAUDE_PLUGIN_ROOT}/payload/. This skill explains the config surface and drives the launcher.

Quick start

# 1. Be logged in to Claude Code on this host. The launcher installs the
#    host's live claude.ai OAuth credential (extracted from the macOS
#    Keychain) AND seeds the guest's identity (userID + oauthAccount from
#    your ~/.claude.json, plus synthesized onboarding/auto-update-off
#    keys) so the in-guest claude comes up already onboarded and logged
#    in. Run `claude` once and complete the claude.ai login if you have
#    not; the launcher aborts at a preflight if you are not logged in.
#    No token environment variable is required.

# 2. (Optional) drop a global config PAIR at
#    ~/.config/claude-vm/config-bake.yml + config-boot.yml and/or a
#    per-repo pair at <repo>/.claude-vm/config-{bake,boot}.yml. A bake
#    file holds image-bytes keys; a boot file holds run-time keys.
#    Run /claude-vm-config-global to write the global pair from the
#    resolved defaults, and /claude-vm-config-repo (from inside a repo)
#    to write per-repo overrides (both idempotent), or see
#    payload/config-bake.example.yml + config-boot.example.yml for a
#    starting point. bin/claude-vm below also offers to create the global
#    config for you if it is missing. (A legacy single-file config.yml is
#    no longer read -- the launcher aborts with a migration message.)

# 3. Launch from inside the repo you want to run a VM for. bin/claude-vm
#    derives the repo name and root, names the run, and forwards to the
#    launcher, which makes the repo available RW to the guest.
claude-vm [claude args...]

On exit, the launcher copies the guest's changes back to the local source by default (clone mode). The companion skills extract work explicitly: /claude-vm-diff, /claude-vm-apply-local, /claude-vm-apply-remote.

Config surface

Four files, all optional (issue #179) — a bake file and a boot file per tier. Placement rule: a key that changes bytes in the guest .raw image goes in a bake file; a key applied at run time goes in a boot file. Placement IS the classification, made once by the operator — a knob in the wrong file loudly does nothing instead of silently poisoning the image cache.

  1. Global bake: ~/.config/claude-vm/config-bake.yml — machine-wide image-bytes defaults.
  2. Global boot: ~/.config/claude-vm/config-boot.yml — machine-wide run-time defaults.
  3. Per-repo bake: <repo>/.claude-vm/config-bake.yml — this repo's image-bytes overrides. Shipping this file gives the repo its OWN image.
  4. Per-repo boot: <repo>/.claude-vm/config-boot.yml — this repo's run-time overrides.

Run /claude-vm-config-global to create the global pair from the resolved defaults, and /claude-vm-config-repo (from inside a repo) to write per-repo overrides; both are idempotent and never clobber an existing file. A legacy single-file config.yml (either tier) is no longer read — the launcher aborts with a migration message rather than silently dropping the knobs it set.

What goes where:

  • bake file — packages: (a flat list of apt packages baked into the image), apt_sources: (third-party apt repos rendered into the image), image.root_headroom_mb, env.set (guest environment variables written INTO the image — literals only).
  • boot file — cpus, mem, guest_image, repo.*, proxy.*, egress.allow, mounts, provisioner, packages: (here a flat list installed AT BOOT), update_at_boot, add_apt_uris_to_allowlist, apt_sources: (for a boot-time install; union+dedup with the bake file's), claude.*, github.*, env.* (all three sub-keys; env.copy and env.files are boot-ONLY and abort in a bake file).

Layering semantics

The effective config is the union of all four files (compose each tier's bake+boot, then merge global under repo):

  • Scalars (cpus, mem, guest_image, image.root_headroom_mb [bake], repo.mount, repo.copy_back, proxy.*, claude.version, claude.renderer, update_at_boot, add_apt_uris_to_allowlist, claude.permission_mode, claude.plugins.update_at_boot, claude.plugins.add_marketplace_uris_to_allowlist, github.auth): repo overrides global; global fills gaps; a hardcoded default applies only when neither layer sets the key.
  • Scalar maps (claude.plugins.enabled, env.set): repo overrides global per key — each entry follows the scalar repo-wins rule independently, so a repo can flip one plugin's enabled state, or one environment variable's value, without restating the global map.
  • Lists (bake file: packages, apt_sources, claude.marketplaces, claude.plugins.bake; boot file: egress.allow, mounts, packages, apt_sources, claude.marketplaces, claude.permissions.allow, claude.permissions.ask, claude.permissions.deny, claude.plugins.install_at_boot, env.copy, env.files): merged — the union of global + repo entries, de-duplicated. apt_sources and claude.marketplaces are allowed in both file types; each is unioned and deduped by name, and the same name with DIFFERING content ({repo, key_url} / url) aborts the launch (no silent shadowing).
  • Placement guard: claude.plugins is the one map that legitimately appears in both file types, so a sub-key in the wrong file aborts the launch with a message naming the file that carries it — bake belongs in the bake file (it changes image bytes), and install_at_boot / update_at_boot / add_marketplace_uris_to_allowlist / enabled belong in the boot file. A presence test, so a misplaced sub-key written empty (a valueless bake:, or bake: [] / "" / {}) aborts exactly like a populated one. env has the same shape and its own guard: env.set is allowed in both file types, while env.copy and env.files are boot-only and abort in a bake file — a presence test, so an empty or valueless env.copy: aborts too. See Guest environment variables below for why.

Keys

# The keys below are grouped by which FILE they live in (bake vs boot). A key
# in the wrong file loudly does nothing rather than silently poisoning the cache.

# --- BOOT file keys (config-boot.yml -- run-time; never rebuild the image) ---
cpus: 4
mem: 8192
guest_image: /path/to/guest.raw   # repo may override; SET = used verbatim
                                  # (opts out of image-identity derivation);
                                  # UNSET = derived guest+global<hash>.raw
                                  # (no repo-bake file) or
                                  # guest+global<hash>+<reponame>-<repohash>.raw
                                  # (repo ships a config-bake.yml)

repo:
  mount: clone                    # clone (default) | live
  copy_back: local                # local (default) | none

# Boot-time apt: a flat `packages:` LIST installed AT BOOT (through the proxy,
# blocking, before claude starts -- issue #106); update_at_boot runs
# `apt-get update && upgrade`; add_apt_uris_to_allowlist derives apt egress;
# apt_sources here feed a boot-time install (union+dedup by name with the bake
# file's; a baked name is not re-rendered). Use install-at-boot packages for
# things that change often (e.g. the AWS SDK/CLI) so they stay fresh without a
# rebuild. This requires `apt` in the guest, which mkosi does not provide for
# free -- so `apt` is baked into every guest image's base Packages= list
# unconditionally. The guest's baked apt sources are binary-only (main + updates
# + security, no deb-src/debug/Translations -- issue #106 real-run fix) to keep
# the per-boot apt working set small; boot_apt_phase ends with `apt-get clean`.
# The proxy that covers boot-time apt ALSO covers a mid-session interactive
# apt-get: run.env exports lowercase http_proxy/https_proxy/no_proxy alongside
# the uppercase forms (apt honors only lowercase; curl ignores uppercase
# HTTP_PROXY for plain http://), and the boot launcher writes a persistent
# /etc/apt/apt.conf.d/99claude-vm-proxy so proxying does not depend on a shell
# re-sourcing run.env.
packages:                         # (in config-boot.yml) apt packages installed
  - awscli                        # AT BOOT, through the proxy (a flat list)
update_at_boot: true              # apt-get update && upgrade at boot (default true)
apt_sources: []                   # (boot) third-party repos a boot-time install
                                  # pulls from: {name, repo, key_url}
add_apt_uris_to_allowlist: auto   # auto (default) | always -- adds
                                  # deb.debian.org/security.debian.org +
                                  # apt_sources hosts to guest egress iff
                                  # boot-time apt work is configured (auto),
                                  # or unconditionally (always)

# --- BAKE file keys (config-bake.yml -- image bytes; editing rebuilds) ---
# In config-bake.yml, `packages:` is a flat LIST BAKED into the image (present
# with no boot-time network), `apt_sources:` are rendered into the image at
# build time, and image.root_headroom_mb sizes the root partition. The image
# cache key + filename is a WHOLE-FILE, RAW-BYTE hash of the bake files -- no
# key-picking, no canonicalization -- so editing a bake file (including only its
# trailing newline, the documented force-rebuild lever) rebuilds the image;
# editing a boot file never does. A repo that ships a config-bake.yml gets its
# OWN image (its name in the filename); a repo without one shares
# guest+global<hash>.raw.
#
# packages:                       # (in config-bake.yml) apt packages BAKED in
#   - jq
#   - ripgrep
# apt_sources: []                 # (bake) third-party repos rendered at build time
#
# image.root_headroom_mb: extra MiB of FREE SPACE the guest root filesystem is
# sized ABOVE its base content (default 1024, repo overrides global). Real-
# hardware testing hit ENOSPC twice in one short session on a tight-fit-sized
# root -- boot-time apt working set + ordinary session growth both eat into a
# root with zero margin. 1024 MB is roughly 20x the observed short-session
# growth. It is a BAKE key: changing it changes the bake-file hash and triggers
# a rebuild.
image:
  root_headroom_mb: 1024

# Marketplaces + BAKED plugins (BAKE file). The image build runs the
# host-verified guest `claude` binary inside the build container with HOME
# pointed at the image root and drives its own CLI (`claude plugin marketplace
# add` / `claude plugin install`), so the image ships a real
# /root/.claude/plugins that loads with NO marketplace egress at boot. A failed
# add/install FAILS THE BUILD rather than shipping an image without them --
# for the marketplaces declared HERE and every `bake:` ref. A marketplace
# declared only in the boot file is pre-registered as an optimization, and a
# failure there only warns (the guest adds it at boot).
# Placement here (not in the boot file) is what puts these under the whole-file
# image-identity hash; writing `claude.plugins.bake` into a boot file aborts the
# launch. Prefer an explicit https:// url over the `owner/repo` shorthand so the
# launcher can derive the marketplace's egress host. Shown commented out, like
# the bake `packages:`/`apt_sources:` above, because the boot file's own
# `claude:` map follows below and one document cannot carry both.
#
# claude:
#   marketplaces:
#     - name: thevoskamps
#       url: https://github.com/TheVoskamps/claude-plugins-marketplace.git
#   plugins:
#     bake:
#       - block-background-agents@thevoskamps
#       # COMPILED HOOKS NEED NO TOOLCHAIN: the guardrails permission-gate
#       # ships prebuilt, committed binaries (one per <goos>-<goarch>,
#       # including the guest's linux-arm64), so baking it requires nothing
#       # in this file's `packages:` -- no `golang`, nothing.
#       # - guardrails@thevoskamps

# --- BOOT file keys, continued ---
claude:
  version: stable                 # stable (default) | latest | <pinned>
                                  # host-side GPG-verified cache key
  renderer: classic               # classic | fullscreen | (unset)
                                  # terminal renderer on the interactive
                                  # console; unset uses claude's own default
  remote_control: false           # true | false (default) | (unset)
                                  # opt-in Remote Control: true adds
                                  # --remote-control + a date-stamped --name
  permission_mode: bypassPermissions   # bypassPermissions (default) | default
  permissions:
    allow: []
    ask: []
    deny: []
  marketplaces: []                # {name, url} entries. Allowed in BOTH file
                                  # types (like apt_sources); `name` must match
                                  # the marketplace's OWN manifest name. One
                                  # declared HERE only has to be reachable from
                                  # the GUEST -- a url the image build cannot
                                  # reach warns and is added at boot instead.
  plugins:
    # bake: lives in the BAKE file -- see the bake-file block above.
    install_at_boot: []           # plugin@marketplace refs installed at boot
    update_at_boot: true          # refresh marketplaces + update the installed
                                  # plugins at boot (default true). This is the
                                  # freshness path for BAKED plugins: they are
                                  # frozen at build time and the image-identity
                                  # hash excludes marketplace HEAD, so a
                                  # marketplace bump lands at the next boot with
                                  # no rebuild.
    add_marketplace_uris_to_allowlist: auto   # auto (default) | always
    enabled:                      # OPTIONAL map, plugin ref -> boolean,
                                  # mirroring settings.json's enabledPlugins.
                                  # Every bake/install_at_boot ref defaults
                                  # enabled; list an entry only to override
                                  # (false = installed-but-disabled). Keys must
                                  # name an installed ref; values must be
                                  # boolean; a typo aborts the launch.
      show-loaded-rules@thevoskamps: false

proxy:
  cmd: "<forward-proxy launch command>"   # must read
                                          # $CLAUDE_VM_EGRESS_ALLOWLIST
  port: 3128
  host_alias: 192.168.127.254

egress:
  allow:                          # outbound hosts permitted via the proxy
    - api.anthropic.com
    - github.com
    - claude.ai

mounts:                           # extra mounts beyond the repo auto-mount
  - source: ~/.claude/policy      # ALWAYS read-write -- see below
    tag: policy
  - source: ~/datasets/foo
    tag: data
  - source: ~/.gitconfig          # a single FILE works too
    tag: gitconfig
    path: /root/.gitconfig        # optional guest mountpoint override

github:
  auth: none                      # none (default) | host-token

# Guest environment variables (issue #135). `set` is allowed in BOTH file
# types; `copy` and `files` are BOOT-ONLY and abort in a bake file (they read
# the HOST environment at launch, which does not exist at build time, and
# their values must never become image bytes). See "Guest environment
# variables" below for the precedence chain and the egress pairing.
env:
  set:                            # explicit literals; NON-SECRET only (these
    FOO_ENDPOINT: https://foo.internal/v2   # values ARE committed config)
  copy:                           # NAMES read from the environment claude-vm
    - OPENROUTER_API_KEY          # is launched from; an unset/empty one aborts
    - TAVILY_API_KEY
  files:                          # host .env files parsed at launch; a later
    - ~/.config/foo/prod.env      # file wins over an earlier one
  • egress.allow is written to a newline-delimited file whose path is exported as CLAUDE_VM_EGRESS_ALLOWLIST. When proxy.cmd is unset, the launcher defaults to the bundled tinyproxy launcher (payload/proxy/tinyproxy-launch.sh), which reads that file and binds CLAUDE_VM_PROXY_PORT. A proxy.cmd override must likewise read that file instead of a hand-maintained allowlist baked into the command.

  • mounts generates the extra virtio-fs device flags, and the guest mounts each one at path: (default /mnt/<tag>) before claude starts. A leading ~ in source expands to $HOME. Both source and tag are mandatory per entry — the guest mounts each share by its tag, so an entry with an empty or omitted tag: is a share nobody can mount and two of them would collide on one tag.

    Every extra mount is read-write, and pierces the VM isolation boundary for that one path. Guest writes land on the host path live — no copy-back step, no review, no undo (repo.copy_back governs the repo mount only). Everything else about the VM still holds; that one path is simply outside it, on purpose.

    There is no read-only option, and no mode: key. Read-only cannot be enforced on this stack: vfkit's virtio-fs device has no read-only export (it rejects readOnly/readonly/ro as unknown option keys — verified against vfkit v0.6.4), and the guest session runs as root, so a guest-side ro is undoable from inside the guest. A config that still sets mode: aborts the launch rather than having the key ignored, so nobody believes a share is read-only when it is not. Enforced read-only at the hypervisor boundary is tracked as issue #233. Never point a mount at anything you would mind an autonomous agent rewriting; to give the guest read access to something you care about, mount a disposable copy.

    A single file source works as well as a directory: virtio-fs shares directories only, so the launcher wraps the file in a per-entry directory (hard-linking it, so writes still reach the host file) and the guest bind-mounts just that one file onto path:. Nothing else from the file's real parent directory reaches the guest. A hard link cannot cross volumes: the wrap directory sits in the run dir, and a file on another volume aborts the launch — mount its directory instead. A caveat a directory mount does not have: the kernel refuses a rename(2) onto a file bind mount with EBUSY, so a single-file mount takes in-place edits but not the write-a-temp-then-rename pattern git config, sed -i and most editors use. Mount the containing directory when the guest needs to replace the file.

    Every mistake aborts the launch at config load rather than booting a VM without the mount you asked for: a missing source/tag, a source that is not on the host, a directory source whose path carries a ,, a tag that is reserved (repo/runconfig/claudebin/claudecreds), outside [A-Za-z0-9._-], repeated, or unusable in the tag's other roles (see below), a mode key, and a path that is relative, carries .., overlaps one of claude-vm's own guest mountpoints — landing on one, above one (/mnt, /) or inside one (/mnt/repo/sub) — shadows a guest OS path, or duplicates another entry's. The diagnostic names the entry by its position in the merged boot config — mounts is a union list, so that number counts through the global entries before the per-repo ones and need not be the entry's position in either file on its own — and by its path when it has one.

    A tag is not only a tag, which is why the charset is necessary but not sufficient. The same string is vfkit's mountTag=, a bare argv word in the guest's mount -t virtiofs -o rw <tag> <path>, a path component in /mnt/<tag> and in both the host and guest directories a single-file mount is staged through, and a mounts.tsv field. So a tag of . or .. is rejected — it would walk one level up out of each of those trees the entry reaches, and path:'s own .. check never sees a tag-derived mountpoint — and so is a tag beginning with -, which the guest's mount reads as an option rather than as the device. ..., a..b and a-b are ordinary names and pass. The source side of the same device string is why a directory source may not carry a comma: vfkit reads it as the start of another device option. That last rule covers the mounts entries only — a repo path (or $HOME, or $TMPDIR) carrying a comma breaks the built-in shares, the EFI store, the disk, the console log or the gvproxy socket the same way and is not checked; the launch fails loudly on the argument rather than booting, and payload/README.md → The tag is not just a tag records why it is left there. The one such path this feature adds — the single-file wrap directory ($RUN/mount-wrap) — is checked: the launcher aborts on a comma there when it wraps a file, naming the run dir. That is an earlier, cause-naming abort rather than a rescue; the other arguments break the same launch anyway.

    Those checks run on a normalized path:, so a mount cannot dodge them by respelling its mountpoint: repeated slashes, a trailing slash and . segments in any position (/./etc, /mnt/./repo, /etc/., and /. for the guest root) are collapsed first, which is why the diagnostic names the collapsed path rather than what you wrote. A .. segment is the exception, rejected rather than resolved — where it lands depends on the guest's filesystem, which the host cannot read.

    The guest OS's own paths are protected, by shape. They are /bin /boot /dev /etc /home /lib (and its /lib32, /lib64, /libx32 spellings), /proc /root /run /sbin /sys /tmp /usr /var — CLAUDE_VM_GUEST_SYSTEM_PATHS in payload/lib/config.sh is the one authoritative list. Linux stacks a mount, so landing on one hides the image's own files for the whole session, and the mount phase runs first, so the breakage surfaces later as something unrelated. A directory source may not land on, above or inside one of those paths — use /mnt/<tag> (the default), /srv or /opt. A single file may not land on or above one, and may sit inside only /root, /home or /tmp, which is what makes path: /root/.gitconfig legal while path: /etc/ld.so.preload is not. The guest checks as well, since only it can see the image: a mountpoint that already exists and is non-empty, or a single-file target that exists at all, is warned about on the boot console and skipped rather than mounted over.

  • claude.version selects which claude binary the host-side verified cache fetches: stable (default), latest, or a pinned version (2.1.172). The host resolves a channel to a concrete version, downloads that version's GPG-signed manifest, verifies the signature against the operator's pinned key, checksum-verifies the binary, caches it keyed on the version, and shares it into the guest, where the image's fstab mounts it ro. A failed gpg --verify or a checksum mismatch aborts the launch. On a warm boot (already cached), the launcher drops claude.ai / downloads.claude.ai from the guest egress allowlist. See the payload README's "Verified claude cache" section for the operator's one-time key-import step.

  • claude.renderer selects the in-guest claude's terminal renderer on the interactive console (the vfkit stdio byte pipe). Both renderers work over the console — this is a preference, not a workaround: classic disables the alternate-screen buffer (CLAUDE_CODE_DISABLE_ALTERNATE_SCREEN=1), fullscreen forces the flicker-free fullscreen renderer (CLAUDE_CODE_NO_FLICKER=1), and leaving it unset passes nothing so claude uses its own default. The launcher writes the matching CLAUDE_CODE_* var into run.env. An unrecognized value aborts the launch.

  • claude.remote_control is an opt-in boolean (default false/unset). When true, the launcher injects --remote-control into the in-guest claude invocation (unless the CLI args already carry it) and, when Remote Control is in effect but no --name was given, appends a date-stamped --name (format like Jul10-14:30). When false/unset, claude runs without Remote Control and the CLI args pass through unchanged. Accepts true/false (or unset); any other value aborts the launch. This is the config-driven equivalent of passing --remote-control on the command line — see the interactive-session section below.

claude.permission_mode, claude.permissions.*, claude.plugins.bake / .install_at_boot (as enabledPlugins), and claude.plugins.enabled are consumed by the guest settings.json render (issue #104) — the launcher renders /root/.claude/settings.json host-side and shares it into the guest (see "Guest Claude settings.json" below). (There is no schema translation: the launcher merges the two bake files into one bake document and the two boot files into one boot document, and every reader consumes its tier's document at the file-schema path — a key set per the documented schema is always read.) The bake document's packages: and apt_sources: are consumed by the guest-image build (issue #105 — see "Guest image" below). The boot document's packages:, update_at_boot, and add_apt_uris_to_allowlist are consumed by the guest boot launcher's boot-time apt phase (issue #106 — see "Boot-time package install/update" in payload/README.md). The bake document's claude.marketplaces + claude.plugins.bake are consumed by the image build's plugin bake step, and the boot document's claude.plugins.install_at_boot / .update_at_boot / .add_marketplace_uris_to_allowlist by the guest boot launcher's plugin phase (issue #107 — see "Marketplaces and plugins" below). The remaining key (GitHub token seeding) is schema + merge only as of issue #103 — that consumer lands in a sibling slice under #39. It resolves correctly through payload/lib/config.sh today; nothing downstream reads it yet.

  • The bake file's packages: (baked into the image) vs. the boot file's packages: (installed at boot, blocking, before claude starts, through the proxy) — the containing file's tier is what makes each a build-time bake or a boot-time install (this replaces the old single-file packages.bake / packages.install_at_boot key split; each tier's merged document keeps its own flat packages: list, read as written). Both union global + repo entries. The baked packages are present in the guest with no boot-time network, and the image is cached per whole-file bake hash (see "Guest image" below). The boot-install list runs apt-get -y install <list> at boot (issue #106): use it for packages that change often (e.g. the AWS SDK/CLI) so they stay fresh without an image rebuild; a failed install warns loudly and continues to claude rather than blocking the session.
  • The boot file's update_at_boot (default true) runs apt-get update && upgrade at boot, through the proxy, before claude starts (issue #106); a failed update warns loudly and continues. apt_sources (allowed in BOTH files; union, deduped by name; conflicting content under one name aborts) adds third-party apt repos as {name, repo, key_url} entries. A bake file's apt_sources are rendered at image-build time (issue #105 — baked into the mkosi sandbox tree so baked packages from that repo install at build time). A boot file's apt_sources (minus any name already baked) are rendered at boot time into the guest's live /etc/apt whenever the boot packages: install list is nonempty (issue #106 — reusing the exact same keyring-fetch + sources.list.d-write shape, ported to plain bash since the guest has no python3/jq).
  • The boot file's add_apt_uris_to_allowlist (auto default | always) controls whether deb.debian.org + security.debian.org + every apt_sources host are added to the guest's egress allowlist. auto adds them only when boot-time package work needs them (the boot packages: install list nonempty, or update_at_boot true); with neither configured, auto derives nothing, leaving package repos unreachable — by design, for a hard-secure all-baked config. always adds them unconditionally so in-session apt-get install also works. The knob never removes URIs that scheduled boot-time work requires, and every derived addition is logged.
  • Marketplaces and plugins (issue #107). claude.marketplaces (union of {name, url}, allowed in both file types, deduped by name, conflicting urls under one name abort, and — since issue #226 — an entry with a url but no name aborts too, since the name is what every consumer matches on) declares the marketplaces the guest knows. claude.plugins.bake (BAKE file) is installed into the image at build time; claude.plugins.install_at_boot (BOOT file) is installed at boot, blocking, before claude starts.
    • The bake path runs the host-verified guest claude binary inside the build container with HOME pointed at the image root and drives its own CLI (claude plugin marketplace add / claude plugin install) — the registry format is claude's and is never hand-written. A failed add/install fails the build, so a cached image never silently lacks a configured plugin. That strictness covers what the image must carry: every bake: ref and every marketplace declared in a bake file. A marketplace declared only in a boot file is pre-registered here as an optimization, and its url only has to be reachable from the guest — a guest-local path (/mnt/repo), a private source, or an https host outside the build container's egress. A boot-declared entry warns and leaves the registration to the boot path on each of the paths that fail a bake-declared one: no url at all, a failed add, or an add that registers under a name other than the configured one (issue #226).
    • The boot path ensures any marketplace the image does not already carry, then (when update_at_boot is true, the default) refreshes the marketplaces and updates the installed plugins, then installs the install_at_boot refs. This is the freshness mechanism for baked plugins: they are frozen at build time and the image-identity hash deliberately excludes marketplace HEAD, so a marketplace bump lands at the next boot with no rebuild. A failure warns loudly on the captured console log and continues to claude. The guest image bakes git unconditionally for this phase: the claude CLI shells out to system git for every git-url marketplace operation, so without it the add/update fails (fail-soft) and update_at_boot would be inert.
    • .add_marketplace_uris_to_allowlist (auto default | always) mirrors add_apt_uris_to_allowlist: under auto, marketplace hosts are added to the guest egress allowlist only when boot-side work can actually run (a nonempty install_at_boot, a marketplace declared in the boot file that is not also bake-declared, or update_at_boot true with at least one marketplace configured). The middle test reads the declaration, not the image: the build's pre-registration of a boot-declared marketplace is best-effort since #226 and the host cannot know whether it succeeded, so the gate derives the host either way. Everything bake-declared + update_at_boot: false + auto derives nothing — and the guest still has working plugins, because the baked ones need no marketplace. Every derived addition is logged. A owner/repo shorthand url yields no derivable host (keep github.com in egress.allow yourself); the launcher says so rather than guessing.
    • Compiled hooks need no toolchain: the guardrails permission-gate ships prebuilt, committed binaries (one per <goos>-<goarch>, the guest's being linux-arm64), so baking guardrails@… requires nothing in the bake file's packages: — in particular no golang. A platform with no committed binary makes the hook fail closed (exit 2, tool call denied), never silently unadjudicated.
  • github.auth (none default | host-token) selects whether the guest is seeded with a GitHub auth token derived from the host.

Guest environment variables (issue #135)

env: is how a variable reaches the in-guest claude session — a plain non-secret setting (FOO_ENDPOINT) or a third-party API key (OPENROUTER_API_KEY, TAVILY_API_KEY) for a tool, MCP server or model provider other than Anthropic or GitHub. github.auth covers the host's GitHub token specifically and nothing else.

The tier a sub-key may be declared in follows from how its value is obtained, not from operator preference:

Sub-key Bake tier Boot tier Value source
env.set yes yes explicit literal in the config
env.copy no — hard abort yes host environment at launch
env.files no — hard abort yes host .env file at launch

A bake file's result is image bytes that persist across every run of that image; a boot file's result is shredded on exit. env.copy/env.files resolve against a host environment that does not exist at image-build time, and a value read from it is exactly the kind of secret that must never become image bytes — so only explicitly written literals are bakeable. The bake-tier abort is a presence test: an empty or valueless env.copy: aborts too, since ignoring it silently would leave you believing a host variable is forwarded into a persistent image.

  • env.set — a map of name → literal value, for non-secret settings only (these values are committed config, and in a bake file they are also image bytes). Merge: repo-over-global per key.
  • env.copy — a list of names. The launcher reads each from its own environment at launch and forwards the value, so no secret is ever written to config and the config stays committable. Keep supplying values however you already do: shell profile, direnv, op run. Union merge.
  • env.files — a list of host .env files whose NAME=value lines are parsed at launch and forwarded the same way. Union merge. Blank lines and # comments are skipped, a leading export is dropped, and a value wrapped in matching quotes is unwrapped; there is no variable expansion and no escape processing.

Precedence, lowest to highest:

bake env.set  <  boot env.files  <  boot env.copy  <  boot env.set

Within each tier, repo-over-global (per key for set, union for copy/files); within env.files, a later file wins over an earlier one. Boot beats bake throughout: bake is the image's baseline, boot is the per-launch override.

Carrier. Two, one per tier — run.env is neither and stays launcher-owned, deliberately a non-secret channel. Bake env.set is written into the image at build time and persists. The whole boot tier, including the non-secret env.set literals, rides the same transient claudecreds mount as the OAuth credential and identity seed (0600, mounted ro guest-side, shredded on exit); the guest sources it off that mount and never copies it, so no forwarded value reaches the guest filesystem. One carrier for the whole boot tier means the secret and non-secret boot paths cannot diverge.

Egress is the other half. Forwarding a key does not make the service reachable: the guest is egress-confined, so the provider's host must also be in egress.allow (openrouter.ai, api.tavily.com, …) or the proxy blocks the call and the failure is baffling. A variable name implies no hostname the way an apt source's URI does, so nothing is derived automatically — there is no add_apt_uris_to_allowlist analogue. Add the pair together.

Every mistake aborts the launch, rather than booting a guest that looks fine while lacking a key it was configured to have (which surfaces much later, deep inside a tool call, as an opaque auth error naming nothing): env.copy or env.files in a bake file; an env.copy name unset or empty on the host; an env.files path that is not on the host or does not parse; a name outside [A-Za-z_][A-Za-z0-9_]* from any source; a non-scalar env.set value, or a key left valueless (write NAME: "" for the empty string); and a name the launcher itself composes — every name in run.env (the proxy vars, CLAUDE_ARGS, the *_TAG mount vars, IS_SANDBOX, DISABLE_AUTOUPDATER, the renderer CLAUDE_CODE_* vars, the terminal geometry, the CLAUDE_VM_*_UPDATE_AT_BOOT flags) plus CLAUDE_VM_LAST_CLAUDE_STATUS — because the guest sources run.env before both env files, so such an entry would overwrite the launcher's own value (a different proxy, a renamed mount tag, a replaced claude argv) and break the boot rather than configure anything. CLAUDE_VM_LAST_CLAUDE_STATUS is the exception in the other direction — the launcher exports it long after both files, so a config entry for it would be silently overwritten instead — and refusing at load covers both. The abort message lists the whole reserved set. No diagnostic ever prints a value.

Rebuilds. No new trigger is needed: the image identity is already a whole-file, raw-byte hash of the bake files, so changing a baked env.set value invalidates the cached image and the next launch rebuilds. Editing a boot file never rebuilds.

Guest Claude settings.json (issue #104)

The launcher renders the guest's /root/.claude/settings.json host-side from the merged config and shares it into the guest over the existing transient claudecreds mount (the same one the OAuth credential and identity seed ride). The guest boot launcher installs it at $HOME/.claude/settings.json. The guest's permission and plugin surface — everything the rendered file carries — is derived from the claude-vm configs only: the host's ~/.claude/settings.json and the host's own installed plugins are never read, so the guest deliberately runs its own (possibly riskier) posture. (The host's ~/.claude working rules — the non-policy layer of CLAUDE.md, rules/, agents/, skills/ and keybindings.json — are seeded in; see Host working rules seeded into the guest below.) The rendered keys:

  • permissions.allow / .ask / .deny come verbatim from claude.permissions.* (each a unioned list).
  • permissions.defaultMode comes from claude.permission_mode (bypassPermissions default | default). Only those two values are accepted — any other aborts the launch (it is a security-posture value with no defined behavior for an unknown mode). YOLO-by-default: the VM is the isolation boundary, so bypassPermissions is the default with the deny list as backstop. The guest runs claude as root, which claude refuses in bypassPermissions unless IS_SANDBOX=1; the launcher sets IS_SANDBOX=1 unconditionally in run.env (the guest is the sandbox).
  • enabledPlugins maps every ref in claude.plugins.bake ++ claude.plugins.install_at_boot to true (de-duplicated), then the optional claude.plugins.enabled map overrides those defaults per key. enabled mirrors settings.json's own enabledPlugins vocabulary (plugin ref → boolean): false marks a plugin installed-but-disabled (re-enabling needs no reinstall — handy for toggling debug plugins like show-loaded-rules / show-loaded-skills around a specific issue). The map is validated once: every value must be boolean and every key must name an installed ref — an unknown key is a typo and aborts the launch.
  • extraKnownMarketplaces maps every configured marketplace name (the effective bake ++ boot set) to its source, in the shape claude itself writes: an https:// url renders as {"source":"git","url":…}, an owner/repo shorthand as {"source":"github","repo":…}. This key is rendered because claude plugin install was observed writing it into ~/.claude/settings.json alongside enabledPlugins — and the boot launcher copies the host-rendered file over whatever the image baked, so omitting it would drop the marketplace declarations the bake step's own CLI run wrote. Rendering it from the same effective set the bake and boot paths use keeps the three from drifting. It does not make claude self-install a missing plugin (tested directly: a home dir with only this settings.json and no ~/.claude/plugins tree installs nothing), which is why the guest's explicit ensure/install/update phase is load-bearing.

claude-vm has no own CLI flags: every post-repo argument is forwarded to the guest claude verbatim. Plugin enable/disable state is set through claude.plugins.enabled in the config files, not on the command line.

Host working rules seeded into the guest (issue #108)

The section above is the policy layer, which the guest gets from the claude-vm config rather than from the host. The operator's "who I am / how I work" layer goes the other way — it follows them into the VM. The launcher stages copies of the host's ~/.claude/CLAUDE.md, rules/, agents/, skills/ and keybindings.json onto the same transient claudecreds mount the credential, identity seed and rendered settings.json ride, and the boot launcher copies them additively into the guest's ~/.claude/: a directory is merged into whatever is already at that path (the image's baked plugins/ is untouched) and a same-named file is overwritten. CLAUDE.md and rules/ travel together because the former references the latter as @~/.claude/rules/*.md.

There is no config key for this — the list is fixed in the launcher and spelled again in the boot launcher it emits, so adding an entry is a deliberate edit on both sides of the seam. And it is an include list: a host ~/.claude accumulates directories claude-vm has never heard of, and an exclude list would leak every future one by default. Nothing else is copied. Not the policy layer (settings.json is rendered, plugin state is config-driven), and not host-scoped session state — projects/ (keyed by host paths the guest does not have), history.jsonl, todos/, sessions/, logs/, statsig/, shell-snapshots/, ide/, teams/, usage-data/.

Your host files are never touched: what the guest sees is a copy, staged under umask 077 in the run's shred-on-exit credential dir. Symlinks are dereferenced, so a ~/.claude that is a checkout with rules/ or skills/ symlinked out of it still seeds real content rather than a dangling link. Every entry is optional — a host with no keybindings.json and no global CLAUDE.md launches normally and silently. A copy that fails prints a warning from the side that attempted it — on the launcher's stderr when the host cannot stage the entry (which then never reaches the guest at all), in the guest's hvc0 diagnostic log when the guest cannot install it — and the launch continues: unlike the credential and settings.json, no copy failure in this layer aborts a boot. The guest half therefore guards every command it runs on an entry, its mkdir -p as much as its copies, since the boot launcher runs under set -euo pipefail.

A failed entry is also dropped, not left half-copied: cp -R keeps going past a per-file error, and a partial rules/ tree is worse than an absent one. The guest can only drop what this seed created, so a destination that already existed in the image is left alone — with a warning that it may now hold a partial copy — rather than having baked content deleted under it.

Interactive session (the launching terminal IS the in-VM claude)

claude-vm <repo> opens an interactive Claude Code session on the launching terminal — the terminal becomes the guest's hvc1 console and you drive the full REPL inside the micro-VM (detached clone + egress proxy). This is the product goal; headless one-shot is not. Pass --remote-control --name <n> straight through (claude-vm <repo> --remote-control --name foo) and the same session is also Remote-Control-attached for AFK observation/replies — those flags reach the in-guest claude via the existing CLAUDE_ARGS plumbing; no extra transport is involved.

Ways to turn on Remote Control:

  • Per-launch, via CLI — pass --remote-control (and optionally --name <n>) after the repo path, as above.
  • Opt-in by config — set claude.remote_control: true in the global or per-repo config. The launcher then injects --remote-control for you (without duplicating it if you also pass it on the CLI). Either way, if Remote Control is in effect but you gave no --name, the launcher appends a date-stamped --name (format like Jul10-14:30) so the run is named — matching the date-stamp default this skill documents. A user-supplied --name (in either --name <v> or --name=<v> form) is never overridden. Arbitrary CLI args survive verbatim: the launcher quotes CLAUDE_ARGS per-argument into run.env and the guest boot launcher reconstructs the exact argv, so a value like --name "foo #7 micro-vm" (with spaces and a #) round-trips intact.

Topology: vfkit attaches two virtio-serial consoles. The first (logFilePath, guest hvc0) captures all kernel/systemd boot output to $CLAUDE_VM_STATE_DIR/logs/<run-id>/guest-console.log (preserving the observability from the guest-console capture); the second (stdio, guest hvc1) bridges the launching terminal. The guest runs claude as the login program of an autologin serial-getty@hvc1, so claude is the session with no shell in between. Boot diagnostics stay on hvc0 (off your terminal).

Because the stdio console is a byte pipe that needs a real controlling TTY on the host, launch claude-vm from a real terminal, not from a pipe. The console carries no live window-resize channel, so the launcher seeds the guest tty geometry once from the host's stty size at launch; there is no live resize.

Repo mount strategy (repo.mount)

How the repo is made available RW to the guest:

  • clone (default): git clone --no-hardlinks the repo into a persistent worktree, mounted RW. The guest never touches the live working tree or .git. The worktree lives under $CLAUDE_VM_RUNS_DIR/<runid>/worktree — the runs root, runs/ under the state root lib/config.sh resolves — whether or not the argument is a git repo. It persists after the run so the companion diff/apply skills can inspect and extract results; they find this repo's runs by the repo_src line of each run's run.meta.
  • live: mount the live repo dir RW directly. More convenient, less isolated. Opt-in.

Getting work back out (clone mode)

After the guest exits, the launcher runs copy-back to the local source by default (repo.copy_back: local). Set repo.copy_back: none to disable it and extract manually. The three companion skills handle extraction explicitly:

  • /claude-vm-diff — read-only: show what changed in the VM worktree vs. the local source.
  • /claude-vm-apply-local — apply the VM worktree's changes to the local source.
  • /claude-vm-apply-remote — push the VM worktree's changes to the remote.

Reaping a run whose launcher has exited

A launcher killed with kill -9 (or a crash, or a closed terminal) never runs its exit trap, and its run dir keeps its guest-image clone. Each launcher holds a lockf lock on $RUN/run.lock for its lifetime, and no process it leaves running holds it, so a dead launcher is a dead run. A watcher the launcher starts beside vfkit waits on that lock and, the moment the launcher dies, stops vfkit, gvproxy and the proxy — so a kill -9 of the launcher stops the VM too. The watcher signals those three pids, and the launcher's own exit trap the gvproxy, proxy and watcher pids, only while each still carries the start time recorded for it at launch. bin/claude-vm-cleanup, run by hand, reaps the rest for every repo at once: it reaps only a run whose lock it can take, whether that run exited normally or crashed — killing the pids its run.meta records (vfkit_pid, gvproxy_pid, proxy_pid, a backstop for a watcher that was killed as well) while each still carries the start time recorded beside it, so a pid since taken by another process is never signalled, and removing its gvproxy socket dir, its creds/ dir (the OAuth credential and identity seed), any raw Keychain blob (.keychain-blob.raw.json) and its guest-clone.raw — and leaves every live run alone. It keeps the run dir, worktree/, run.meta and run.lock included, so the companion skills still find the run, and it never removes $CLAUDE_VM_STATE_DIR/logs/, where each run's console, gvproxy and proxy logs and egress capture are kept. It reports each run it reaped, with its log dir and kept worktree, or spared.

Guest image — built on demand, version-pinned, claude verified host-side

Claude Code updates daily, so the guest image does not bake in claude:

  • The baked image is a stable base: a pinned OS plus a boot launcher that, on boot, loads the run environment and then runs the host-side GPG-verified claude binary mounted RO at /mnt/claudebin against the repo at /mnt/repo, as an interactive session on the hvc1 console (issue #88). claude is never baked in and never fetched-and-run inside the guest (no curl install.sh | bash anywhere — there is no such fallback); the host fetches, verifies, and caches it (see "Verified claude cache" in the payload README). The base only changes when the base OS pin or the launcher logic changes — not when claude does.

  • The base is version-pinned in payload/build-guest-image.sh (BASE_OS_REV + LAUNCHER_LOGIC_REV; never the claude version).

  • Baked packages (issue #105, re-keyed by #179). A bake file's packages: and apt_sources: ARE baked into the image (unlike claude): the baked packages are present in the guest with no boot-time network, and each apt_sources repo's key_url is fetched into a keyring so its packages install (signed-by that key) at build time. An apt_sources entry's repo may already carry its own apt one-line [options] block (e.g. an operator-authored signed-by=); the renderer adapts to the line's existing shape instead of unconditionally appending a second [options] block (apt allows only one, and two make the line unparseable) — no block gets one added, a block without signed-by= gets it merged in, and a block that already pins signed-by=<path> is left verbatim with the fetched key written to that path's staging equivalent. Baked packages: entries that are null/empty (e.g. a stray - in the YAML list) are stripped during the build render rather than baked in as a literal "None" package name.

  • Immutable base + whole-file image identity (issue #179). The image cache key + filename is a whole-file, raw-byte hash of the BAKE files — no key-picking, no canonicalization. Placement of a key in a bake file IS the classification, made once by the operator: a knob in the wrong file loudly does nothing instead of silently poisoning the cache. Because the hash is over raw bytes, list order, key order, whitespace, and even a trailing-newline toggle all change it — the trailing-newline toggle is the documented force-rebuild lever. The shape:

    • a repo without a .claude-vm/config-bake.yml shares one image keyed on the GLOBAL bake file's hash: guest+global<hash>.raw, version BASE_OS_REV+launcherN+global<hash> (an absent global bake file hashes to the 00000000 sentinel);
    • a repo that ships a .claude-vm/config-bake.yml appends its own segment — the repo NAME plus a hash of the repo bake file — guest+global<hash>+<reponame>-<repohash>.raw, so the filename tells you whose override runs where. The repo segment's PRESENCE is gated on the bake FILE existing (not its content), so two repos with byte-identical repo-bake files still get two images (the name disambiguates): legibility over dedup, an explicit choice.

    Editing a boot file never changes identity and never rebuilds; editing a bake file (including only its trailing newline) does. The guest_image scalar, when set, opts out of identity derivation and is used verbatim.

    The cached base .raw is immutable and is NEVER attached to a VM: each run APFS-clones it (cp -c, instant zero-copy) into the run dir and boots the CLONE. N concurrent sessions cost one base plus each session's written blocks — no cross-session/cross-repo state leakage (OAuth credential, identity seed, transcripts, boot-installed packages) and no multi-writer corruption on a shared image. The clone is discarded on a clean exit and retained (path logged) on an abnormal one for forensics. There is no host-driven forced stop: the guest halts itself and vfkit (running foreground) exits on its own, so the launcher's sync in cleanup simply narrows the window in which writes in flight to the clone are still unflushed when the guest goes away.

  • Ending a session (issue #179). The guest decides its own fate from claude's exit status; there is no host→guest shutdown channel.

    • A deliberate quit powers the guest off. Ctrl-D Ctrl-D, /exit, and Ctrl-C Ctrl-C all exit claude 0, and on 0 the guest starts systemd's ordered poweroff (SIGRTMIN+4 to PID 1 — the bus-less path, so no spurious "Failed to connect to bus" error on a guest that ships no dbus). vfkit then exits on its own, control returns to the claude-vm launcher on the host, your terminal is restored, the per-run clone is discarded, and the copy-back step runs. This is the normal way to end a session — nothing on the host needs to be killed.
    • Ctrl-C belongs to the guest claude. The launcher disables isig/ixon on the host tty for the session, so Ctrl-C (and Ctrl-Z/Ctrl-\/Ctrl-S/Ctrl-Q) travel to the guest as bytes instead of signalling host-side vfkit — the first Ctrl-C shows claude's press-again warning, the second exits 0 and powers off, same as Ctrl-D Ctrl-D. Consequence: the keyboard cannot abort a wedged guest from that terminal; the recovery path is kill <vfkit pid> from another terminal (vfkit tears the guest down within ~5s and the launcher cleans up normally). The saved tty state is restored on every exit path.
    • An abnormal claude death drops you into a guest shell. If claude exits nonzero (a crash, an OOM kill, or declining the bypass-permissions dialog — the easy way to try this path), the guest does not power off yet. The boot launcher hands you an interactive root login shell on the same console you were already attached to, so you can run a post-mortem inside the still-running guest: inspect /mnt/repo, see how the clone diverged, read dmesg, check whether the network wiring survived. claude is not relaunched — there is no respawn loop. Exiting that shell powers the guest off and returns control to the host launcher; the clone is retained (its path is logged) for further forensics.
  • Boot-time package install/update (issue #106). A boot file's packages: (install list) and update_at_boot do not feed the image-identity hash — they run a blocking phase in the boot launcher itself, right before claude launches, through the same proxy the rest of the guest's egress goes through. The base image DOES need one thing unconditionally to support this phase: apt itself, baked into the base Packages= list regardless of whether install_at_boot/update_at_boot are configured (mkosi does not otherwise put apt/dpkg tooling into the guest rootfs, since it installs baked packages from OUTSIDE the image with its own build-container apt) — this is covered by LAUNCHER_LOGIC_REV, the base-version pin, not by the image-identity hash. See "Boot-time package install/update" and "Mid-session apt proxying, metadata diet, and root headroom" in payload/README.md for the full mechanics (the reused render_apt_source shape, the proxy -o Acquire::*::Proxy= flags and persistent apt.conf.d drop-in, the apt metadata diet, apt-get clean, the failure policy, and the add_apt_uris_to_allowlist derived-egress gate).

  • On startup, the launcher ensures the image exists and matches the pinned version. If the resolved image is missing or version-mismatched, it builds the image (payload/build-guest-image.sh --output …, passing the merged bake config through CLAUDE_VM_BAKE_CONFIG and the pre-computed image-identity segments through CLAUDE_VM_IMAGE_IDENTITY_SEGMENTS) rather than erroring. The image's pinned version is stamped at <image>.version.

  • No image artifact is committed to the repo, and there is no publish-prebuilt-image path. Every machine builds its own.

The provisioning step that produces the bootable raw image defaults to the bundled payload/provisioners/podman-mkosi.sh: mkosi run inside a throwaway rootless podman container (Debian Trixie build container, systemd ≥ 254 for the offline, loop-device-free RepartOffline=yes path), emitting a raw EFI-bootable Debian guest with the boot launcher wired as the autologin serial-getty@hvc1 login program (so claude becomes the interactive hvc1 console session — issue #88), plus an unlocked passwordless root (RootPassword=hashed:). vfkit boots it --bootloader efi. build-guest-image.sh pins the version and emits the boot launcher, then hands <boot-launcher-path> <output-image-path> to the provisioner. The CLAUDE_VM_IMAGE_PROVISIONER env var overrides the bundled default with your own script honoring the same two-argument contract.

The launcher captures the booting guest's boot serial console (hvc0) to $CLAUDE_VM_STATE_DIR/logs/<run-id>/guest-console.log via the first vfkit --device virtio-serial,logFilePath=…. The recipe KernelCommandLine sets console=hvc0, so all kernel/systemd boot output — and the boot launcher's diagnostic/seam lines, which it writes explicitly to /dev/console — are observable from the host instead of being discarded, while staying off the interactive hvc1 terminal. The path is reported on exit and retained in the run's log dir, beside the gvproxy and proxy logs and the egress capture, where reaping the run does not reach it.

Authentication (secrets)

This section covers the two credentials the launcher handles itself: the host's claude.ai OAuth credential, and (under github.auth: host-token) a GitHub token. Any other third-party key — an OpenRouter or Tavily key for an in-guest tool, MCP server or model provider — reaches the guest through env.copy / env.files instead; see Guest environment variables above, which carries the same "never in config, never in run.env, shredded on exit" posture.

The guest authenticates claude with the host operator's live claude.ai OAuth credential — the full-scope login credential, not a scoped inference token — installed at $HOME/.claude/.credentials.json. That bearer token alone is not sufficient for the interactive TUI to treat itself as onboarded and logged in: current Claude Code also reads onboarding + identity state from ~/.claude.json, which a fresh throwaway guest lacks — so without it every launch hits the onboarding/login wall despite the mounted credential. Two keys matter beyond identity: hasCompletedOnboarding (absent → claude runs its onboarding flow) and autoUpdates (unset → claude tries to self-update and fails against its RO-mounted binary in the egress-confined guest).

So the launcher also seeds the guest's identity + onboarding state (issue #88): it reads your host ~/.claude.json and emits a seed carrying userID and oauthAccount selected from the host, plus four synthesized keys: hasCompletedOnboarding: true (skip the wall), autoUpdates: false (no self-update), and lastOnboardingVersion / lastReleaseNotesSeen stamped with the concrete resolved claude version. It additively carries benign host UI keys when present — installMethod, hasSeenTasksHint, hasUsedStash, tipsHistory (each silently omitted when absent) — and seeds a projects entry for the guest mount (/mnt/repo) with hasTrustDialogAccepted / hasCompletedProjectOnboarding forced true so the guest skips the "Do you trust this folder? /mnt/repo" dialog (if the host already has an entry for the launched repo, a named allowlist of benign per-project keys — allowedTools and friends — survives, rekeyed to /mnt/repo with those two flags forced true; the operator's prompt history, lastSessionId, and mcpServers are deliberately dropped, and unrecognized future keys default to excluded). Nothing else from ~/.claude.json (no other projects{} entries, no telemetry, no machineID) is copied; machineID is deliberately not seeded — the guest mints its own. That object is shared into the guest under the same claudecreds mount, and the guest boot launcher installs it at $HOME/.claude.json (mode 0600) before launching claude, so the in-guest session comes up already onboarded, logged in, folder-trusted, and with self-update disabled. The seed is built via lib/credential.sh's claude_vm_select_claude_json_seed (using python3; unit-tested in payload/test/credential-test.sh) and carries account identity, so it rides the same secret posture as the credential: written under umask 077 into the transient, owner-only (0600), shred-on-exit claudecreds mount, never into run.env or the verified-binary cache. A preflight aborts the run with an actionable message if the host ~/.claude.json is missing or lacks a usable userID/oauthAccount (i.e. you are not logged in on the host).

The launcher also quiets claude's startup install-health check (issue #88): claude probes for a working claude at the native installer's ~/.local/bin/claude, but the guest runs the RO-mounted binary from /mnt/claudebin, so that path is empty and the TUI prints two claude command at /root/.local/bin/claude missing or broken · run claude install to repair warnings. The guest boot launcher symlinks $HOME/.local/bin/claude → the verified RO-mounted binary right after the claude-fetch seam validates it; the symlink target is the running binary, so the version comparison passes by construction and autoUpdates: false plus the RO mount prevent write-through (empirically confirmed to clear the warnings on real hardware). Belt-and-braces with the seeded autoUpdates: false, the launcher also writes the documented DISABLE_AUTOUPDATER=1 env knob into run.env.

A second credential-token preflight guards against a degraded Keychain entry: the claudeAiOauth object can be structurally complete yet carry empty accessToken / refreshToken strings (with expiresAt: 0) — which happens when your host claude sessions coast on the shared auth daemon's in-memory tokens while the persisted Keychain entry has gone stale. Booting the guest with it lands at "Not logged in · Run /login", and an in-guest /login can trip OAuth reuse-detection and revoke your other live sessions. So after selecting the credential, the launcher validates both tokens are non-empty (claude_vm_validate_claude_credential_tokens) and aborts fast if not, telling you to re-login on the host (claude then /login, or restart Claude Code — either repairs the Keychain entry) rather than inside the guest.

At launch the launcher reads the credential from the macOS login Keychain by service name alone (security find-generic-password -s "Claude Code-credentials" -w). That Keychain item is not only the claude.ai login — its JSON also carries sibling keys such as mcpOAuth (per-MCP-server OAuth). To avoid mounting unrelated MCP credentials into the guest, the launcher selects only the claudeAiOauth key and writes a file in the shape claude expects, {"claudeAiOauth": { ... }} (selection via lib/credential.sh, using python3; unit-tested in payload/test/credential-test.sh). The selected credential is written to a transient, owner-only (0600) tmpfile and shared into the guest under mountTag=claudecreds, which the image's fstab mounts ro. The ro is guest-side, not host-side — vfkit's virtio-fs device has no read-only export, so the host shares this exactly as it shares an extra mount, and the same caveat applies: a guest-side ro stops an accidental write, not a determined one, since the guest session is root. Nothing rests on it — the guest boot launcher copies the file into $HOME/.claude/.credentials.json (mode 0600) before launching claude.

The credential is a secret and is handled like one: it is never written to config, to run.env, or to the verified-binary cache; its host-side tmpfile is created under a tightened umask 077 and removed by the launcher's cleanup()/trap on every exit. The full raw Keychain blob (before selection) lives only in a transient tmpfile outside the guest share and is removed immediately after selection.

Requirements: macOS only (security find-generic-password is a macOS Keychain tool; python3, used for credential and identity-seed selection, ships with macOS), and you must be logged in to Claude Code on the host first. The launcher fails fast with an actionable message if the host ~/.claude.json is missing or lacks a usable userID/oauthAccount, or if the Keychain lookup returns empty or non-zero, or the blob has no usable claudeAiOauth key. egress.allow must include the Anthropic API host (api.anthropic.com) so the in-guest claude can reach it. See the payload README's "Authentication" section for the full mechanic.

Requirements

yq (mikefarah v4+), git, python3 (stock on macOS; used to select the claudeAiOauth key from the Keychain blob — see "Authentication" above), gpg (brew install gnupg, for the host-side verified claude cache — see "Verified claude cache" in the payload README), a sha256 tool (shasum / sha256sum, both stock on macOS/Linux), and — for an actual VM boot — vfkit and tinyproxy (for the bundled default proxy.cmd). A launch that has to build the guest image is the only one that runs podman, for the bundled podman-mkosi provisioner; the podman formula is in practice a requirement of every launch regardless, because that is where gvproxy normally comes from (next paragraph). What a build does not need is a started podman machine: the launcher inits and starts one itself and stops it again at end of run if it was the one that started it (see "The launcher manages the podman machine" below). On a clean host: brew install yq git gnupg vfkit podman tinyproxy.

gvproxy is not a separate install and need not be on PATH: it ships inside the podman Homebrew formula at <brew-prefix>/libexec/podman/gvproxy and a stock brew install podman does not symlink it onto PATH. The launcher resolves it automatically (an explicit on-PATH gvproxy first, then podman's libexec), so installing podman is enough.

Before any image build, network call, or Keychain read, the launcher runs a trust-path preflight that checks the local, instant preconditions for the verified cache and credential selection up front: gpg on PATH, the claude.signing_key_fingerprint pinned in config, that pinned fingerprint actually present in the gpg keyring, and python3 on PATH. Immediately after, a separate identity-seed preflight aborts if the host ~/.claude.json is missing or lacks a usable userID/oauthAccount (i.e. you are not logged in on the host). Later, once the credential is selected, a credential-token check aborts if the selected claudeAiOauth carries empty accessToken / refreshToken (the degraded-Keychain state described under "Authentication"), steering you to re-login on the host. Each failed check prints the exact remediation command(s) (e.g. brew install gnupg, the curl … | gpg --import + gpg --fingerprint pin steps). Without this gate, a cold boot would otherwise pay for a guest-image build and three network fetches before aborting on a condition that was knowable at startup. These are an additive early gate; the deep checks in the verified cache (gpg-on-PATH and unset-pin hard-abort) and credential selection (python3) remain as defense-in-depth.

After the trust-path preflight, and still before any build/boot work, the launcher runs a dependency preflight that checks the VM toolchain up front (gvproxy resolvable, vfkit on PATH, and — only when the bundled default proxy is in use — tinyproxy). It fails fast with one actionable remediation line per missing piece rather than dying deep in the boot sequence. A custom proxy.cmd owns its own dependencies, so the tinyproxy check is skipped then.

The config-resolution half (layering, scalar/list resolution) is exercisable without the virtualization stack; see payload/test/config-test.sh, and the verified-cache logic (resolve / verify / checksum / abort / warm-boot) in payload/test/claude-cache-test.sh.

The per-run endpoint primitives (issue #179) are also exercisable without a VM: payload/test/endpoint-test.sh covers free-TCP-port acquisition and TCP/unix-socket liveness (a live listener vs a stale socket-file corpse, the exact distinction the concurrency fix turns on), using real perl listeners; payload/test/bin-config-check-test.sh regression-tests bin/claude-vm's four-file bake/boot config-presence check so it no longer prints a false "no global config" when the migrated pair is present. payload/test/cleanup-test.sh covers the run's run.lock across a kill -9 of the launcher, the watcher stopping a vfkit stand-in after one, and bin/claude-vm-cleanup over dead, live and lockless run dirs.

payload/test/podman-mkosi-test.sh regression-tests the recipe the default provisioner generates (the literal mkosi.conf and build-in-container.sh), stubbing only podman at the container handoff — added after a real end-to-end build caught failures (a backtick-command-substitution bug corrupting mkosi.conf, and a missing curl/ca-certificates in the build container) that no pure-function config-test.sh case could catch, since none of them render or execute the actual generated recipe files.

The end-to-end acceptance test — default-provisioner build, vfkit boot to the claude-fetch seam (running the host-verified claude off the mount), egress confinement, and the host-side GPG-verified cache — is payload/test/host-acceptance.sh; it is host-gated by cause: it skips cleanly when a required binary is absent, but a stopped or absent podman machine is not a skip — the test starts the machine itself and tears down exactly what it changed on exit. A bring-up the test attempted that then fails (podman machine init/start) is a real failure, not a skip: the test exits non-zero rather than green-exiting with nothing proven. Diagnostics (including the machine init/start stderr) are retained under $CLAUDE_VM_STATE_DIR/logs/<run-id>/ — the state root lib/config.sh resolves, ~/.local/state/claude-vm by default — so a failed run stays diagnosable.

payload/test/podman-machine-test.sh covers the launcher's own podman machine management (issue #215) against a stateful stub podman, and — by slicing the build-or-reuse block out of claude-vm.sh and running it — the scoping: a warm-cache launch invokes podman zero times, a build-needing one inits/starts, builds, and stops again — including when the bring-up leaves a machine up behind a failure, whether podman machine start itself exits non-zero after bringing it up or the confirmation that follows fails.

The launcher manages the podman machine

The dependency preflight deliberately checks neither the podman binary nor any machine state, because only a launch that builds the guest image runs podman. A warm-cache launch — the image on disk already stamps the pinned version — boots it with vfkit and invokes podman not once, so it neither gates on a started machine nor starts one. (The preflight does check gvproxy, which normally resolves out of podman's Homebrew formula, so a host with neither podman nor an on-PATH gvproxy still fails there.)

On the build path the launcher brings podman up itself rather than printing two commands and refusing, since claude-vm is meant to be one command on a fresh host where podman has never been initialized. The decision reads podman machine list: no machine listed gets a podman machine init then a podman machine start; a listed-but-stopped machine gets a start; a running machine is left exactly as found. At end of run the launcher stops the machine iff it was the one that started it — a machine found running is left running, and an init'd machine is stopped rather than removed, so the next build reuses it.

There is no config surface for any of this: it is launcher plumbing, not policy. Every init/start/stop is logged to stderr as it happens, and those log lines are its only trace. See the payload README's "The launcher manages the podman machine" section for the mechanic.

04 同仓库更多 Skills

TheVoskamps
TheVoskamps/claude-plugins-marketplace

mask-inappropriate-language

Replace inappropriate language (profanity, slurs, strong insults) in provided text or a file with asterisks, character-for-character, preserving everything else.

★ 0
TheVoskamps
TheVoskamps/claude-plugins-marketplace

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.

★ 0
TheVoskamps
TheVoskamps/claude-plugins-marketplace

sdlc-config-user

Interactively create or merge-update the repo user sdlc config, `<repo-root>/.sdlc/user-config.yml` (tier 3 — this user, this repo, never committed), and add it to the repo's tracked `.gitignore`.

★ 0
TheVoskamps
TheVoskamps/claude-plugins-marketplace

sdlc-config-repo

Interactively create or merge-update the shared repo sdlc config, `<repo-root>/.sdlc/repo-config.yml` (tier 2 — tracked, every user of this repo).

★ 0
TheVoskamps
TheVoskamps/claude-plugins-marketplace

sdlc-config-global

Interactively create or merge-update the global user sdlc config, `$XDG_CONFIG_HOME/sdlc/user-config.yml` (tier 1 — this user, every repo on this machine).

★ 0
TheVoskamps
TheVoskamps/claude-plugins-marketplace

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.

★ 0