Nucleic
Virtual Machines

macOS virtual machines

Give an agent a whole Mac of its own — a per-session macOS VM for Xcode, the simulators, and codesign, so parallel Mac builds never collide on your host.

01What they are & why

Each macOS VM is a per-session, isolated Mac running on Apple's Virtualization framework — a real, disposable macOS instance where xcodebuild, the simulators (xcrun simctl), and codesign run end-to-end without ever touching your host.

They exist to remove shared-host toolchain thrash. Two agents building on the same host collide and corrupt each other's derived-data build output — one clobbers the other's intermediate files mid-compile, and both builds fail in confusing ways. When each agent gets its own isolated Mac, concurrent builds never collide: every session compiles, simulates, and signs in its own clean environment.

This is exposed to agents as the mac_vm_exec tool — the per-agent alternative to the shared-host host_exec. Where host_exec runs commands directly on your Mac (shared by every session), mac_vm_exec runs them inside that session's own VM.

02Requirements

Before you turn this on, make sure the machine can carry it:

  • Apple silicon Mac. Running macOS guests requires Apple silicon — Intel Macs can't host a macOS VM.
  • Plenty of RAM. It's heavy: expect several GB of RAM per running VM, on top of a one-time base-image install.
  • Free disk space. The golden base image, its downloaded restore image, and each per-session VM disk add up fast.
  • macOS 27 or later on host and guest. macOS 27 is the supported host and guest version for macOS VMs.
Disk spaceKeep at least 64 GB free before enabling macOS VMs. Between the golden base image, its restore image, and every per-session VM disk, space disappears quickly — and running low can stall builds or corrupt a VM mid-run.

03Turning it on

  1. Enable the service

    In Settings ▸ Virtual Machines, turn on Enable macOS VM service.

  2. Optionally expose it to sessions

    Turn on Expose to sandboxed sessions by default so sessions get the mac_vm_exec tool automatically, without opting in per session.

  3. Build the one-time base image

    Before any VM can boot, you must build the golden base image once — this installs macOS and provisions the dev toolchain. See Building the base image for the full walkthrough.

Good to knowThe base image is a one-time build. Every per-session VM is cloned from it, so you only pay the macOS install cost once — not on every session.

04How a per-session VM works

The first time a session calls mac_vm_exec, Nucleic spins up a VM just for that session:

  • Clone the golden base. Nucleic makes a copy-on-write clone of the base image — fast and space-efficient, since unchanged blocks are shared with the base rather than copied.
  • Boot and connect. It boots the clone and connects to it over SSH.
  • Share the repo. That session's repository is shared into the VM over virtiofs at /Volumes/My Shared Files/workspace, so the agent builds the exact working tree it's editing.

When the VM goes idle (default 15 minutes), it stops to free RAM — but its disk persists, so the next turn reboots quickly instead of re-cloning from scratch. When the session ends or is interrupted, the clone is deleted. Any orphaned clones left behind by a crash are cleaned up on the next app launch.

05Concurrency & resources

macOS caps how many macOS guests can run at once — about 2 on recent releases. Nucleic works within that limit rather than fighting it:

  • Max concurrent VMs. When the cap is reached, extra agents queue for a VM rather than failing — a session waits its turn for a slot instead of erroring out.
  • CPUs. A per-session ceiling on virtual CPUs (default 4).
  • Memory. A per-session memory ceiling (default 8 GB).
TuningRaise CPUs and Memory for heavier builds, but remember each running VM holds that memory for as long as it's booted — balance the per-VM ceilings against how many run at once.

06What's next

Now that you know what macOS VMs are, these guides take you the rest of the way:

Related guides

Building the base image Computer use for macOS VMs Setting up AX-based computer use