# Building the base image — Nucleic Support
Every Nucleic macOS VM starts from one golden base image. Learn what the build does, how to choose a guest macOS version, and how to pin a specific restore image.

Virtual Machines

# Building the base image

Every macOS VM starts from the same place. Nucleic builds a golden base image once — a clean, fully provisioned macOS that every per-session VM is cloned from.

## 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 makes every per-session VM a fast copy-on-write clone of it. Build and provision once. Reuse for every agent.

Each clone shares the base's disk blocks until it writes new ones, so 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.

PrerequisiteYou'll need the macOS engine turned on before you can build. In Settings ▸ Virtual Machines, under Virtualization engine, turn on macOS. See Virtual machines: overview for requirements and disk space.

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

1. ### Downloads and installs macOS

   Nucleic downloads the restore image — about 14 GB — and installs a clean copy of macOS into the golden base.

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

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

Good to knowIf a version's restore image hasn't been published yet, it falls back to the latest available macOS until its image ships. Once the image is out, that version becomes selectable on its own.

## 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 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. Between the base image, the 14 GB restore image, and each per-session clone, space adds up fast. And a build needs room to work.

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

## Related guides

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