x86_64 guest on Linux (KVM)

Condensed from the driver README. This pathway boots an x86_64 macOS 13 Ventura guest under KVM with the device attached as reims-vgpu-pci and the host GPU driven through Vulkan.

1. Host prep

• KVM available at /dev/kvm.
• A working Vulkan stack (NVIDIA or other).
• Build dependencies for the in-tree QEMU.
• KVM must ignore unhandled MSRs or macOS will not boot — set options kvm ignore_msrs=1 in a modprobe conf, then reboot or reload the module.

2. Provision with OSX-KVM

Guest provisioning uses OSX-KVM: fetch recovery media, build OpenCore, and install macOS 13 under QEMU+KVM until you have a working post-Setup-Assistant guest plus the OpenCore/OVMF pieces. The goal is the artifacts, not OSX-KVM’s launcher long-term.

3. Place artifacts

vm/boot-x86.sh expects these defaults (env-overridable):

Artifact	Default location
Guest system disk	vm/disks/macos.img
OpenCore boot disk	vm/disks/OpenCore.qcow2
OVMF code	vm/ovmf/OVMF_CODE_4M.fd
OVMF vars template	vm/ovmf/OVMF_VARS-1920x1080.fd

Finish in-guest setup: enable Remote Login, install your SSH key, disable sleep and the screensaver. Host SSH is localhost:2222 → guest :22.

4. Capture the golden snapshot

Boot in capture mode and shut down cleanly from inside the guest:

vm/boot-x86.sh --snapshot --device vmware-svga

5. Day-to-day boots

# Console-only VGA while debugging the host stack
vm/boot-x86.sh --testing --device vmware-svga

# Product device (needs in-tree QEMU + reims-vgpu Vulkan)
REIMS_VGPU_BACKEND=vulkan scripts/qemu-build/qemu-build.sh --target x86_64
vm/boot-x86.sh --testing --device reims-vgpu-pci

# Host-window screenshot (KDE Plasma host)
scripts/screenshot-when-kde-plasma-host/screenshot-when-kde-plasma-host.sh -o /tmp/screen.png

Every boot clones snapshots/current (COW when possible) and throws the clone away on exit, so wedges and hard kills never poison the golden image. Use --testing for time-bounded runs and --interactive for open-ended GUI sessions.