Box of Apples Docs

Restore images

An IPSW is a macOS restore image used to install a new VM. The Image Library tracks its version, build, source, download state, local file, and host compatibility.

Choose an image source

• Download Latest: discover and download Apple's latest restore image supported by this host.
• Download Alternative: browse the alternative IPSW catalog, select an image, and choose Download Selected IPSW. Check its signing and compatibility status; a listed or signed image is not automatically usable on every host.
• Import IPSW: select an existing .ipsw file. The app imports it into the managed image library and reads its installation requirements.
• Download from URL: supply a direct HTTP or HTTPS IPSW URL. Enable Settings > Source Policy > External IPSW URLs if this action is unavailable.

Allow downloads and validation to complete before creating a VM. Use the download cancellation control to stop a transfer, or Reload Library to refresh the list. Right-click an image to rename it, reveal it in Finder, or delete it.

A create-ready image must be local, supported on the current host, and have readable CPU and memory requirements. Discovering an image alone does not download it. Deleting an image removes the managed IPSW, so keep any image you still need for installation.

Configure and control a VM

Select a machine in Virtual Machines to open its inspector. Edit the settings and choose Save Configuration. CPU and memory are constrained by the restore image and host; disk size and disk format are selected when creating the VM.

Disk format

Most Efficient uses ASIF when supported. Most Compatible uses a raw disk image. New VMs default to ASIF on macOS 27 or later in the app, CLI, and Web Dashboard; you can explicitly choose raw instead. ASIF is required for snapshots and linked disposables. Allow space for the IPSW, guest disk, snapshot layers, exports, and collected artifacts.

Networking

NAT uses the host's connection. Bridged attaches to the selected host network interface. Choose an available interface or Automatic; a saved interface that is no longer available prevents startup.

Audio and identity

Toggle Guest Audio Output, Guest Audio Input, and Randomize Serial at Startup. With randomization off, the VM keeps its saved machine identifier.

Guest integration

Choose Boa Guest Agent for guest actions, and configure shared folders and installer mounts. Selecting the agent mode does not install the guest package.

Runtime actions

• Start VM opens an interactive console. Start Headless runs without opening a console; use Open Console when you need it.
• Start VM in Recovery boots into macOS Recovery for that start only.
• Suspend VM pauses the current runtime. Resume VM continues it. This is an in-memory pause, not a saved checkpoint for later host restarts.
• Shutdown VM requests a graceful shutdown. Use Force Stop VM for an unresponsive guest; unsaved guest work can be lost.

Apply CPU, memory, network, audio, or guest-agent-mode changes with a stop and start. Shared folders and USB passthrough have specific live-update support. Use Lifecycle Log for startup, installation, configuration, and shutdown details. Delete VM removes the bundle, guest disk, and runtime metadata.

Snapshots

A snapshot preserves a point in a VM's disk history using ASIF layers. Later writes go into a writable overlay, and restoring a snapshot starts a fresh overlay from that saved point. This is a disk snapshot, not a live snapshot or a saved memory checkpoint.

Requirements

• A macOS 27 or later host and a build with snapshot support. This feature does not independently require a macOS 27 guest.
• A persistent VM with an ASIF disk that is not sealed as a template. Existing ASIF VMs can qualify; the new-VM backing marker required for linked disposables is not required for snapshots.
• The VM must be stopped before creating, restoring, or deleting snapshots. A suspended VM still has an active runtime and does not qualify. Wait for any installation to finish.

Take and organize snapshots

1. Prepare your persistent VM, then choose Shutdown VM and wait until it has stopped.
2. Select it in Virtual Machines and choose Snapshots in the toolbar. You can also right-click an unsealed persistent VM and choose Take Snapshot... or Show Snapshots....
3. Under Take Snapshot, enter a name, optional notes, and comma-separated tags such as baseline, before-update. A blank name gets a timestamp-based name.
4. Choose Take Snapshot. The saved point appears in the list; start the VM normally when you are ready to continue working.
5. Use Search snapshots to match names, notes, or tags. Mark entries with the star control and enable Favorites to narrow the list. Choose Edit, change the metadata, and choose Save.

Names, notes, tags, and favorites organize existing snapshots without changing their saved disk contents. Favorites are not deletion protection. The sheet's Availability message explains why disk operations are unavailable for a VM.

Restore a saved point

1. Shut down the VM. Take another snapshot first if you want to preserve its current disk changes.
2. Open Snapshots, find the saved point, and choose Restore.
3. Start the VM normally. New writes use a fresh overlay based on the selected snapshot. Other saved snapshots remain in the catalog.

Restore discards unsnapshotted disk changes. It replaces the current writable layer. Snapshots do not capture running memory, restore the VM's CPU/network configuration, or roll back files in external shared folders.

Delete snapshots and keep backups

With the VM stopped, choose Delete on an unneeded snapshot. Deletion is blocked if that snapshot is the parent of the active writable layer or has child snapshots. Move the active state to a different saved point and remove unneeded dependent leaf snapshots first. There is no automatic layer flattening or a command to force-delete a dependency.

Snapshot metadata and disk layers live inside the VM bundle. Keep the complete bundle together; do not delete individual layer files. Snapshots are not an independent backup against losing that bundle. Use a stopped-VM archive export for a separate copy, and use a macOS 27 or later host to run a VM with a snapshot stack.

Equivalent operations are available through boa vm snapshot and the Web API. The Web Dashboard has a Snapshots view for creation, favorites, restore, and deletion.

Templates and disposable VMs

A sealed template is a persistent VM kept as a baseline. Starting a sealed template or a disposable VM creates a temporary runtime clone; stopping that runtime discards its guest disk changes.

