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.