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 doctor shows 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 create

This 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 ready

hoy 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 demo
  • hoy create clones the image in seconds and uses no extra disk until the guest writes. It prints created demo (stopped) and the command to start it: creating a VM does not boot it. Use the image name that hoy images shows: a plain name always means the newest image of that name that passed its tests.
  • hoy start --wait ready boots the VM and returns when ssh answers.
  • hoy ssh demo opens 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 -a runs 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 list

hoy 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 demo

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