cocoon-macos vm stop m1
cocoon-macos vm snapshot m1 --tag clean
cocoon-macos vm restore m1 --tag clean # --force: power down, restore, relaunch a running VM
--force on a running VM keeps its VNC display across the relaunch. A display
that was started with --vnc-password (every CNI display, optionally others)
needs the password again: pass --vnc-password to restore, or stop, restore
and start --vnc N --vnc-password; without it the restore is refused before
any disk is touched. VMs launched by a cocoon-macos older than this rule with a
passworded non-CNI display are not recognised as password-gated until their
next stop or start.
A forced restore quiesces CNI forwarding after stopping QEMU and restores forwarding only after
the relaunch succeeds. An apply failure leaves the VM stopped; a relaunch error leaves forwarding
quiesced. After resolving the failure, retry restore or use vm start, which also restores forwarding
when it adopts an already-running QEMU after a failed record write.
Snapshots are offline qcow2-internal (qemu-img snapshot, VM stopped) and cover the system disk,
every data disk, and OVMF_VARS when it is qcow2 (a raw .fd NVRAM has no internal-snapshot
support, so with raw NVRAM only guest disk state rolls back). Live RAM snapshot is intentionally
impossible here: -cpu +invtsc makes the macOS guest non-migratable, so resume-from-RAM can’t work.
This is by design (see Roadmap).
cocoon-macos vm clone m1 -n m2 --ssh-port 2223 --random-smbios
A clone bakes a fresh copy-on-write overlay on the shared base (never on SRC’s per-VM overlay,
which would break on vm rm m1), and that base is the exact blob SRC was built from, by its
recorded digest; only if that blob has left the store does the clone fall back to whatever SRC’s
image ref resolves to now, with a warning. It cold-boots a fresh Apple identity when --random-smbios
is given to the clone (or inherited automatically when SRC already carries one) — without it, the
clone shares SRC’s serial. With a fresh identity, user, tap, and bridge use its ROM MAC;
cni always uses the provider MAC. Without one, auto-created tap/bridge use a provider MAC,
while user and pre-created --tap use QEMU’s non-unique default. Clones copy SRC’s data disks
and can add more; a clone-of-a-clone keeps a correct backing chain. SRC must be stopped while its
OVMF variables and data disks are copied.
--data-disk)--data-disk (on run / create / clone) attaches empty qcow2 data disks. It is repeatable with
comma-separated key=value:
cocoon-macos vm run <IMAGE> --data-disk size=20G --data-disk name=scratch,size=50G
size= (required, Docker or Kubernetes spelling — 20G, 20Gi, 20GiB — min 16 MiB) and name=
(optional, [a-z][a-z0-9_-]{0,19} and not starting with cocoon-, default data1, data2, …;
duplicates error).ich9-ahci controller’s free SATA ports — OpenCoreBoot (sata.2) and MacHDD (sata.4) leave
ports 0, 1, 3, 5.fstype= / mount= / directio= are rejected: a macOS guest has no
cloud-init/agent to partition, format, or mount the disk. It is attached raw — format it in the
guest with Disk Utility or diskutil.