1. Install macOS in a persistent VM and configure the guest. Install any guest tools and complete their approvals before making a reusable baseline.
2. Shut down the VM. In Template / Baseline, choose Seal as Template / Baseline.
3. Right-click the template and choose Create Disposable VM from This Template, or select a baseline through the Create menu. Give the disposable VM a name and create it.
4. Start the disposable VM. Export captures and collect artifacts to the host before stopping it.
5. To edit the baseline itself, stop its runtime and choose Turn into Normal Persistent VM. If it has linked disposable dependents, collect their results and delete those disposable VMs first. Make your baseline changes, shut it down, then seal it again.

Linked ASIF disposables on macOS 27+

Eligible sealed templates create disposables with a writable ASIF overlay over the template's read-only base disk, instead of copying the full disk into each disposable bundle. The app selects this backing automatically; there is no separate linked-clone switch.

1. On a macOS 27 or later host, create a new persistent ASIF VM using a build with linked-disposable support. New ASIF VMs receive the linked-clone capability marker.
2. Install macOS, configure your guest tools, and shut down the VM. Keep this baseline free of snapshots: an existing snapshot stack makes it ineligible for linked disposables.
3. Seal the persistent VM as a template. It must be installed or stopped when you create the disposable; a running template does not use this optimization.
4. Choose Create Disposable VM from This Template. Check Disk Backing in the Web Dashboard's VM details, or run boa vm show --id <disposable-uuid>; a linked disposable reports linked ASIF overlay.

The template must be standalone, sealed, ASIF, marked for linked clones, and have no snapshots, active snapshot layer, or snapshot parent. Upgrading an older host or opening an older ASIF VM does not add the new creation marker. Templates that do not meet all these conditions continue using the existing full-copy disposable path, with APFS copy-on-write support for temporary runtime copies where available.

A linked disposable depends on its sealed template. Keep the base VM bundle at its original location and do not delete or modify its base disk. Unsealing is blocked until all dependent linked disposable VMs are deleted from the library; stopping their runtimes is not enough.

Persistence and portability limits

Linked-overlay disposables cannot currently be exported or converted to persistent VMs. There is no flattening or materialization operation to make them independent. Collect files and captures to the host before ending a run; use a standalone persistent VM when you need an independently portable working disk.

For full-copy disposables, Convert to Persistent VM changes the stopped disposable source into a normal persistent machine. It does not recover changes already discarded from a stopped temporary run. Both disposable backing types still use temporary runtime clones and discard guest disk changes when the runtime ends.

Shared folders are outside the disposable disk. Changes made through a writable host share survive VM shutdown. Use read-only shares when the guest should only inspect host files.

Move VMs between libraries

1. Shut down the VM completely. Export is unavailable while it is running, suspended, or installing, and is not supported for linked-overlay disposables.
2. Select the VM and choose Export, or right-click it and choose Export VM. Save the portable .boa-vm archive.
3. On the destination Mac, open Virtual Machines > Import and select the archive.
4. Review the imported VM's configuration before starting it. Host folder paths, network interfaces, and USB devices may differ on the destination.

Import creates a new library ID and bundle while retaining the VM's configuration and persistent/disposable mode. An exported bundle does not include the contents of external shared folders, and importing does not remove Apple's host compatibility requirements. CLI equivalents are in VM import and export.

Exports of standalone VMs include the snapshot catalog and layers in their bundle. Keep the archive intact and run snapshot-backed VMs on macOS 27 or later. A linked disposable cannot be made portable by exporting it alongside its template; that export path is not implemented.

Shared folders and guest installers

Share a host folder, WebDAV location, SMB share, or APFS volume with a guest. Folder sharing uses the VM's filesystem device and does not require the Boa Guest Agent.

1. Select the VM and scroll to Shared Folders in its inspector.
2. Choose Add Shared Folder and the source type. Enter a unique Guest Name.
3. For a local folder, use Choose Folder and set Read Only as needed. For other sources, enter the source shown below.
4. Choose Save Configuration. In the guest's Finder, choose Go > Go to Folder and open /Volumes/My Shared Files. Each share appears under its Guest Name.

Mount the bundled installer packages

In the VM inspector's Configuration section, enable Mount Guest Agent Installer or Mount ES Monitor Installer, then save. The packages appear in read-only folders named Boa Guest Agent Installer and Boa ES Monitor Installer inside /Volumes/My Shared Files. Open the package inside the guest to install it.

The guest-agent installer mount is enabled by default for newly created VMs; the ES Monitor installer mount is optional. Mounting a package does not run the installer or approve its permissions. You can turn off the mount after installing; the installed guest software remains.

Change shares while a VM is running

Saving folder changes, including the installer toggles, updates an app-managed local runtime immediately when its shared-folder device is available. This also works for headless sessions owned by the app. If a session was created without that device, or is owned by a separate CLI runtime, stop and start the VM to apply the configuration. Check Lifecycle Log if changes were saved but could not be applied live.

The guest location follows Apple's automatic shared-folder mounting.

Install and use the Boa Guest Agent

The agent enables guest information, text clipboard integration, process execution, file staging, and artifact collection. It runs inside the guest as a LaunchAgent for a logged-in desktop user.

1. In the VM inspector, select Guest Agent > Boa Guest Agent and enable Mount Guest Agent Installer. Save the configuration. Restart the VM if you changed its agent mode during an existing session.
2. Log in to the guest. Open /Volumes/My Shared Files/Boa Guest Agent Installer and run the bundled .pkg.
3. Complete the installer. It starts the agent for the active desktop user automatically; if no user was logged in, the agent starts at the next desktop login.
4. Back on the host, use VM Actions > Guest Agent Actions > Query Guest Info. A successful query shows the guest host name, current user, OS version, and IP address.

If the installer mount is unavailable, choose Guest Agent in the Virtual Machines toolbar, then Save Package.... Place the saved package in a shared folder and install it inside the guest.

