01What the base image is
The base image is a golden macOS install that Nucleic builds once and stores in its Application Support folder. Every per-session VM is a fast copy-on-write clone of it, so the base is built and provisioned a single time and reused for every agent.
Because the clone shares the base's disk blocks until it writes new ones, spinning up a fresh VM for a session is near-instant — the slow, one-time work of installing and provisioning macOS is already done and baked into the base. Everything an agent needs at runtime lives in that one image.
02The one-click build
Building the base is a single action. In Settings ▸ Virtual Machines ▸ Base image, click Build base image. In one step it:
-
Downloads and installs macOS
Nucleic fetches the restore image (about a 14 GB download) and installs a clean copy of macOS into the golden base.
-
Creates the agent account
It provisions the guest account an agent logs into and works from, configured to auto-log-in so a cloned VM lands straight on the desktop.
-
Installs the dev toolchain
It installs the developer tooling — Xcode, node, and python — plus the in-guest agent if the semantic AX agent is enabled.
On macOS 27, this is fully unattended — you click once and come back to a finished base, with provisioning handled end to end.
03Choosing a guest macOS version
The Guest macOS image picker chooses which version of macOS goes into the base. It defaults to Latest supported (default) — the newest macOS your host can run — which is the right choice for most builds.
When you pick a specific version, remember the host-must-be-at-least-guest rule: 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
Under the Base image section's Advanced disclosure you can override the picker. Three fields are available:
| Field | What it does |
|---|---|
| Prebuilt base bundle | A path to a base someone already 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. Pins the base to that exact macOS version instead of the newest the host can run. |
| Restore image URL | A URL to a specific restore image. Also pins an exact version, fetched from that address. |
A local path or URL takes precedence over the picker. Leave both empty to install the newest macOS the host can run.
05Rebuilding / re-provisioning
Once a base exists, the button changes to Rebuild / re-provision base image. Rebuild when you've changed what the base needs to contain — most commonly:
- After you enable the semantic AX agent — a rebuild installs
NucleicVMAgentinto the base and, on macOS 27, writes its permission grants automatically. See setting up AX-based computer use.
06After it's built
The base-image status line reports readiness, so you always know what the 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 an agent to use: computer use for macOS VMs for host-side screenshots and clicks, or the semantic AX agent for by-identity control. The base you just built is what every session VM clones from.