Architecture

QuantaBox is a layered system: two front ends (a Tauri desktop app and a CLI) over a shared Rust core, which drives a platform-specific hypervisor backend that launches QEMU.

Layered Design #

+-----------------------------------------------------------------+
|  Presentation                                                   |
|   - quantabox-gui -- Tauri shell + Svelte/TS frontend + noVNC   |
|   - quantabox-cli -- clap-based command line                    |
+-----------------------------------------------------------------+
|  Domain / Core                                                  |
|   - quantabox-core -- VM config & manager, disk, network,       |
|     snapshot, display, ssh, usb, shared_folders, unattended     |
|   - quantabox-crypto -- AES-256-GCM, ML-KEM-768, key vault     |
|   - quantabox-iso -- OS catalog + downloader + verification     |
|   - quantabox-backup -- export/import + encrypted backups       |
+-----------------------------------------------------------------+
|  Virtualization                                                 |
|   - Hypervisor backend trait: KVM / Hyper-V / HVF / (TCG)      |
|   - QEMU engine (qemu-system-x86_64, qemu-img)                 |
+-----------------------------------------------------------------+

The two front ends never talk to QEMU directly. They call quantabox-core, which owns all VM logic and delegates crypto, ISO, and backup concerns to the sibling crates.

Request Flow: Starting a VM #

1. Front end -- the user clicks Start (GUI) or runs quantabox start <vm> (CLI).
2. Core -- loads the VM's config.json, validates it (e.g. at least one disk must be attached), and selects the active hypervisor backend.
3. Backend -- translates the VmConfig into QEMU command-line arguments: machine type, acceleration flag, CPU model, SMP topology, memory, drives, NICs, display (VNC + WebSocket), shared folders, USB, and any unattended-install media.
4. Engine -- QEMU launches the VM. On Windows, helper processes are spawned without a console window; logs are written to the VM's folder.
5. Front end -- for the GUI, the console connects over the VM's VNC WebSocket once it is running; metrics and logs are polled for display.

Stopping, pausing, and resuming follow the same path, using platform-appropriate mechanisms (signals on POSIX, taskkill/process control on Windows).

Backend Selection #

At startup the core detects the best available acceleration:

It then locates an execution binary, preferring a bundled quantabox-vmm and falling back to qemu-system-x86_64 discovered in standard install locations. Full detail: Hypervisor Backends.

Data Directory #

All persistent state lives in one data directory, chosen per platform and overridable in Settings:

Layout:

<data-dir>/
+-- vms/
|   +-- <vm-id>/
|       +-- config.json     # the VM's configuration (see VM Configuration Format)
|       +-- <vm-id>.qcow2   # disk image(s) (.qvd when encrypted)
|       +-- ssh/            # generated SSH connection files
|       +-- *.log           # engine logs
+-- isos/                   # downloaded OS images
+-- backups/                # .qvbk backups

Because the GUI and CLI share this directory, changes made in one are immediately visible in the other.

Disk and Image Operations #

Disk lifecycle (create, resize, convert, info) is implemented over qemu-img. Snapshots use qemu-img snapshot and therefore require QCOW2/QVD images. See Disk Formats and Snapshots.

Display, SSH, Shared Folders, USB #

The core builds device configuration that the backend renders into QEMU arguments:

• Display -- a VNC server bound to localhost with a WebSocket port for the in-app noVNC console.
• SSH -- when a host port is forwarded to guest port 22 (NAT), the core generates ready-to-use connection material (command, OpenSSH config, batch and Bitvise profiles).
• Shared folders -- virtio-9p fsdev + virtio-9p-pci devices with a mapped-xattr security model.
• USB -- an xHCI/EHCI controller plus optional usb-host passthrough by vendor/product ID, enumerated per platform.

Unattended Installation #

When unattended install is enabled, the core generates boot media that the backend attaches to the VM:

• Linux (cloud-init): an ISO 9660 image labelled cidata containing meta-data, user-data, and network-config. It creates the user with sudo, sets locale/timezone/hostname, enables DHCP on the virtio NIC, and installs the guest agent. Passwords are hashed with SHA-512 (via OpenSSL when available).
• Windows: a FAT12 floppy image carrying autounattend.xml that partitions the disk (EFI/MSR/NTFS), creates the user, enables auto-logon, and bypasses OOBE screens. IANA timezones are mapped to Windows timezone names.

The ISO 9660 and FAT12 images are produced by minimal in-house builders, so no external tooling is required.

Cross-Platform Process Handling #

All child-process invocations (QEMU, qemu-img, PowerShell probes, taskkill, etc.) go through a small helper that suppresses console windows on Windows (CREATE_NO_WINDOW) and is a no-op elsewhere -- so the GUI never flashes terminal windows. See Components.

Where to Go Next #