Start here:

1vm doctor          # host, entitlements, library, engines
1vm capabilities    # what this specific Mac can and cannot do
1vm logs <vm>       # guest serial and host lifecycle logs

logs takes --source guest|host|all, --lines N and --follow. Most "it just failed" questions are answered by the last few guest serial lines.

Every machine fails to start

Almost always the signature. The app must carry the virtualization entitlement, so a binary that has been moved out of the bundle or had its signature stripped cannot start anything. Reinstall from the original app rather than copying pieces of it around. 1vm doctor reports entitlement state directly.

The machine says it is running but there is no display

Check 1vm logs <vm> --source guest. A machine whose virtual CPUs exist is reported as running even if firmware never got as far as the guest — so "running" plus a black screen usually means a boot failure above the engine, not a missing window.

For Windows on the fallback Virtualization.framework engine, a black Setup screen is expected until the display driver binds. Use the 1VM engine instead, where ramfb lights Setup with no driver at all.

An x86 ISO will not boot

It cannot. Both engines run guest code natively on Apple silicon, so the guest must be ARM64. There is no emulation path and no conversion — you need an ARM64 build of the operating system. This is the single most common surprise, and it is what the Omarchy guide exists to explain in full.

Windows has no network

Install virtio-win's NetKVM driver. Windows has in-box drivers for NVMe and xHCI, which is why the disk and keyboard work immediately, but not for virtio-net. Attach the driver ISO at create time with --drivers.

The guest ran out of memory during install

Installers are the memory high-water mark, not the running system. Give the machine more and try again:

1vm stop dev --force
1vm set dev memory 8GiB
1vm start dev

If the Mac itself is under pressure, 1VMTool scales the profile down and tells you rather than overcommitting silently.

The keyboard is stuck in the guest

Tap the release chord — the console's status strip shows which combination is active for that window. It is configurable:

1vm get dev input.releaseChord

A setting will not change

Hardware changes on a running machine are refused unless the setting explicitly supports it. Stop the machine, change it, start it. Settings are validated when you set them, so the error names the actual problem rather than failing at next boot.

A script hangs or races

Use 1vm wait-ready <vm> rather than sleeping. "Running" means the machine is executing; "ready" means the guest is reachable over SSH or the guest agent. The gap between them is where flaky scripts live.

Getting back to a working state

1vm discard-session dev --force   # undo everything since this boot
1vm snapshot restore dev clean    # go to a named snapshot
1vm reset dev --force             # back to the clean state

If you skipped taking a snapshot, this is the moment to start: it costs nothing, and that is the whole point.