Architecture

Virtualization integration

QEMU discovery, launch, QMP lifecycle, Linux KVM, and the console transport.

Wave VM uses direct QEMU integration rather than making libvirt a mandatory dependency. The current virtualization layer covers discovery, disk creation, process launch, QMP lifecycle control, and the guest console.

What is implemented

A QEMU system emulator name is selected from the host architecture. Unknown architectures produce an unsupported result.
QEMU and qemu-img are discovered through bundled resources, PATH, and standard platform locations.
Each executable is probed directly with a version flag and a five-second timeout. The probe does not use a shell command string.
On Linux, KVM is verified by opening /dev/kvm and issuing KVM_GET_API_VERSION.
QCOW2 disks are created with qemu-img and are never overwritten.
QEMU is launched with typed argument vectors, a private QMP Unix socket, and no guest network device.
KVM is used when verified; otherwise QEMU uses TCG software emulation.
Start and stop use QMP with bounded process-termination fallbacks.
A running machine exposes a loopback-only WebSocket VNC listener for the bundled noVNC console.

What is not implemented

Guest operating system installation or installation media attachment.
Guest networking or USB passthrough.
Reset, pause, resume, or snapshot operations.
Machine editing or deletion.
Windows and macOS host verification.
Bundled QEMU distribution or release packaging.

The lifecycle is real, the guest is not installed

Wave VM starts a real QEMU process and shows its actual framebuffer. It does not provide a guest operating system. A blank QCOW2 disk may boot to firmware output or a no-bootable-device message until installation media is implemented.

Lifecycle boundary

QEMU arguments are constructed through typed vectors, never shell command strings. The process is tracked, duplicate launches are blocked, and persisted runtime state is reconciled when the application starts. QMP and the console listener are local-only. A force-killed desktop process can still leave an orphaned QEMU child; automatic recovery from that case is not guaranteed.

Source references

qemu/discovery.rs — executable discovery.
qemu/probe.rs — version probing.
host/kvm.rs — Linux KVM verification.
vm/runtime.rs — QEMU launch, QMP lifecycle, console session, and termination.
qmp.rs — QMP client.

Read Machine lifecycle for the user-facing behavior, or Security model for the control boundary.