Nucleic
Virtual Machines

Virtual machines

Give every agent a machine of its own. Each session gets an isolated macOS or Linux VM for building, testing, and computer use — so parallel work never collides on your host.

01About virtual machines

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

Why? Because two agents building on the same host get in each other's way. They corrupt each other's derived-data build output — one clobbers the other's intermediate files mid-compile, and both builds fail in confusing ways. Give each agent its own isolated Mac, and concurrent builds never collide. Every session compiles, simulates, and signs in its own clean environment.

Agents use this through 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.

Nucleic offers two kinds of VM, each with its own switch in Settings ▸ Virtual Machines:

  • macOS virtual machines — a per-session Mac for Xcode, the simulators, and codesign.
  • Linux virtual machines — a per-session Linux desktop that's lighter and starts faster, for general build, test, and GUI work that doesn't need a Mac.

Both build once into a reusable base image that every session is cloned from, and both support computer use, so an agent can see and drive the screen. This page uses macOS as the running example; the Linux flow works the same way.

02What you need

Before you turn on virtual machines, make sure your Mac is up to it:

  • An Apple silicon Mac. macOS guests require Apple silicon — an Intel Mac can't host a macOS VM.
  • Plenty of memory. VMs are heavy: expect several GB of RAM for each 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 you turn on macOS VMs. Between the golden base image, its restore image, and every per-session VM disk, space goes fast — and running low can stall builds or corrupt a VM mid-run.

03Turn on virtual machines

  1. Turn on the engine

    In Settings ▸ Virtual Machines, under Virtualization engine, turn on macOS (or Linux). Sandboxed sessions then get their own VM automatically — the exec tool appears with no per-session opt-in.

  2. Build the one-time base image

    Before any VM can boot, you 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 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. Every session's VM is cloned from the base image in seconds, and takes almost no extra disk to start.
  • Boot and connect. Nucleic boots the clone and connects to it.
  • Share the repo. The session's repository appears inside the VM at the same absolute path it has on the host, so tools and build artifacts see one consistent project location.

When the VM sits idle (15 minutes by default), 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. And if a crash leaves orphaned clones behind, they're cleaned up the next time the app launches.

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, additional agents queue for a VM rather than failing — each 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 VMs run at once.

06What's next

Now that you know how macOS VMs work, 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