feat: add macOS VM support via Apple Virtualization.framework

[rgarcia]

Summary

• Add vz hypervisor implementation using Apple's Virtualization.framework via a codesigned subprocess (vz-shim)
• vsock-based guest communication, shared directory mounts for disk access, macOS-native networking via vmnet
• Makefile targets: build-darwin, test-darwin, dev-darwin, sign-darwin
• CI: macOS runner for test-darwin
• scripts/install.sh and scripts/uninstall.sh with macOS support (launchd, Homebrew PATH, codesign)

Depends on #89 (cross-platform foundation) — merge that first, then rebase this onto main.

Test plan

• CI passes on Linux runner (no regressions)
• CI passes on macOS runner (test-darwin)
• make build-darwin && make sign-darwin succeeds on macOS
• E2E install test passes on macOS (scripts/e2e-install-test.sh)

🤖 Generated with Claude Code

---

Note

High Risk
Large cross-cutting change touching hypervisor lifecycle, process spawning/codesigning, CI, and install/uninstall scripts; regressions could impact VM startup/guest connectivity or production installs on both platforms.

Overview
Adds experimental native macOS (Apple Silicon) support via a new vz hypervisor implementation that runs VMs through a detached, codesigned vz-shim subprocess (HTTP control API + Unix-socket vsock proxy) and embeds/signs the shim + required entitlements at build time.

Updates API/instance flows to be hypervisor-agnostic for guest vsock access (handlers now call InstanceManager.GetVsockDialer), adjusts instance creation for vz-specific vsock socket paths and kernel console args, and adds macOS-focused tests/docs.

Extends tooling and distribution for macOS: new make targets (build-darwin, sign-darwin, dev-darwin, test-darwin), Darwin air config, a macOS GitHub Actions job + install E2E test, and installer/uninstaller support for macOS (launchd, macOS paths, codesigning, CLI artifact handling, Docker socket detection, optional builder image build).

^{Written by Cursor Bugbot for commit 7d29895. This will update automatically on new commits. Configure here.}

[rgarcia]

@cursor push 1353ca6

[sjmiller609]

Just nits or possible additional color, looks good

[hiroTamada]

Solid PR. Clean hypervisor abstraction, good use of build tags, thorough docs and E2E coverage. The vz-shim subprocess design (surviving hypeman restarts, CH-compatible control API) is well thought out. The API handler refactor to use GetVsockDialer is a nice decoupling.

A few minor nits inline, nothing blocking.

[hiroTamada]

nit: this silently swallows codesign failures. if signing fails, the binary won't have the virtualization entitlement and will crash at runtime with a confusing error. consider at least warning on failure instead of || true.

[hiroTamada]

nit: vz control interface is HTTP over Unix socket (matching the Cloud Hypervisor API pattern), not gRPC.

[hiroTamada]

nit: both branches set the same path (/usr/local/bin/hypeman), so the if/else is a no-op.

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{Bugbot Autofix is ON. A Cloud Agent has been kicked off to fix the reported issue.}

[cursor]

VMM shutdown may not terminate shim

Medium Severity

handleVMMShutdown returns success but only calls vm.Stop() when s.vm.CanStop() is true. If the VM is already non-stoppable (for example, it already stopped), the handler does nothing to end vz-shim, so the control process can remain alive with stale state after a shutdown request.

 

[cursor]

Bugbot Autofix prepared fixes for 1 of the 1 bugs found in the latest run.

• ✅ Fixed: VMM shutdown may not terminate shim
  • Added context.CancelFunc to ShimServer and always call it in handleVMMShutdown after attempting vm.Stop(), ensuring the shim process terminates through the existing graceful shutdown flow even when CanStop() is false.

Or push these changes by commenting:

@cursor push 1e49227e7d

Preview (1e49227e7d)

diff --git a/cmd/vz-shim/main.go b/cmd/vz-shim/main.go
--- a/cmd/vz-shim/main.go
+++ b/cmd/vz-shim/main.go
@@ -61,7 +61,7 @@
 	slog.Info("VM started", "vcpus", config.VCPUs, "memory_mb", config.MemoryBytes/1024/1024)
 
 	// Create the shim server
-	server := NewShimServer(vm, vmConfig)
+	server := NewShimServer(vm, vmConfig, cancel)
 
 	// Start control socket listener (remove stale socket from previous run)
 	os.Remove(config.ControlSocket)

diff --git a/cmd/vz-shim/server.go b/cmd/vz-shim/server.go
--- a/cmd/vz-shim/server.go
+++ b/cmd/vz-shim/server.go
@@ -4,6 +4,7 @@
 
 import (
 	"bufio"
+	"context"
 	"encoding/json"
 	"fmt"
 	"io"
@@ -19,14 +20,16 @@
 type ShimServer struct {
 	vm       *vz.VirtualMachine
 	vmConfig *vz.VirtualMachineConfiguration
+	cancel   context.CancelFunc
 	mu       sync.RWMutex
 }
 
 // NewShimServer creates a new shim server.
-func NewShimServer(vm *vz.VirtualMachine, vmConfig *vz.VirtualMachineConfiguration) *ShimServer {
+func NewShimServer(vm *vz.VirtualMachine, vmConfig *vz.VirtualMachineConfiguration, cancel context.CancelFunc) *ShimServer {
 	return &ShimServer{
 		vm:       vm,
 		vmConfig: vmConfig,
+		cancel:   cancel,
 	}
 }
 
@@ -151,7 +154,9 @@
 		if s.vm.CanStop() {
 			s.vm.Stop()
 		}
-		// Process will exit when VM stops (monitored in main)
+		// Ensure process terminates even if VM is already stopped
+		// (e.g. CanStop() returned false because the VM already stopped).
+		s.cancel()
 	}()
 }