Run a command or collect a file

From VM Actions > Guest Agent Actions, choose Run Process..., enter the guest executable path, and add each argument separately. For a first check, use /usr/bin/sw_vers without arguments. Choose Run as Administrator only when needed and supply the guest administrator's password.

Collect File... retrieves a guest file to a host destination. Run Host Script... and Run Host Executable... select a file on the host, stage it into the guest, and execute it there. Working directories and executable/interpreter paths are guest paths. These actions require a running, unpaused guest and an available agent session.

Console, capture, and resource usage

Start a VM or choose Open Console to interact with it. Pop-out windows retain their size and position. Use the console toolbar or the macOS Actions menu while a console is active.

• Mac Keyboard: toggle capture of macOS system keys for the guest.
• Hide Console: hide the console while leaving the VM running. Use the VM library to reopen it.
• Take Screenshot: save a PNG of the VM display.
• Start Screen Recording / Stop Screen Recording: save a .mov recording. The title bar shows recording state and elapsed time.
• Show Resource Footprint: inspect host-side resource measurements associated with the VM. These are not a substitute for measurements inside the guest.
• Endpoint Security: open the VM's event capture window after completing guest setup.

Under Settings > Console Capture, choose screenshot and recording folders and a capture size: Actual Size, 720p, 1080p, or 1440p. Configured folders let captures save immediately; clearing a folder restores the save dialog. Screen recordings and OCR steps in runbooks use the VM display and need a usable app-managed console.

Clipboard sync and history

With the guest agent installed and the VM running, open the console's Actions > Clipboard Sync menu. You can also cycle modes with the clipboard toolbar control.

Off

The default. Clipboard changes are not automatically synchronized.

Host to VM

New text copied on the host is sent to this VM. Guest clipboard changes do not replace the host clipboard.

Bidirectional

New text copied on either side updates the other side's clipboard.

1. Select a sync mode, then copy some text on the appropriate side. Paste normally in the destination application.
2. Choose Actions > Show Clipboard History to inspect recent entries for this VM, including their source and time.
3. Use Copy to Host or Send to VM to reuse an entry. Clear History removes the recorded entries.

Sync supports text, not file or image clipboard transfer. History keeps up to 40 entries per VM in app memory and is not a persistent clipboard archive. Sync is session-specific and turns off when the session stops or the VM is suspended; re-enable it after resuming. Bidirectional sync can replace your host clipboard, so select the mode deliberately when working with several VMs.

Endpoint Security Monitor

Capture macOS Endpoint Security events inside a VM and inspect them on the host. View executions, process relationships, file activity, signing information, and event JSON. Event subscriptions control what is collected; this is an observation workflow, not a policy editor for blocking guest processes.

Set up the monitor inside the guest

1. Install the Boa Guest Agent, select its mode in the VM inspector, and keep a guest desktop user logged in.
2. Enable Mount ES Monitor Installer in the VM's Configuration and choose Save Configuration.
3. In the guest, open /Volumes/My Shared Files/Boa ES Monitor Installer and install the package.
4. Open the installed Box of Apples ES Monitor app in the guest. It requests extension activation on launch. Use Activate Extension if you need to submit the request again, then approve the system extension in the guest's System Settings.
5. Choose Open Full Disk Access and grant access to BoxOfApplesEndpointSecurityExtension in the guest. Use Relaunch and Refresh in ES Monitor as needed.
6. Wait until both System Extension and Full Disk Access report Granted and the app reports Ready. Restart the guest if activation explicitly reports that a reboot is required.

These installations and approvals belong inside each guest, including any baseline you intend to reuse as a template.

Start a capture

1. On the host, right-click the VM and choose Endpoint Security, or open it from the active console's Actions menu.
2. Open Subscriptions, select the events you need, and choose Save and Deploy. The default subscription is exec.
3. Choose Start, perform the activity in the guest, and inspect the arriving events. Choose Stop to stop host collection.
4. Export your capture as JSON or JSONL before stopping the VM or clearing the capture.

Available subscriptions include exec, fork, exit, create, open, write, rename, unlink, getextattr, setextattr, deleteextattr, tcc_modify, btm_launch_item_add, and btm_launch_item_remove.

Inspect events and process trees

Filter the Events list by event type or search for a process, path, or field. Open an event for its message, process context, event data, and JSON. The Executions view focuses on process launches and arguments.

Use Process Tree, or an event's Open in Process Tree as Root Object action, to explore relationships. Select the relationship mode and root process, search by PID, name, path, signing ID, or argument, and zoom as needed. Subscribe to exec and fork for richer relationships; add exit for lifecycle context. Trees reflect captured events, so filtered or missed events can leave incomplete ancestry.

Control noise and preserve results

Mute Policy supports signing IDs, team IDs, exact paths, and path prefixes. It is shared across Endpoint Security sessions. Edit the entries and choose Save and Deploy. Review the built-in defaults when expected processes are absent. Muting prevents collection of matching activity; filtering the Events list only changes what you see.

Stored counts events retained for the session; the live view is bounded to the latest 20,000. Exports include the stored capture, not just the visible filtered rows. Lost reports transport loss and is a signal that the capture may be incomplete. Clear discards the host's captured history.

JSON exports contain a document envelope and an events array. JSONL exports contain one event per line. Both use ESLogger-shaped event records with Box of Apples and VM metadata. The session store is removed when the VM runtime is torn down, so export before shutdown.

Runbooks and artifacts

A runbook is an ordered, reusable workflow for an app-managed VM with a Boa Guest Agent session. Use it to run commands, stage host tools into a guest, capture output, watch for screen text, and collect results.

Create and run a first workflow

