Quickstart
Make a macOS image on your Mac, create and start a VM, ssh in, list your VMs, then stop and remove the VM.
Make a macOS image, create a VM from it, ssh in, and clean up. In short:
make an image once, create a VM from it, start it, open its desktop. create
does not start the VM.
Prerequisites#
- Hoy installed, the Hoy system extension approved, and
hoy doctorshows no failed check. - 64 GiB of free disk for the first image.
Make an image#
A VM is made from an image: a macOS install that was set up once and is stored read-only. You make the image on your own Mac, from Apple's macOS restore image. Hoy contains no Apple software, and Cua does not hand out macOS.
hoy image createThis downloads the newest macOS restore image your Mac supports from Apple (20 to 26 GB, resumable, kept for the next build), installs it, sets up a user and ssh without clicking through Setup Assistant, and tests the result. With the download already done it takes about 6 minutes, and the finished image takes about 27 GiB on disk. Run it once. If it fails, the output names the step; run the same command again and the download is reused.
It prints five steps. Step 5 stores the image (copying about 27 GiB, a few minutes) and then runs a smoke test that can take up to 15 minutes. Both print a line every 30 seconds so you can see it is working.
While it runs, hoy images in another terminal lists the build:
building: macOS 27.2.1 (24C101), step 5 of 5, storing the image, 14 min 0 s so far (not tested until it finishes). An older image in the same list is a
different, finished image. When the build ends, hoy image create prints the
total time and the exact commands to run next:
image macos-27.2.1:1 is ready (sha256:...)
macOS 27.2.1 (24C101), 27.2 GiB on disk, built in 12 min 30 s
tested: yes (a plain `macos-27.2.1` always means the newest image of this name that passed its smoke test)
Next: make a VM from it, then start it. Creating a VM does not boot it.
hoy create demo --image macos-27.2.1
hoy start demo --wait readyhoy images lists your images, whether each one passed its test, and which version a plain image name picks.
Create, start and ssh in#
hoy create demo --image macos-26.5.2
hoy start demo --wait ready
hoy ssh demohoy createclones the image in seconds and uses no extra disk until the guest writes. It printscreated demo (stopped)and the command to start it: creating a VM does not boot it. Use the image name thathoy imagesshows: a plain name always means the newest image of that name that passed its tests.hoy start --wait readyboots the VM and returns when ssh answers.hoy ssh demoopens a shell in the VM. It uses the VM's own address, user and key, so you do not copy any of them.hoy ssh demo -- uname -aruns one command and exits with its exit code.
hoy create also takes --cpu, --memory 8G and --disk 150G (the disk only
grows). Add --vnc to get a desktop you can open with hoy vnc demo, or
--profile headless for a VM with no desktop session. Every option is in the
CLI reference.
hoy exec demo -- sw_vers runs one command in the guest and exits with its exit
code. hoy restart demo reboots the guest from inside.
If hoy start is refused with exit code 5, the Hoy system extension is not on
yet, or two macOS VMs already run. See Limits.
List your VMs#
hoy listhoy ps and hoy ls do the same. hoy inspect demo shows one VM in detail:
address, resources, identity and clipboard settings.
Stop and remove#
hoy stop demo
hoy rm demohoy stop is an ordered stop: it flushes the guest's disk, asks the guest to
shut down, and only forces it off after 60 seconds. hoy rm deletes the VM, its
disk and all of its snapshots, for good. The image stays, so you can create
another VM from it.
At a terminal, hoy rm asks first and says what goes:
Delete VM "demo"? This removes its disk (23 GB used) and 3 snapshots. It can't be undone. [y/N]Only y or yes deletes. Anything else, or just Enter, cancels and deletes
nothing. Afterwards it says what it freed: deleted demo: freed 23 GB, removed 3 snapshots. Add --yes (or -y) to skip the question.
In a script, in CI, or with --json, hoy rm never asks. A VM without
snapshots is deleted straight away. A VM with snapshots is not: hoy rm exits
with code 2 and says demo has 3 snapshots; add --yes to delete the VM and its snapshots. With --json, the answer reports disk_bytes, snapshot_count,
snapshot_bytes and freed_bytes.
Every command takes --json for scripts. Exit codes are in
Troubleshooting.
Next#
- Snapshots and restore: save a running VM and go back to it.
- Import VMs from Tart, UTM and Lume
- CLI reference
- Clipboard sharing: copy and paste between your Mac and a VM.