feat: add macOS support via Virtualization.framework (vz)

[rgarcia]

Summary

Adds macOS support to hypeman using Apple's Virtualization.framework via the Code-Hex/vz library.

Key changes:

• Platform abstraction: Split Linux-specific code (resources, devices, network, vmm, ingress) into _linux.go files with stub _darwin.go counterparts
• vz hypervisor: New lib/hypervisor/vz/ package implementing Hypervisor and VMStarter interfaces
• vz-shim subprocess: New cmd/vz-shim/ binary that hosts VMs in a separate process, allowing VMs to survive hypeman restarts (mirrors cloud-hypervisor architecture)
• vz vsock proxy: Uses Cloud Hypervisor-compatible text protocol (CONNECT {port}\n → OK {port}\n) over Unix socket
• ClientFactory pattern: New hypervisor.NewClient() for uniform hypervisor client creation across all VMM types
• Guest system updates: hvc0 console support, cross-compiled binary embedding for darwin builds
• OCI image handling: Pull linux/arm64 images regardless of host platform

Architecture (vz-shim subprocess model):

┌─────────────────────────────────────────────────────────────┐
│                        hypeman                               │
│  ┌──────────────┐    ┌──────────────┐    ┌──────────────┐  │
│  │ vz.Starter   │    │ vz.Client    │    │ VsockDialer  │  │
│  │ (spawn shim) │    │ (HTTP→shim)  │    │ (vsock proxy)│  │
│  └──────┬───────┘    └──────┬───────┘    └──────┬───────┘  │
└─────────┼───────────────────┼───────────────────┼──────────┘
          │                   │                   │
          │ spawn             │ vz.sock           │ vz.vsock
          ▼                   ▼                   ▼
┌─────────────────────────────────────────────────────────────┐
│                       vz-shim (PID survives restart)        │
│  ┌──────────────┐    ┌──────────────┐    ┌──────────────┐  │
│  │ HTTP Server  │    │ Vsock Proxy  │    │ vz.VM        │  │
│  │ (control API)│    │ (CH protocol)│    │ (actual VM)  │  │
│  └──────────────┘    └──────────────┘    └──────────────┘  │
└─────────────────────────────────────────────────────────────┘

Platform comparison:

Aspect	Linux (CH)	Linux (QEMU)	macOS (vz)
Process model	External process	External process	vz-shim subprocess
Networking	Bridge + TAP	Bridge + TAP	Built-in NAT (192.168.64.0/24)
Vsock	Unix socket (text protocol)	AF_VSOCK (kernel)	Unix socket (text protocol)
Persistence	Survives restart	Survives restart	Survives restart
Snapshot	Yes	Yes	No (Linux guests not supported)

Snapshot limitation

Virtualization.framework does not support save/restore for Linux guest VMs - only macOS guests work. This is an undocumented Apple limitation confirmed by other projects:

• Tart #1177, #796
• UTM #6654
• Tart explicitly blocks Linux VM suspend: "You can only suspend macOS VMs"

The snapshot infrastructure is implemented in vz-shim for potential future macOS guest support, but the capability is correctly disabled for Linux guests.

vz-shim API:

The shim exposes a Cloud Hypervisor-compatible HTTP API on Unix socket:

• GET /api/v1/vm.info - VM state and configuration
• PUT /api/v1/vm.pause - Pause VM
• PUT /api/v1/vm.resume - Resume VM
• PUT /api/v1/vm.shutdown - Graceful shutdown
• PUT /api/v1/vm.power-button - ACPI power button
• PUT /api/v1/vm.snapshot - Save VM state (infrastructure for macOS guests)
• GET /api/v1/vmm.ping - Health check
• PUT /api/v1/vmm.shutdown - Terminate shim

Vsock proxy uses same text-based handshake as Cloud Hypervisor:

• Client sends: CONNECT {port}\n
• Server responds: OK {port}\n
• Then bidirectional data flow

CI Considerations

Current CI uses self-hosted Linux runners with KVM. For macOS:

• GitHub-hosted macOS runners (macos-14) support Apple Silicon but may lack virtualization entitlements
• Self-hosted macOS runners would be needed for full VM testing
• Recommendation: Add a build-only job on macos-14 to verify compilation, defer VM tests to self-hosted

Example addition to test.yml:

  build-macos:
    runs-on: macos-14
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-go@v6
        with:
          go-version: '1.25'
      - name: Build (macOS)
        run: make build-darwin

Test plan