1. Open Runbooks > New Runbook. Use Open Builder to edit an existing runbook.
2. In Runbook Details, enter its name, author, version, and summary. Choose Select Folder... for the host artifact output directory, or leave the default.
3. Choose Add Step > Run Process. Set Executable Path to /usr/bin/sw_vers, enable Wait for Exit, and set Guest Output File Path to /tmp/boa-system-version.txt.
4. Add Collect Declared Outputs after it to retrieve that output file. Steps run in list order; drag them or use the move controls to reorder them.
5. Choose Save Runbook. Under Activation, select a running Target VM with the agent installed and choose Run Runbook.
6. Inspect the execution and step results. Collected files are written below the selected host output directory in runbook-name/execution-id folders.

Host files and artifact sources

Choose New Artifact Source to register a Local Directory or Git Repository. For a local directory, select the folder. For Git, enter the repository URL and optional reference/branch and subpath, then choose Save Source and Sync Source. Git sources need a successful sync before their files are available to a runbook.

Select an artifact source and relative file path for host-script or host-executable steps. These files run inside the guest after staging. Guest Output File Path is a path in the VM; the runbook's output folder is on the host. Use the folder chooser for protected host locations such as Desktop or Documents so the app receives access.

Watch screen text and pause for input

Watch Screen Text starts an OCR monitor in parallel while later steps continue. It is not a blocking wait. Configure Matched Text, Contains or Exact Line matching, case sensitivity, recognition quality, and a timeout.

On a match, the monitor can notify you, suspend the VM, and pause the runbook. Resume the guest to handle any prompt, then choose Resume Runbook; Resume VM with Runbook can resume the guest automatically when both pause and suspend behavior are enabled. Keep a usable console open for screen-based steps.

Failures, elevation, and sharing

Disable steps to skip them. A failing step normally stops execution; enable Continue on Failure for a step only when later work can still proceed. Stop Runbook cancels an active run. If a step requires elevation, enter the guest administrator password in Activation before starting.

Use Export... and Import Runbook to exchange runbook JSON. The shared runbooks folder supports Import Folder Runbooks and Export Selected to Folder. Imported runbooks can reference host-specific artifact sources and output folders; review and reconnect those before execution. The CLI currently has no standalone runbook command; use the app, a schedule, or the Web API.

Schedule your VM workflows

Schedules contain recurring actions at selected local times and weekdays: boot, shutdown, suspend, resume, or run a saved runbook.

1. Open Scheduler > New Schedule. Enter a name and optional notes, then enable the schedule.
2. Choose Add Action. Set its name, Action, Virtual Machine, local hour and minute, and weekdays. Keep the action's Enabled toggle on.
3. For boot actions, choose Headless or Open console on boot. For shutdown, use Force stop VM only when a graceful shutdown is unsuitable. For a runbook action, select a saved runbook.
4. Choose Save Schedule. Keep Box of Apples open and the host awake. Inspect Next Action, the last scheduler check, and each action's last result.

A typical weekday sequence is boot at 09:00, run a saved workflow at 09:05, and shut down at 18:00. Allow enough time for guest boot, desktop login, and the guest agent to become ready before the runbook action.

Execution rules

• The app checks roughly every 30 seconds and matches the current local minute. It does not wake a sleeping host or catch up actions missed while the app was closed.
• Boot actions only start an installed or stopped VM, and are skipped if two VMs are already running. A skipped action is not queued for later capacity.
• VMs started by the scheduler are exempt from the app's console-idle suspend policy while scheduler-managed.
• For actions due in the same minute, the order is shutdown, suspend, resume, boot, then runbook. Give boot and runbook actions separate times so the guest can become ready.
• Runbook actions require an app-managed live VM and a Boa Guest Agent session. Scheduled runbooks cannot supply an administrator password, so runbooks with elevated steps are skipped.

Schedules can also be edited in the Web Dashboard and managed with boa scheduler. After changing schedules through the CLI, reopen the app to load the updated schedule definitions.

Web Server and Dashboard

The built-in server provides an authenticated browser dashboard and JSON API for the host's VM, image, runbook, and scheduler libraries. The server runs as part of the desktop app and is disabled by default.

Connect from this Mac

1. Open Settings > Web Dashboard.
2. Leave Bind Address set to This Mac Only. The default port is 7427 and the default Security mode is HTTP.
3. Enable Server Mode and check that the dashboard status reports a running server.
4. Choose Copy beside Authentication Token.
5. Open http://127.0.0.1:7427/, paste the token into Dashboard token, and choose Sign In.

Use the dashboard

• Virtual Machines: create from an image or template, install, start, shut down, force stop, suspend, resume, and edit supported configuration. Use the action menu for Recovery, sealing, unsealing, and conversion.
• Snapshots: select an eligible stopped persistent ASIF VM and open Snapshots. Enter a name, notes, and comma-separated tags, then choose Take Snapshot. Existing entries have Favorite/Unfavorite, Restore, and Delete actions. The dashboard asks for confirmation before restore or delete; the same host, VM-state, and layer-dependency rules apply as in the app.
• Live Console: select an app-managed running VM, choose Start Live, and interact with its keyboard and pointer. Use Enlarge for a larger view. Stopping the live view does not shut down the VM.
• Guest Actions: run a guest process or stage and run a host script/executable. A logged-in guest with its agent installed is required.
• Images: discover and download IPSWs, browse the catalog, import a host file path, rename entries, and delete images.
• Runbooks: create an empty runbook, import runbook JSON, select a VM, run saved steps, manage artifact sources, and inspect execution summaries. Use the desktop builder to edit the steps.
• Scheduler: create and edit schedules, choose actions, times, and weekdays, and inspect their results.

VM details show the disk format and Disk Backing. Linked disposables retain their base-template dependency in the dashboard too: conversion and unsealing requests are subject to the same restrictions. Use the native snapshot sheet, CLI, or API to edit an existing snapshot's name, notes, and tags; the browser list currently provides a favorite toggle rather than a metadata editor.

