macos - SKILL.md Agent Skill

name: macos description: Read this BEFORE trying to fix a GenVM build that fails on macOS. GenVM is NOT built natively on macOS — building from source on Darwin breaks the deterministic runner-artifact invariant. Use a remote Linux nix-builder instead. Triggers on any build/nix/runner/linker/ar failure on a Mac (Apple Silicon or Intel).

Building GenVM on macOS

STOP — do not "fix" the build to run natively on macOS

If you are on macOS and a build (nix build, ninja, runner packaging, linking, ar, FFI deps, …) fails, do not try to make GenVM compile natively on Darwin. This has been attempted and rejected before. Native macOS builds break the project's core invariant.

Why native macOS builds are forbidden

Runner artifacts are content-addressed .tar files. The file name encodes the content hash (a Nix nix32 SHA-256), so two nodes that build the "same" runner must produce byte-identical tars with identical names. This is what prevents determinism violations across the network: one node running a correct artifact and another running a differently-built artifact will disagree.

A native macOS build:

produced different and/or missing runner tars vs. the Linux reference build (e.g. only one cpython tar instead of two, mismatched hashes), and
silently changed the on-disk set of runners.

You can verify the reference set on Linux with:

find $(nix build .#runners-all --no-link --print-out-paths) -name '*.tar' \
  | sort | xargs sha256sum | sed -e 's+/nix/store/[^/]*++'

Any macOS output that does not reproduce these exact hashes is wrong.

Specific anti-fixes — never do these

These are the tempting "fixes" that actually break determinism. Do not apply them:

Removing outputHash from fixed-output derivations (e.g. runners/cpython/deps/ffi/default.nix). The repo literally warns: "the moment you delete this you should question yourself." outputHash is what pins the artifact; deleting it destroys reproducibility.
Adding a platform-native linker path for Darwin.
Patching ar to work on macOS.
Any change that lets runners build on aarch64-darwin / x86_64-darwin instead of Linux.
Editing runners/support/versions/current.nix hashes to make a macOS build pass. A change whose only purpose is "make it build on macOS" must not touch those hashes — they pin the Linux reference artifacts. If a macOS build forces you to change a hash there, the build is producing the wrong bytes; fix the builder (use the Linux remote builder), not the hash.
Removing / pruning old runner generations (existing .tar entries or prior hash versions). A macOS-build-only change must leave the existing set of runner generations intact — silently dropping old ones is exactly the determinism-breaking regression that gets such changes rejected.

Per the maintainer: runners can only be built on Linux (x86_64). On macOS you download prebuilt runners or build them on a remote Linux builder — you do not build them locally.

The supported path: a remote Linux nix-builder

Build Linux derivations on Linux, from your Mac, over SSH. The repo ships a ready-made containerized Linux remote builder:

support/macos/nix-builder/ — see its README.md for the full, current procedure. Read that file; do not improvise.

In short (read the README for exact, up-to-date steps):

Install Rosetta (softwareupdate --install-rosetta --agree-to-license) and Docker Desktop with "Use Rosetta for x86_64/amd64 emulation" enabled.
docker build -t nix-builder support/macos/nix-builder (add --platform linux/arm64 if needed), drop your id_ed25519.pub into the volume, and docker run it (privileged, port 2222).
Register it in /etc/nix/machines and set builders-use-substitutes = true in /etc/nix/nix.conf. Add the host key to known_hosts for root too.
Sanity-check with NIX_REMOTE="ssh-ng://root@localhost:2222" nix build --system x86_64-linux nixpkgs#hello.

Notes that bite people (all in the README): use Nix 2.34.7+ (older 2.2x mishandles ssh-ng://host:port), and the root user — not just your user — must trust the builder's host key.

If you just need to develop / run, not rebuild runners

You usually do not need to build runners at all. Download them instead (works on any platform):

nix develop .#full --command python3 build/out/bin/post-install.py \
  --create-venv false --default-step false \
  --runners-download true --error-on-missing-executor false

See the build skill for the normal Rust build flow.