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
Introduces a new hypervisor backend and a privileged/codesigned subprocess plus platform-specific install/service management, which can impact VM lifecycle, guest connectivity, and production deployments on macOS.

Overview
Adds a new macOS-only vz hypervisor implementation that runs VMs in a separate vz-shim subprocess, exposes a Cloud-Hypervisor-like control API over a Unix socket, and proxies vsock connections via a per-VM vz.vsock socket.

Updates instance creation/boot defaults for vz (vsock socket path + console=hvc0) and routes API operations (exec, cp, stat) through InstanceManager.GetVsockDialer to support multiple hypervisors consistently. Guest init now always overwrites the guest-agent binary to avoid stale/corrupt binaries after restarts.

Adds macOS developer and deployment plumbing: new .env.darwin.example, .air.darwin.toml, Makefile targets for building/signing (build-darwin, sign-darwin, dev-darwin, sign-vz-shim), a self-hosted macOS CI job plus an E2E install test, and expanded scripts/install.sh/scripts/uninstall.sh to support macOS (launchd service, codesigning, macOS paths, CLI artifact differences).

^{Written by Cursor Bugbot for commit 07550ed. 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.

[cursor]

Network disable flag ignored on macOS

Medium Severity

configureNetwork always creates a NAT NIC when networks is empty, so instances created with NetworkEnabled=false still get guest networking on vz. This makes macOS behavior diverge from the instance request and can unintentionally expose workloads that were expected to run without network access.

 

[rgarcia]

@cursor push eaaacb0

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

Shutdown masks shim communication failures

Medium Severity

Client.Shutdown returns nil for any httpClient.Do error, not just expected connection-reset-on-exit cases. If the shim socket is unreachable or the request fails, callers still treat shutdown as successful, which can leave a running vz-shim process while metadata and control flow proceed as if the VM stopped.

 

[cursor]

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

• ✅ Fixed: Shutdown masks shim communication failures
  • Changed Shutdown to only ignore expected connection-closed errors (EOF, ECONNRESET, EPIPE, net.ErrClosed) and propagate all other transport errors, so callers can detect when the shutdown request never reached the shim.

Or push these changes by commenting:

@cursor push bd4f570bbd

Preview (bd4f570bbd)

diff --git a/lib/hypervisor/vz/client.go b/lib/hypervisor/vz/client.go
--- a/lib/hypervisor/vz/client.go
+++ b/lib/hypervisor/vz/client.go
@@ -5,10 +5,12 @@
 import (
 	"context"
 	"encoding/json"
+	"errors"
 	"fmt"
 	"io"
 	"net"
 	"net/http"
+	"syscall"
 	"time"
 
 	"github.com/kernel/hypeman/lib/hypervisor"
@@ -116,13 +118,28 @@
 	}
 	resp, err := c.httpClient.Do(req)
 	if err != nil {
-		// Connection reset is expected when shim exits
-		return nil
+		// Connection reset / EOF is expected when the shim exits in
+		// response to the shutdown request. Any other error means the
+		// request may not have reached the shim.
+		if isExpectedShutdownError(err) {
+			return nil
+		}
+		return fmt.Errorf("shutdown shim: %w", err)
 	}
 	defer resp.Body.Close()
 	return nil
 }
 
+// isExpectedShutdownError reports whether err is a connection-closed error
+// that is expected when the vz-shim process exits after handling a shutdown
+// request.
+func isExpectedShutdownError(err error) bool {
+	return errors.Is(err, io.EOF) ||
+		errors.Is(err, syscall.ECONNRESET) ||
+		errors.Is(err, syscall.EPIPE) ||
+		errors.Is(err, net.ErrClosed)
+}
+
 func (c *Client) GetVMInfo(ctx context.Context) (*hypervisor.VMInfo, error) {
 	body, err := c.doGet(ctx, "/api/v1/vm.info")
 	if err != nil {