All paths entered in the dashboard refer to the Mac running Box of Apples, not the computer running your browser. Importing a path is not a file upload. Endpoint Security analysis, clipboard history, shared-folder source editing, and VM archive import/export use the desktop app or their documented CLI equivalents.

Connect from another computer

Choose All Interfaces or a Custom local interface address, then browse to that Mac's reachable IP address and configured port. 0.0.0.0 is a bind setting, not a destination address. Network and firewall configuration must allow access.

Use HTTPS Self-Signed for the built-in encrypted connection. Choose Certificate > Reveal to locate the generated .crt, then trust that certificate on each client you control. Only distribute the certificate; the neighboring private key and PKCS#12 files remain on the host. Plain HTTP is intended for localhost, a trusted LAN, or a deployment with a TLS reverse proxy.

The authentication token grants control of the dashboard and its actions. Regenerate replaces it and invalidates existing browser sessions; sign in again with the new token. Sign Out ends the current browser session. Keep the desktop app open for both the server and scheduled work.

macOS 27 features

The app still supports macOS 26 hosts. The following additions are available when the host runs macOS 27 or later.

ASIF disks, snapshots, and linked disposables

New VM creation defaults to ASIF across the native app, CLI, and Web Dashboard. You can explicitly select raw, but raw disks do not support snapshots or linked ASIF disposables. Existing disks are not automatically converted.

• Snapshots save and restore disk states for stopped, unsealed persistent ASIF VMs. They do not capture live memory and are unavailable while running, suspended, or installing.
• Linked disposables use an overlay over an eligible sealed base. They require a new ASIF VM's linked-clone marker and no snapshot stack; other templates keep the full-copy path.
• Both storage features require a macOS 27 or later host. Unlike First Boot Setup, they do not independently require a macOS 27 guest. Run snapshot-backed and linked-overlay VMs on macOS 27 or later.

First Boot Setup

1. Create a fresh persistent VM from a macOS 27 or later IPSW.
2. Enable Provision macOS Guest in the creation form, or expand Configuration > First Boot Setup in the inspector before its first normal boot.
3. Enter Full Name, Username, and Password. Optionally enable Log In Automatically and Enable Remote Login.
4. Save, install macOS, and start the VM normally. The setup options are applied on that first normal boot; Recovery starts do not apply them.

Once applied, First Boot Setup is marked complete and is not an account-editing tool for an existing guest. Configure later account changes inside macOS. Guest-agent and ES Monitor installation and approvals are separate steps.

First Boot Setup also requires macOS 27 or later inside the guest.

USB passthrough

1. Connect the accessory to the host Mac.
2. In the VM inspector, expand USB Passthrough, enable Attach Matching USB Device, and choose Choose USB Device....
3. Select a connected device and save the configuration. The app matches USB vendor/product identifiers and attaches matching accessories when available.
4. Check Lifecycle Log for attachment status. If the running VM lacks a USB controller, restart it to apply the saved configuration.

Matching devices connected later can attach to an app-managed session. Saving a change can update a running session when its controller is available. Disabling passthrough stops new matching attachments; an already attached device remains until detached by the guest or the VM stops. The separate CLI headless runtime does not implement the app's accessory attachment listener; use the desktop app's Start VM or Start Headless actions for USB passthrough.

VM labels in Activity Monitor

On macOS 27 hosts, VM configurations carry a Box of Apples label containing the VM name and a short ID, making host-side processes easier to identify.

Settings and storage

Use the sidebar's Settings section for source policy, creation defaults, console capture, idle suspend, the Web Dashboard, and storage locations.

• VM defaults: network mode, disk size, and startup serial randomization apply to new machines. On macOS 27 or later, creation initially selects ASIF even if the saved disk-format preference is raw; explicitly select raw in the creation form or command when needed. Edit an existing VM in its inspector.
• Console Capture: select output folders and a capture size. Console thumbnail previews can be disabled separately.
• Idle Suspend: optionally suspend idle console VMs after the configured interval. Idle means no tracked keyboard/mouse interaction in the console, not low guest CPU use. Headless-only and scheduler-managed VMs are excluded.
• Storage: use the reveal controls for the Image Library, VM Bundles, and Disposable Runs. These controls reveal the current locations; they do not move the library.

The host library lives under ~/Library/Application Support/Box of Apples/. Managed images are in Library/Images, VM bundles in Library/VMs/Bundles, and temporary runtime clones in Library/VMs/DisposableRuns. Runbooks, execution records, and artifact sources live alongside these libraries.

Each snapshot-enabled VM keeps its catalog in Metadata/snapshots.json and additional layers in Disks/Snapshots inside its bundle. A linked disposable also references its sealed template's disk outside its own bundle. Manage these through the app, CLI, or API instead of editing catalog files or moving disk layers manually.

Keep backups of persistent VM bundles and exported runbooks. Use the app's delete and import/export actions for lifecycle operations; a suspended VM is still a live runtime, not an exportable backup.

Troubleshooting

No image in the VM creation form

Complete the IPSW download/import and check host support and installation requirements. A remote catalog entry alone is not create-ready.

A feature is missing

Check your installed build against the release notes. macOS 27 controls require a supported host, and First Boot Setup also requires a macOS 27 guest. Older builds may not include the scheduler or current guest integrations.

Snapshots are unavailable

Use a macOS 27 or later host and an ASIF persistent VM. Shut it down completely, wait for installation to finish, and unseal it if it is a template. Read the snapshot sheet's Availability message. Pausing is not sufficient; disposable and raw-disk VMs do not qualify.

A snapshot cannot be deleted

The active writable layer or a child snapshot still depends on it. Restore to another saved point if appropriate, preserving current work first, and delete unneeded dependent leaf snapshots before their parent. Favoriting does not override these rules.

