Hypervisor Backends

QuantaBox abstracts platform virtualization behind a single HypervisorBackend trait. Three concrete backends implement it -- KVM (Linux), Hyper-V (Windows), and Hypervisor.framework (macOS) -- with a TCG software fallback.

The Backend Trait #

Every backend implements a common interface:

vm_status returns a VmProcessStatus { pid, running, cpu_percent, memory_bytes }.

Detection #

Detection runs at startup and picks the first applicable backend:

Engine Binary Discovery #

Backends prefer a bundled quantabox-vmm and fall back to qemu-system-x86_64. Search order by platform:

Linux

/usr/bin/quantabox-vmm
/usr/local/bin/quantabox-vmm
-> fallback: /usr/bin/qemu-system-x86_64, /usr/local/bin/qemu-system-x86_64

Windows

%ProgramFiles%\QuantaBox\quantabox-vmm.exe
<exe dir>\quantabox-vmm.exe
-> fallback: C:\Program Files\qemu\qemu-system-x86_64.exe,
            C:\msys64\mingw64\bin\qemu-system-x86_64.exe

macOS

/opt/homebrew/bin/quantabox-vmm
/usr/local/bin/quantabox-vmm
/Applications/QuantaBox.app/Contents/MacOS/quantabox-vmm
-> fallback: /opt/homebrew/bin/qemu-system-x86_64, /usr/local/bin/qemu-system-x86_64

KVM Backend (Linux) #

• Acceleration: native KVM (--accel kvm).
• Machine/CPU: q35 machine, host CPU (passes through host features).
• SMP: built from the VM's cores x threads.
• Nested virt: supported.
• Process control: SIGTERM (graceful) / SIGKILL (force); SIGSTOP/SIGCONT for pause/resume; status via /proc.

Hyper-V Backend (Windows) #

• Acceleration: WHPX (-accel whpx) when available, otherwise TCG.
• Machine/CPU: q35; host CPU under WHPX, max under TCG.
• Detection: PowerShell query Get-WindowsOptionalFeature -Online -FeatureName Microsoft-Hyper-V (run without a console window).
• Drives/NICs: -drive per disk with the chosen format/bus; NIC model from config with -netdev user (NAT) including hostfwd for SSH when set.
• Display: -vnc localhost:<display>,websocket=<port> to feed the in-app noVNC console; -display none for the host window.
• Shared folders / USB: virtio-9p fsdev/virtio-9p-pci; usb-tablet plus optional usb-host passthrough.
• Unattended media: an autounattend floppy (Windows) or a cloud-init CD-ROM (Linux).
• Process control: taskkill /PID <pid> [/F]; status via tasklist /FI "PID eq <pid>" /NH.
• Logging: stdout/stderr are redirected to a log file in the VM's folder.

SSH Forwarding (NAT)

When ssh_host_port is set on a NAT adapter, the backend appends hostfwd=tcp::<host_port>-:22 to the first NIC's -netdev user, bound to localhost.

Shared Folders

For each share the backend emits:

-fsdev local,id=fsdev_<tag>,path=<host_path>,security_model=mapped-xattr[,readonly=on]
-device virtio-9p-pci,fsdev=fsdev_<tag>,mount_tag=<tag>

Mount tags are sanitized to alphanumerics, underscores, and hyphens.

Hypervisor.framework Backend (macOS) #

• Acceleration: --accel hvf.
• Machine/CPU: q35 on Intel, virt on Apple Silicon; host CPU.
• Nested virt: not supported.
• Binary: prefers quantabox-vmm-aarch64 on Apple Silicon, else quantabox-vmm / qemu-system-x86_64.
• Process control: POSIX signals, as with KVM.

TCG Software Fallback #

When no native backend is available, QEMU runs with TCG (pure software emulation). VMs still run, but slowly. quantabox status reports Hypervisor: None in this case.

Engine Identifiers #

The core uses the constants ENGINE_NAME = "QuantaVirt Engine" and VMM_BINARY = "quantabox-vmm" when locating and labelling the execution engine.