refactor: cross-platform foundation for macOS support

[rgarcia]

Summary

• Split platform-specific code into _linux.go and _darwin.go files across resources, network, devices, ingress, vmm, and vm_metrics packages
• Add hypervisor abstraction with registration pattern (RegisterSocketName, RegisterVsockDialerFactory, RegisterClientFactory) to decouple instance management from specific hypervisor implementations
• Add "vz" to the OpenAPI hypervisor type enum, erofs disk format support, and insecure registry option for builds
• Cross-compile guest-agent and init binaries for Linux (needed when building on macOS)

No behavioral changes on Linux. macOS can now compile but has no VM functionality yet.

This is part 1 of 2 for macOS/Virtualization.framework support. Part 2 (feat/vz-hypervisor) adds the actual vz hypervisor implementation.

Test plan

• make build-linux succeeds
• make test-linux passes (failures are Docker Hub rate limiting, not code changes)
• CI passes on Linux runner
• CI passes on macOS runner (compilation check via test-darwin)

🤖 Generated with Claude Code

---

Note

Medium Risk
Touches VM lifecycle/build pipeline (vsock connection path, builder image preparation, log persistence) and image/disk creation logic, which could affect build reliability and instance startup even on Linux despite being largely additive/guarded.

Overview
Establishes a cross-platform foundation by splitting multiple subsystems into Linux vs macOS implementations (networking, devices/GPU passthrough, resources, VM metrics, VMM/ingress binaries), adding macOS stubs/no-ops where features aren’t supported yet, and updating the API hypervisor enum to include vz.

Refactors hypervisor integration to be registration/factory-based (RegisterClientFactory, platform-specific starters, per-instance GetVsockDialer) and adds platform-specific hypervisor access checks (KVM on Linux vs Virtualization.framework on Apple Silicon).

Improves the build system: builder-agent now streams logs over vsock while retaining an authoritative buffered log; build manager can bootstrap a builder image locally from an embedded Dockerfile via Docker + OCI cache import when BUILDER_IMAGE is unset, gates build execution until the builder image is ready, and switches to per-instance vsock dialing. Image handling is adjusted to always target Linux VM platform for pulls/manifests and disk image creation is made 4K-sector aligned for Virtualization.framework compatibility.

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

refactor: cross-platform foundation for macOS support

⚠️ hypeman-openapi studio · code

There was a regression in your SDK.
generate ⚠️

⚠️ hypeman-typescript studio · code

There was a regression in your SDK.
generate ❗ → build ✅ → lint ✅ → test ✅

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

⚠️ hypeman-go studio · code

There was a regression in your SDK.
generate ⚠️ → lint ✅ → test ✅

go get github.com/stainless-sdks/hypeman-go@8adc4f38026abee34ad85c15509e90f47644a0d0

⚠️ hypeman-cli studio · conflict

There was a regression in your SDK.

---

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-11 01:11:19 UTC

[sjmiller609]

looks good, maybe some opportunity for deduplication

[sjmiller609]

this looks simpler than the linux one, idk if we could do the same there or not

[sjmiller609]

the implementations for darwin and linux look almost identical here

[rgarcia]

Addressed the remaining review feedback in 3658218:

Cursorbot bugs (all fixed):

• RecoverPendingBuilds race — Moved RecoverPendingBuilds() from NewManager() to Start(), running it sequentially after ensureBuilderImage completes. Recovered builds no longer race against builder readiness.
• Missing erofs sector alignment — Added the same alignToSector + truncate logic that ext4 already had to convertToErofs.
• Redundant ForLinux aliases — Removed InspectManifestForLinux/PullAndUnpackForLinux and updated the single caller in initrd.go.

Steven's observations:

• cpu_darwin.go simplicity — Good observation. Linux could potentially use runtime.NumCPU() too, but the /proc/cpuinfo parsing handles edge cases like hyperthreading topology (siblings × sockets) which runtime.NumCPU() may not match on certain server configurations. Worth revisiting as a follow-up but not blocking.
• disk_darwin.go duplication — Agreed, the implementations are nearly identical. The difference is Darwin uses unix.Statfs_t with a / fallback while Linux uses syscall.Statfs_t without. These could be unified using golang.org/x/sys/unix on both platforms in a follow-up refactor.

Additionally, this commit includes the builder image rework:

• Embedded the Dockerfile with go:embed instead of reading from filesystem
• Removed the hardcoded "hypeman/builder:latest" default — if BUILDER_IMAGE is unset, builds from the embedded Dockerfile
• After docker build + docker save, writes the image directly into the OCI layout cache and calls ImportLocalImage, bypassing docker push entirely

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

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

• ✅ Fixed: DockerSocket config not propagated to build manager
  • Added the missing DockerSocket: cfg.DockerSocket field to the builds.Config struct initialization in providers.go so the environment variable value is properly wired through.

Or push these changes by commenting:

@cursor push 262b30fcb7

Preview (262b30fcb7)

diff --git a/lib/providers/providers.go b/lib/providers/providers.go
--- a/lib/providers/providers.go
+++ b/lib/providers/providers.go
@@ -259,6 +259,7 @@
 		RegistryCACert:      registryCACert,
 		DefaultTimeout:      cfg.BuildTimeout,
 		RegistrySecret:      cfg.JwtSecret, // Use same secret for registry tokens
+		DockerSocket:        cfg.DockerSocket,
 	}
 
 	// Apply defaults if not set