A disposable uses a full copy instead of an overlay

Its template must be a newly marked ASIF persistent VM created on macOS 27 or later, sealed, installed/stopped, and free of a snapshot stack. Older ASIF VMs, running templates, and snapshot-backed templates use the fallback copy path.

A linked disposable cannot be exported or converted

These operations are not implemented for linked overlays. Keep the base template available and collect needed artifacts to the host. Unsealing that base is also blocked until all its linked disposable VMs are deleted, not merely stopped.

The installer folder is missing

Enable its mount toggle and save. In the guest, open /Volumes/My Shared Files. Restart a CLI-owned or older runtime to pick up changes. If the build has no bundled installer package, the mount cannot expose one.

Guest Agent actions or clipboard sync fail

Check Boa Guest Agent mode, package installation inside the guest, an active guest desktop login, and that the VM is not suspended. Try Query Guest Info. Guest logs are /tmp/box-of-apples-guest-agent.stdout.log and /tmp/box-of-apples-guest-agent.stderr.log; installation logs are at /var/log/box-of-apples-guest-agent-install.log.

Endpoint Security has no events

Confirm both guest ES Monitor prerequisites say Granted. On the host, deploy subscriptions and start collection, then generate matching activity. Review the shared mute policy and event filters. Query Guest Info verifies the basic guest connection, not system-extension approval.

A schedule did not run

Check schedule/action Enabled toggles, weekdays, the host's local time, and the last result. Keep the app open and the host awake. Boot can be skipped by the two-VM guard; runbooks need an active agent session and cannot prompt for elevation.

The dashboard is unreachable

Check Server Mode and the status in Settings. Verify the configured port, bind address, and host IP; a localhost binding cannot be reached remotely. Keep the app open. For HTTPS, trust the generated certificate on the client. After token regeneration, sign in again.

A runbook cannot find its files

Sync Git artifact sources, confirm relative artifact paths, and reselect protected host folders with the folder chooser. Guest paths and host paths are different. Collect outputs before shutdown or discarding a disposable runtime.

CLI changes are not reflected in the app

Use Reload Library for images and VMs. Reopen the app after changing settings or schedules through the CLI so its in-memory configuration is refreshed.

When reporting a problem, include the Box of Apples build, host and guest macOS versions, relevant Lifecycle Log entries, and whether the VM was started by the app or the CLI.

Settings commands

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

boa settings show
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
boa settings set default-console-capture-size p1080
boa settings set default-screenshot-directory "$HOME/Pictures"
boa settings set default-recording-directory ""

boa settings set dashboard-bind-address 127.0.0.1
boa settings set dashboard-port 7427
boa settings set dashboard-security-mode http
boa settings set dashboard-enabled true

Reopen the desktop app after changing its settings through the CLI. The CLI writes configuration but does not run the Web Dashboard server itself. boa settings show --json includes the dashboard authentication token; keep that output private.

On macOS 27 or later, boa vm create defaults to ASIF when --disk-format is omitted, even if default-disk-format is set to raw. Pass --disk-format raw explicitly to create a raw-disk VM. This preference does not convert existing disks.

Image commands

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 <http-or-https-ipsw-url> [--json]
boa image delete --id <image-uuid>
boa image reveal --id <image-uuid>

discover-latest registers metadata; download-latest downloads the IPSW. Direct URL downloads honor allow-external-ipsw-urls. reveal opens the local image in Finder and requires a downloaded/imported file.

boa image download-latest
boa image import ~/Downloads/macOS.ipsw
boa image list --json
boa image show --id <image-uuid>

The alternative catalog browser and image renaming are available in the application and Web Dashboard, not as separate image CLI commands.

VM commands

Inspect a VM

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

list and show print runtime status in human-readable output; their JSON output contains VM definitions. show also prints Disk Backing: standalone, standalone, linked clones available, or linked ASIF overlay. The JSON definition includes diskBacking. logs returns lifecycle entries. Unlike the image reveal command, boa vm reveal prints the bundle path to the terminal.

Create and install

boa vm create \
  --image <image-uuid> \
  [--name <name>] \
  [--cpu-count <count>] \
  [--memory-mi-b <mib>] \
  [--disk-size <gib>] \
  [--disk-format asif|raw] \
  [--network nat|bridged] \
  [--randomize-serial-at-startup] \
  [--enable-guest-provisioning] \
  [--provisioning-full-name <full-name>] \
  [--provisioning-username <username>] \
  [--provisioning-password <password>] \
  [--provisioning-auto-login] \
  [--provisioning-remote-login] \
  [--enable-usb-passthrough] \
  [--usb-vendor-id <vendor-id>] \
  [--usb-product-id <product-id>] \
  [--json]

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

Creation makes a persistent VM; installation is a separate command. CPU and memory default to the image's minimum requirements. Disk size, network, and serial randomization use saved defaults when not supplied. Disk format defaults to ASIF on macOS 27 or later, otherwise to the saved preference; an explicit --disk-format takes precedence. New ASIF VMs on macOS 27 or later receive the linked-clone backing marker, reported in create/show output. Provisioning and USB options have the macOS 27 requirements described above. USB IDs accept decimal or 0x-prefixed hexadecimal values.

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

boa vm install --id <vm-uuid>
boa vm start --name Lab-Mac

Update configuration

boa vm update --id <vm-uuid> [options] [--json]

The audio, serial, and installer-mount options require explicit boolean values on update. The provisioning auto-login and remote-login options are enable-only flags; omit them to preserve existing values. The CLI accepts sshBootstrap as a stored mode, but the documented guest integration uses boaGuestAgent; it does not provide an SSH setup command.