• hypeman resources - verified resource detection
• hypeman pull - verified linux/arm64 image pull
• hypeman run - verified VM creation and boot
• hypeman exec - verified command execution in VM
• hypeman ps - verified instance listing
• hypeman build - verified Dockerfile→VM image build
• hypeman ingress - verified external access to VM services
• hypeman rm - verified instance cleanup
• VM persistence - verified VM survives hypeman restart
• VM reconnection - verified hypeman reconnects to running VM after restart
• Snapshot limitation - verified and documented (Apple framework limitation)
• Linux regression testing (CI will cover)

---

Note

High Risk
Large cross-cutting, platform-level change that introduces a new hypervisor backend and OS-specific build/runtime paths; failures could impact VM lifecycle, networking, image/build behavior, and production stability if macOS support codepaths are exercised.

Overview
Enables experimental native macOS (Darwin/arm64) support by introducing a new vz hypervisor implementation backed by a codesigned vz-shim subprocess (Cloud Hypervisor-compatible control API + vsock proxy), and wiring hypervisor client creation through a new hypervisor.RegisterClientFactory/hypervisor.NewClient path.

Refactors multiple subsystems for cross-platform compilation: adds Darwin stubs and Linux build tags for networking (NAT/no bridge), device passthrough (unsupported), embedded ingress binaries (Linux-only; macOS uses caddy from PATH), and resource detection (sysctl/statfs on macOS). Instance creation adjusts kernel console args (hvc0 for vz) and vsock socket paths.

Improves the build system by splitting make build/dev/test into OS-specific targets, adding macOS hot-reload config/signing helpers and CI jobs, cross-compiling embedded guest binaries for Linux, and adding .env.darwin.example docs. Build pipeline behavior changes include: Linux-guest OCI image resolution regardless of host OS, ext4 disk image sector alignment for vz, build log streaming from builder VMs over vsock, and background auto-build of the builder image via a configurable DOCKER_SOCKET with a “retry shortly” guard while the image is prepared.

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

[github-actions]

✱ Stainless preview builds

This PR will update the hypeman SDKs with the following commit message.

feat: add macOS support via Virtualization.framework (vz)

Edit this comment to update it. It will appear in the SDK's changelogs.

✅ hypeman-typescript studio · code · diff

Your SDK built successfully.
generate ⚠️ → build ✅ → lint ✅ → test ✅

npm install https://pkg.stainless.com/s/hypeman-typescript/c5f4a2777fc57ada941611eec78e8480413ca298/dist.tar.gz

✅ hypeman-go studio · code · diff

Your SDK built successfully.
generate ⚠️ → lint ✅ → test ✅

go get github.com/stainless-sdks/hypeman-go@213b748abb9350688d287881c472b9cb50f110ed

✅ hypeman-openapi studio · code · diff

Your SDK built successfully.
generate ⚠️

⏳ hypeman-cli studio · conflict

⏳ These are partial results; builds are still running.

---

This comment is auto-generated by GitHub Actions and is automatically kept up to date as you push.
If you push custom code to the preview branch, re-run this workflow to update the comment.
Last updated: 2026-02-10 01:35:04 UTC

[cursor]

Vsock proxy exits after single direction closes

Medium Severity

The vsock proxy in handleVsockConnection waits for only one direction to close (<-done), then returns — closing both connections via defer. The second goroutine may still be copying data in the other direction. This can cause premature truncation of data still in flight (e.g., a response being written back after the client closes its write side). Waiting for both directions to finish would ensure complete data transfer.

 

[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]

Vsock proxy reads from raw conn instead of reader

Low Severity

In handleVsockConnection, the handshake is read using a bufio.NewReader(conn), but the bidirectional proxy uses io.Copy(guestConn, conn) reading from the raw conn. Any data buffered by the bufio.Reader beyond the handshake line would be silently lost. The client-side implementations in both lib/hypervisor/vz/vsock.go and lib/hypervisor/cloudhypervisor/vsock.go correctly use a bufferedConn wrapper for this exact reason.

 

[cursor]

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

• ✅ Fixed: Vsock proxy reads from raw conn instead of reader
  • Changed io.Copy(guestConn, conn) to io.Copy(guestConn, reader) so that any data buffered by the bufio.Reader during handshake parsing is not lost in the bidirectional proxy.

Or push these changes by commenting:

@cursor push 692e2e5f1c

Preview (692e2e5f1c)

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
@@ -246,7 +246,7 @@
 	done := make(chan struct{}, 2)
 
 	go func() {
-		io.Copy(guestConn, conn)
+		io.Copy(guestConn, reader)
 		done <- struct{}{}
 	}()