Box of Apples Docs

Restore image library

Use the Image Library to collect and validate the IPSWs you trust before creating or reinstalling VMs.

• Discover the latest Apple-supported macOS restore image.
• Download the latest supported IPSW, import local files, or download from direct URLs.
• Track version, build, source, support status, local path, download progress, and cancellation state.
• Reveal downloaded IPSWs in Finder or delete images when a lab no longer needs them.

Virtual machines

Create macOS VMs from restore images, install macOS, tune their hardware, and manage runtime state from the VM library.

• Configure CPU count, RAM, disk size, disk format, NAT or bridged networking, and audio input/output.
• Start with an interactive console, start headless from the CLI, or boot into macOS Recovery.
• Stop, suspend, resume, randomize serial numbers at startup, and inspect lifecycle logs.
• Reveal VM bundles in Finder or delete VMs and clean up their bundles.

Templates and disposable VMs

Templates are the fast path for repeatable experiments: keep a clean baseline, run a temporary copy, and decide later whether it should become permanent.

• Seal persistent VMs as reusable templates and unseal them back into normal machines.
• Create disposable VMs from sealed templates for test runs and investigations.
• Launch sealed or disposable VMs as temporary runtime clones.
• Use APFS copy-on-write clone support for fast temporary VM copies.
• Convert useful disposable VMs to persistent VMs.

VM console and capture

Console windows are designed for repeated lab sessions, including temporary and sealed VM startup flows.

• Pop out VM console windows and keep their positions and sizes across sessions.
• Toggle macOS keyboard capture and sync clipboard contents through the guest agent.
• Capture screenshots and screen recordings from the console.
• Use recording indicators, default save folders, and capture size presets.

Guest agent and runbooks

The guest agent turns a running VM into an automation target. Runbooks make those actions reusable and traceable.

• Install the guest agent package with LaunchAgent-based guest service setup.
• Execute guest-side processes and stage host files into the guest.
• Wait for screen text or OCR conditions before continuing a runbook.
• Collect artifacts from guests and track execution status, results, and reusable arguments.

Command groups

Use a command group and subcommand, then add options for the exact resource you want to inspect or change.

boa <command> <subcommand> [options]

boa settings
boa image
boa vm
boa template

Inspect and update defaults

Settings control default VM creation behavior, external IPSW URL handling, and serial randomization.

boa settings show [--json]
boa settings set <key> <value>

boa settings show
boa settings show --json
boa settings set default-network nat
boa settings set default-disk-size 80
boa settings set default-disk-format asif
boa settings set allow-external-ipsw-urls true

Discover, import, download, and reveal IPSWs

Restore image commands manage the IPSW library used when creating macOS virtual machines.

boa image list [--json]
boa image show --id <image-uuid> [--json]
boa image import <path-to-ipsw> [--json]
boa image discover-latest [--json]
boa image download-latest [--json]
boa image download-url <https-url-to-ipsw> [--json]
boa image delete --id <image-uuid>
boa image reveal --id <image-uuid>

boa image list
boa image discover-latest
boa image download-latest
boa image import ~/Downloads/macOS.ipsw
boa image download-url https://example.com/macOS.ipsw
boa image show --id <image-id>
boa image delete --id <image-id>
boa image reveal --id <image-id>

Create, configure, start, and manage VMs

VM commands cover library inspection, creation, installation, runtime control, lifecycle logs, and conversion of disposable machines into persistent VMs.

boa vm list [--json]
boa vm show --id <vm-uuid> [--json]
boa vm logs --id <vm-uuid> [--json]
boa vm reveal --id <vm-uuid>

boa vm create \
  --image <image-uuid> \
  [--name <name>] \
  [--cpu-count <count>] \
  [--memory-mi-b <memory-mib>] \
  [--disk-size <gib>] \
  [--disk-format asif|raw] \
  [--network nat|bridged] \
  [--randomize-serial-at-startup] \
  [--json]

boa vm install --id <vm-uuid> [--json]

boa vm update \
  --id <vm-uuid> \
  [--name <name>] \
  [--cpu-count <count>] \
  [--memory-mi-b <memory-mib>] \
  [--network nat|bridged] \
  [--audio-output] \
  [--audio-input] \
  [--randomize-serial-at-startup] \
  [--json]

boa vm start [--id <vm-uuid> | --name <name>] [--headless] [--recovery] [--json]
boa vm stop [--id <vm-uuid> | --name <name>] [--json]
boa vm suspend [--id <vm-uuid> | --name <name>] [--json]
boa vm resume [--id <vm-uuid> | --name <name>] [--json]
boa vm delete --id <vm-uuid>
boa vm convert-persistent --id <vm-uuid> [--json]

boa vm create \
  --image <image-id> \
  --name Tahoe-Lab \
  --cpu-count 4 \
  --memory-mi-b 8192 \
  --disk-size 80 \
  --disk-format asif \
  --network nat

boa vm install --id <vm-id>
boa vm start --name Tahoe-Lab
boa vm start --name Tahoe-Lab --headless
boa vm start --name Tahoe-Lab --recovery
boa vm stop --name Tahoe-Lab
boa vm suspend --name Tahoe-Lab
boa vm resume --name Tahoe-Lab
boa vm delete --id <vm-id>

Seal baselines and spawn disposable VMs

Template commands turn a persistent VM into a reusable baseline, then create disposable machines from it for repeatable test runs.

boa template seal --id <vm-id>
boa template list
boa template create-disposable --id <template-id> --name Tahoe-Disposable
boa vm start --name Tahoe-Disposable
boa template unseal --id <template-id>