macOS guests on Mac hosts (Lima vz, macOS 27 Virtualization) #155

Apple Silicon Macs can run macOS guests through Virtualization.framework. Lima added experimental macOS guests in v2.1 (limactl start template:macos), on the same vz driver our Lima backend already uses. So boxery could offer macOS VMs on Mac hosts: useful for agents building Xcode/iOS projects or testing Mac-specific code.

This is a non-goal today (ARCHITECTURE.md: "macOS/Windows guests"). This issue tracks whether to lift that, starting with an experimental, headless-only option on the Lima backend.

What's new from Apple (WWDC26, macOS 27)

• Guest provisioning: VZMacGuestProvisioningOptions passes a user, password, auto-login and SSH on to Setup Assistant at first boot. Host and guest must both run macOS 27.
• DiskImageKit: stacked disk images, with a shared read-only base and a copy-on-write ASIF overlay per VM. That gives cheap clones and forks. There is no snapshot API and overlays can't be merged back into the base.
• vmnet with Virtualization (macOS 26+): custom networks, DHCP settings, host port forwarding and per-VM isolation.

Unchanged: the licence caps it at two macOS VMs running at once per Mac (enforced; a third fails to start), limits use to development, testing or personal non-commercial use, and doesn't allow App Store sign-in. A guest can't be a newer macOS than its host.

What maps onto the backend contract

Lifecycle, backend_list, ssh endpoints and the guest-to-proxy path through the user-net gateway 192.168.5.2 should mostly carry over from host/backends/lima.sh.

What breaks

1. Two-VM cap. fork to 3+, pools and parallel attempts can't work. boxery needs to know the cap and fail clearly (related: Declare backend platform support, requirements, and capabilities #150, declaring backend capabilities).
2. Provisioning. USERDATA is cloud-init, and image/layers/*.sh assume apt and systemd. macOS needs its own plumbing layer: an agent user, sshd, and a launchd job in place of boxery-llm.service. Lima's macOS guest creates a ${USER}.guest user and has no passwordless sudo.
3. Desktop and computer use. XFCE, TigerVNC and xdotool don't exist there. Screenshots and synthetic input need Screen Recording and Accessibility (TCC) permissions, which can't normally be granted without someone clicking. Start headless.
4. Images. It's untested whether limactl clone copies a macOS guest's auxiliary storage and machine identifier correctly for capture/reimage. DiskImageKit would fit better, but it needs a macOS 27 host.
5. Cost. The first install downloads a ~15 GB restore image. Process-heavy work runs slower on macOS than in a Linux VM (see docs/research/2026-11-03-hunk-suite-vm-vs-macos).

Proposed next step: spike

On a macOS 26 host with Lima 2.1+, boot template:macos-26 and check:

• ssh in with a boxery-generated key and pin the host key
• guest reaches the host proxy at 192.168.5.2:$PROXY_PORT, and the Seatbelt loopback confinement still applies
• create an agent user with passwordless sudo
• limactl clone of a stopped macOS guest boots, and both copies can run together
• resize and the two-VM cap: the error a third VM gives

Then repeat on a macOS 27 host to see what the provisioning options and DiskImageKit replace.

Sources

• WWDC26 session 224: Expand the capabilities of your Virtualization app
• Eclectic Light: macOS virtualisation is leaping forward in Golden Gate
• Eclectic Light: Virtualisation on Apple silicon Macs is different
• Bitrise: WWDC26 Virtualization updates for Mac fleets
• CNCF: Lima v2.1, macOS guests
• Lima docs: macOS guests