boa vm update --id <vm-uuid> \
  --audio-output true \
  --audio-input false \
  --randomize-serial-at-startup false \
  --guest-agent-mode boaGuestAgent \
  --mount-guest-agent-installer true \
  --mount-es-monitor-installer true \
  --notes "Guest tools enabled"

There is no disk-resize or shared-folder-source option on vm update. Use the app for folder source editing. CLI updates save VM configuration; stop and start the runtime to apply it.

Start, stop, suspend, and resume

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

Supply either an ID or a name for each runtime command. --recovery applies to that boot only. suspend and resume currently require a headless CLI runtime; control app-managed sessions from the application or Web Dashboard. stop --force force-stops a headless CLI runtime.

boa vm start --name Lab-Mac --headless
boa vm suspend --name Lab-Mac
boa vm resume --name Lab-Mac
boa vm stop --name Lab-Mac

boa vm start --name Lab-Mac --recovery

The runtime-daemon subcommand is an internal implementation detail launched by vm start --headless; do not start it directly.

Snapshot commands

boa vm snapshot manages disk snapshots for a VM. Create, restore, and delete require a macOS 27 or later host and a stopped, unsealed persistent ASIF VM. Listing and metadata updates do not create or restore disk layers.

boa vm snapshot list --id <vm-uuid> [--json]

boa vm snapshot create \
  --id <vm-uuid> \
  [--name <name>] \
  [--notes <notes>] \
  [--tags <comma-separated-tags>] \
  [--json]

boa vm snapshot update \
  --id <vm-uuid> \
  --snapshot <snapshot-uuid> \
  [--name <name>] \
  [--notes <notes>] \
  [--tags <comma-separated-tags>] \
  [--favorite true|false] \
  [--json]

boa vm snapshot delete --id <vm-uuid> --snapshot <snapshot-uuid>
boa vm snapshot restore --id <vm-uuid> --snapshot <snapshot-uuid> [--json]

--id always identifies the VM; --snapshot identifies a saved point from its snapshot list. These commands do not accept a VM name selector. On create, --name names the new snapshot, not the VM. --favorite is an explicit boolean option on update, not an enable-only flag. Delete has no --json option.

Save and label a baseline

Shut down the VM using the app or its owning runtime's controls, then create a saved point:

boa vm snapshot create --id <vm-uuid> \
  --name "Before update" \
  --notes "Guest tools installed; ready to test" \
  --tags "baseline,before-update" \
  --json

boa vm snapshot list --id <vm-uuid> --json

boa vm snapshot update --id <vm-uuid> \
  --snapshot <snapshot-uuid> \
  --favorite true

Omitted update fields keep their current values. Use --notes "" or --tags "" to clear them, and --favorite false to remove a favorite. Tags are trimmed, deduplicated, and sorted. List output is newest-first; create/update JSON returns a snapshot record, while restore JSON returns the VM definition.

Restore or remove a saved point

Stop the VM and take another snapshot first if you need its current disk changes. Restore replaces the current writable layer; it does not prompt to save those changes or start the VM:

boa vm snapshot restore --id <vm-uuid> --snapshot <snapshot-uuid>
boa vm start --id <vm-uuid>

Delete only a snapshot with no child snapshots that is not the current writable layer's parent. There is no force-delete or flatten option. See snapshot requirements, restore behavior, and dependency rules. After CLI changes, use Reload Library in the app to refresh the catalog.

VM import and export

boa vm export --id <vm-uuid> --output <archive-path> [--json]
boa vm import --input <archive-path> [--json]

boa vm stop --name Lab-Mac
boa vm export --id <vm-uuid> --output ~/Desktop/Lab-Mac.boa-vm
boa vm import --input ~/Downloads/Lab-Mac.boa-vm

Export requires a stopped VM and adds .boa-vm when no extension is supplied. Linked-overlay disposables are rejected even when stopped; there is no flatten/materialize command. Standalone VM exports include their bundled snapshot catalog and disk layers. Use a macOS 27 or later host for snapshot-backed VMs.

Choose a new output path if you need to keep an existing archive. Import creates a new VM ID and bundle. Review external host paths and network/device settings after moving an archive to another Mac.

Template commands

boa template list [--json]
boa template seal --id <vm-uuid> [--json]
boa template unseal --id <template-uuid> [--json]
boa template create-disposable --id <template-uuid> [--name <name>] [--json]

boa vm stop --name Lab-Mac
boa template seal --id <vm-uuid>
boa template list
boa template create-disposable --id <template-uuid> --name Lab-Disposable
boa vm show --id <disposable-uuid>
boa vm start --name Lab-Disposable

Seal a configured, installed, stopped persistent VM. On macOS 27 or later, create-disposable automatically uses linked ASIF backing for eligible newly marked templates with no snapshot stack. Other templates use the full-copy path. Inspect Disk Backing with boa vm show; there is no separate CLI option to force linked backing.

Unseal before editing a baseline. A template with linked disposable dependents cannot be unsealed until those VMs are deleted from the library. Linked disposables cannot be exported or converted to persistent; use boa vm convert-persistent only for a stopped full-copy disposable source. Starting either disposable type still uses a temporary runtime clone, so collect results before stopping it. See the linked-disposable eligibility and dependency rules.

Scheduler commands

The CLI edits the same saved schedules used by the app. It does not run an independent scheduling service. Reopen the app after CLI schedule changes, and leave the app open and the host awake for execution.

boa scheduler list [--json]
boa scheduler show [--id <schedule-uuid> | --name <name>] [--json]
boa scheduler create --name <name> [--notes <notes>] [--disabled] [--json]
boa scheduler enable [--id <schedule-uuid> | --name <name>] [--json]
boa scheduler disable [--id <schedule-uuid> | --name <name>] [--json]
boa scheduler delete [--id <schedule-uuid> | --name <name>]

