darwinvm — the macOS guest VM (Elpe’s Darwin isolation primitive)

A macOS guest under Virtualization.framework is the Darwin analogue of Linux’s clone3+namespaces: the boundary a build runs in. This dir holds the Swift shims that create/boot such a guest, plus a non-interactive provisioner that makes a fresh guest boot straight to SSH with zero human interaction.

• How to use it (the current, maintained doc): WORKFLOW.md — tools, the non-interactive provisioner, the per-build lifecycle, installing the in-guest toolchain, and the virtiofs store-sharing open issue.
• How it fits the bigger picture (cross-build-from-Linux vs build-in-VM, deployment, the SDK): ../darwin.md.

Runs on germaine (Apple Silicon, macOS 26). All shims are ad-hoc signed with the com.apple.security.virtualization entitlement (vz.entitlements) — no paid Team ID needed. Build one: xcrun swiftc <f>.swift -o <f> -framework Virtualization [-framework Cocoa] && codesign --entitlements vz.entitlements -s - <f>.

Historical: the original spike (2026-08-03)

The dir started as a spike proving Virtualization.framework was usable at all: vzspike.swift booted an Alpine Linux guest to its initramfs shell (a Linux guest is a wanted use case too — cross-build Linux from a Mac). Two gotchas from that spike are still worth keeping:

• Linux kernel format. VZLinuxBootLoader needs an uncompressed arm64 Image (magic 41 52 4d 64 at offset 56); a distro vmlinuz (compressed / EFI-stub PE) fails with a generic VZErrorDomain Code=1. Extract the raw Image (find gzip magic 1f 8b 08, pipe the tail through gunzip), or use VZEFIBootLoader + a bootable disk image. vzspike-efi.swift takes the latter path.
• Entitlement. Sign with --entitlements vz.entitlements; verify with codesign -d --entitlements - <bin>. VZVirtualMachine runs on the main queue — keep RunLoop.main alive.

The macOS-guest path (vz-fetch/vz-restore/vz-provision/vz-boot, documented in WORKFLOW.md) superseded the spike; vzspike*.swift are kept as references.