refactor: cross-platform foundation for macOS support #89

rgarcia · 2026-02-10T20:25:52Z

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.}

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. No behavioral changes on Linux. macOS can now compile but has no VM functionality yet. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

github-actions · 2026-02-10T20:26:16Z

✱ 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

lib/builds/manager.go

lib/builds/builder_agent/main.go

- Restore persisting result.Logs to disk after build completion, since streamed log lines can be dropped when the bounded channel overflows - Add docker tag + push after building the builder image locally so it is available in the registry for builder VMs to pull - Synchronize log streaming with build result delivery by waiting for logsDone channel before sending build_result, preventing the host from closing the connection before all logs are delivered Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

lib/builds/manager.go

lib/images/disk.go

lib/images/oci_public.go

sjmiller609

looks good, maybe some opportunity for deduplication

sjmiller609 · 2026-02-10T21:49:36Z

lib/resources/cpu_darwin.go

+func detectCPUCapacity() (int64, error) {
+	return int64(runtime.NumCPU()), nil
+}


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

sjmiller609 · 2026-02-10T21:51:09Z

lib/resources/disk_darwin.go

+		// Auto-detect from filesystem using statfs
+		var stat unix.Statfs_t
+		dataDir := cfg.DataDir
+		if err := unix.Statfs(dataDir, &stat); err != nil {


the implementations for darwin and linux look almost identical here

Rework builder image provisioning: - Embed generic/Dockerfile with go:embed instead of reading from filesystem - Remove hardcoded "hypeman/builder:latest" default; if BUILDER_IMAGE is unset, build from embedded Dockerfile (dev mode) - After docker build+save, write image directly into OCI layout cache and call ImportLocalImage, bypassing docker push entirely - Move RecoverPendingBuilds after ensureBuilderImage to prevent race where recovered builds fail with "builder image is being prepared" Also fix review feedback: - Add sector alignment to erofs disk conversion (macOS VF compat) - Remove redundant ForLinux OCI client aliases and update callers Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

rgarcia · 2026-02-10T22:49:49Z

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

lib/instances/hypervisor_darwin.go

lib/builds/manager.go

lib/hypervisor/qemu/vsock.go

Add three tests verifying the builder image import pipeline: - TestDockerSaveTarballToOCILayoutRoundtrip: full pipeline from docker save tarball → load → OCI layout → existsInLayout → extractMetadata → unpackLayers with rootfs verification - TestDockerSaveToOCILayoutCacheHit: verifies pullAndExport skips remote pull when image exists in OCI layout cache (uses bogus registry URL that would fail if pull was attempted) - TestImportLocalImageFromOCICache: end-to-end integration test simulating buildBuilderFromDockerfile's flow: write to OCI cache → ImportLocalImage → async build → verify GetImage metadata and GetDiskPath returns valid ext4 disk Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

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.}

lib/builds/manager.go

cursor · 2026-02-11T00:03:29Z

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

@sjmiller

Merge disk_darwin.go and disk_linux.go into disk.go since both implementations are nearly identical — the only difference was syscall.Statfs (linux) vs unix.Statfs (darwin). Use unix.Statfs from golang.org/x/sys/unix which works on both platforms. Addresses review feedback from @sjmiller. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

disk_darwin.go and disk_linux.go were unified into disk.go in PR #89 but snuck back in during the rebase as new files with no conflicts. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

rgarcia mentioned this pull request Feb 10, 2026

feat: add macOS VM support via Apple Virtualization.framework #90

Open

4 tasks

cursor bot reviewed Feb 10, 2026

View reviewed changes

lib/builds/manager.go Outdated Show resolved Hide resolved

lib/builds/manager.go Show resolved Hide resolved

lib/builds/builder_agent/main.go Show resolved Hide resolved

This comment has been minimized.

Sign in to view

rgarcia requested a review from sjmiller609 February 10, 2026 21:43

cursor bot reviewed Feb 10, 2026

View reviewed changes

lib/builds/manager.go Show resolved Hide resolved

lib/images/disk.go Show resolved Hide resolved

lib/images/oci_public.go Outdated Show resolved Hide resolved

sjmiller609 approved these changes Feb 10, 2026

View reviewed changes

This comment has been minimized.

Sign in to view

cursor bot reviewed Feb 10, 2026

View reviewed changes

This comment has been minimized.

Sign in to view

cursor bot reviewed Feb 11, 2026

View reviewed changes

lib/builds/manager.go Show resolved Hide resolved

rgarcia merged commit 5c29ba8 into main Feb 11, 2026
4 checks passed

rgarcia deleted the refactor/cross-platform-foundation branch February 11, 2026 01:09

refactor: cross-platform foundation for macOS support #89

refactor: cross-platform foundation for macOS support #89

Uh oh!

Conversation

rgarcia commented Feb 10, 2026 • edited by cursor bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Test plan

Uh oh!

github-actions bot commented Feb 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✱ Stainless preview builds

Uh oh!

Uh oh!

Uh oh!

Uh oh!

This comment has been minimized.

Uh oh!

Uh oh!

Uh oh!

sjmiller609 left a comment

Choose a reason for hiding this comment

Uh oh!

sjmiller609 Feb 10, 2026

Choose a reason for hiding this comment

Uh oh!

sjmiller609 Feb 10, 2026

Choose a reason for hiding this comment

Uh oh!

This comment has been minimized.

rgarcia commented Feb 10, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

This comment has been minimized.

cursor bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

cursor bot commented Feb 11, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

rgarcia commented Feb 10, 2026 •

edited by cursor bot

Loading

github-actions bot commented Feb 10, 2026 •

edited

Loading