boa scheduler add-action \
  [--schedule-id <schedule-uuid> | --schedule-name <name>] \
  [--vm-id <vm-uuid> | --vm-name <name>] \
  --kind <boot|shutdown|suspend|resume|runbook> \
  --time <HH:mm> \
  [--name <action-name>] \
  [--weekdays <days>] \
  [--runbook-id <runbook-uuid>] \
  [--open-console] \
  [--headless] \
  [--force-stop] \
  [--disabled] \
  [--json]

boa scheduler remove-action \
  [--schedule-id <schedule-uuid> | --schedule-name <name>] \
  --action-id <action-uuid> \
  [--json]

For commands that select a schedule or VM, provide an ID or a unique name. Times use the host's local 24-hour clock. Weekdays default to daily; use comma-separated values such as mon,tue,wed,thu,fri. --runbook-id is required for runbook actions. Obtain saved runbook IDs from the runbooks API or exported runbook JSON.

--open-console and --headless configure boot actions; use one, with open-console taking precedence if both are supplied. With neither, the scheduler boots headlessly. --force-stop applies to shutdown actions. Schedules and actions are enabled at creation unless --disabled is supplied.

Example: a weekday lab

boa scheduler create --name Weekday-Lab --notes "Daily lab session"

boa scheduler add-action \
  --schedule-name Weekday-Lab \
  --vm-name Lab-Mac \
  --kind boot \
  --time 09:00 \
  --weekdays mon,tue,wed,thu,fri \
  --headless

boa scheduler add-action \
  --schedule-name Weekday-Lab \
  --vm-name Lab-Mac \
  --kind runbook \
  --runbook-id <runbook-uuid> \
  --time 09:05 \
  --weekdays mon,tue,wed,thu,fri

boa scheduler add-action \
  --schedule-name Weekday-Lab \
  --vm-name Lab-Mac \
  --kind shutdown \
  --time 18:00 \
  --weekdays mon,tue,wed,thu,fri

boa scheduler show --name Weekday-Lab --json
boa scheduler disable --name Weekday-Lab

The final command disables the example schedule. Re-enable it with boa scheduler enable --name Weekday-Lab when ready. Use show to find an action ID before removing it. To edit an existing action, use the GUI/Web Dashboard or remove it and add its replacement through the CLI. The scheduler execution rules apply to CLI-created schedules too.

Web API endpoint reference

All paths below are relative to /api/v1. Except for health and session creation, these routes require authentication. For JSON request bodies, send Content-Type: application/json.

VM summaries include diskImageFormat, diskBacking, snapshotCapability, and snapshots. Disk backing reports a kind of standalone or linkedOverlay, a supportsLinkedClones marker, and base/layer references when applicable. Treat this as reported storage state, not a client-editable setting. The capability's isSupported and optional reason describe current snapshot eligibility; dependency checks can still reject a deletion.

VM settings fields are name, cpuCount, memoryMiB, networkMode, bridgedInterfaceIdentifier, audioOutputEnabled, audioInputEnabled, randomizeSerialAtStartup, mountGuestAgentInstaller, mountESMonitorInstaller, guestAgentMode, and notes. Supply only the fields you want to update.

VM creation optionally accepts diskSizeGiB, diskImageFormat, networkMode, bridgedInterfaceIdentifier, randomizeSerialAtStartup, guestProvisioning, and usbPassthrough. Configure CPU and memory afterward through the settings endpoint. The Web Dashboard creation form provides the supported provisioning and USB fields.

Omitting diskImageFormat uses ASIF on macOS 27 or later; explicitly send "raw" to override it. New persistent ASIF VMs on macOS 27 or later receive the linked-clone marker. Disposable creation selects linked or copied backing from the template's eligibility; there is no request field to force linked backing.

Snapshot endpoints

Create, restore, and delete use the same stopped, unsealed persistent ASIF VM and macOS 27 host requirements as the native app. Saved points contain disk state, not live memory.

Action responses include virtualMachine, the updated snapshots array, a message, and the affected snapshot when applicable. Snapshot records include id, vmID, createdAt, name, notes, tags, isFavorite, layerRelativePath, and an optional parentSnapshotID. Layer paths and parent relationships are managed by the app.

Using the authentication setup, list and create snapshots on an eligible stopped VM:

curl --fail-with-body \
  --header "Authorization: Bearer $BOA_TOKEN" \
  "$BOA_URL/api/v1/vms/<vm-uuid>/snapshots"

curl --fail-with-body \
  --request POST \
  --header "Authorization: Bearer $BOA_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{"name":"Before update","notes":"Guest tools installed","tags":["baseline"]}' \
  "$BOA_URL/api/v1/vms/<vm-uuid>/snapshots"

curl --fail-with-body \
  --request POST \
  --header "Authorization: Bearer $BOA_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{"isFavorite":true}' \
  "$BOA_URL/api/v1/vms/<vm-uuid>/snapshots/<snapshot-uuid>"

Use "tags": [] to clear tags or "notes": "" to clear notes in an update body. Handle error responses before assuming an operation succeeded: unsupported hosts, active runtimes, sealed templates, and dependent layers can reject disk changes.

Guest execution requests also accept workingDirectory, requiresElevation, administratorPassword, capturedOutputPath, waitForExit, and timeoutSeconds. Use guest paths for working directories and output capture, and absolute host paths for host artifacts.

For schedule edits, read a schedule from GET /scheduler, retain its IDs and metadata, edit its fields, and send the complete object inside schedule to POST /scheduler/save. Action kinds in JSON are bootVirtualMachine, shutDownVirtualMachine, suspendVirtualMachine, resumeVirtualMachine, and runRunbook. Times use an hour/minute object; weekdays are numbers from 1 (Sunday) through 7 (Saturday). The scheduler CLI provides a simpler way to create schedules from a shell.