01What the base image is
The base image is a golden install of macOS. Nucleic builds it once, stores it in its Application Support folder, and clones every per-session VM from it in seconds. Build and provision once. Reuse for every agent.
A fresh VM spins up almost instantly. The slow work — installing and provisioning macOS — happens once, baked into the base. Everything an agent needs at runtime is already in that one image.
02The one-click build
Building the base takes one action. In Settings ▸ Virtual Machines ▸ Base image, click Build base image. One click does it all:
-
Downloads and installs macOS
Nucleic downloads the restore image — about 14 GB — and installs a clean copy of macOS into the golden base.
-
Creates the agent account
Nucleic sets up the guest account an agent logs in to and works from. It's configured to log in automatically, so a cloned VM lands straight on the desktop.
-
Installs the dev toolchain
Nucleic installs the developer tools — Xcode, node, and python — plus the in-guest agent if the semantic AX agent is enabled.
On macOS 27, the build runs fully unattended. Click once, and come back to a finished base — provisioning handled end to end.
03Choosing a guest macOS version
The Guest macOS image picker sets which version of macOS goes into the base. It defaults to Latest supported (default) — the newest macOS your host can run. For most builds, that's the right choice.
Picking a specific version? Keep one rule in mind: the host must be at least as new as the guest. A macOS N guest needs a macOS N-or-newer host — you can't run a guest that's newer than the Mac hosting it.
04Advanced: pin a specific image or reuse a prebuilt base
Want more control? Open the Advanced disclosure in the Base image section to override the picker. You'll find three fields:
| Field | What it does |
|---|---|
| Prebuilt base bundle | The path to a base that's already been built. Point Nucleic at it to skip install and provisioning entirely and reuse the finished base as is. |
| Restore image (.ipsw) | A local path to a specific macOS restore image. It pins the base to that exact macOS version instead of the newest your host can run. |
| Restore image URL | A URL to a specific restore image. It also pins an exact version — downloaded from that address. |
A local path or URL takes precedence over the picker. Leave both empty, and Nucleic installs the newest macOS your host can run.
05Rebuilding / re-provisioning
Once you've built a base, the button changes to Rebuild / re-provision base image. Rebuild whenever the base needs to contain something new — most commonly:
- After you turn on the semantic AX agent — rebuilding puts the in-guest agent into the base and, on macOS 27, grants its permissions automatically. See setting up AX-based computer use.
06After it's built
The base-image status line tells you exactly what your current base supports:
- Ready — builds + computer use. — the base is provisioned, and host-side computer use works on any base with no extra setup.
- Ready — builds + computer use + semantic AX. — the optional in-guest agent is installed and fully granted, too.
From here, turn on what you want your agent to use: computer use for macOS VMs for host-side screenshots and clicks, or the semantic AX agent for by-identity control. Every session VM clones from the base you just built.