# Building the base image — Nucleic Support
The one-time golden base install every Nucleic macOS VM is cloned from: what the build does, choosing a guest macOS version, and pinning a specific restore image.

Virtual Machines

# Building the base image

Before any macOS VM can boot, Nucleic builds a one-time golden base image — the clean, provisioned macOS that every per-session VM is cloned from.

## 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.

PrerequisiteThe macOS VM service must be on before you can build. In Settings ▸ Virtual Machines, turn on Enable macOS VM service — see macOS virtual machines: overview for requirements and disk space.

## 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:

1. ### 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.

2. ### 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.

3. ### 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.

Good to knowEntries whose restore image hasn't been published yet fall back to the latest available macOS until their image ships. Once the image is out, that version becomes selectable on its own.

## 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 `NucleicVMAgent` into the base and, on macOS 27, writes its permission grants automatically. See setting up AX-based computer use.

Heads upKeep plenty of free disk space — at least 64 GB. The base image, the 14 GB restore image, and each per-session clone all add up, and a build needs room to work.

## 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.

## Related guides

macOS virtual machines: overview→ Computer use for macOS VMs→ Setting up AX-based computer use→