QuantaVirt Installation Guide

This guide covers installing QuantaVirt as a bare-metal hypervisor on physical hardware, including firmware preparation, bootloader configuration, QUAC 100 driver setup, and building from source. For your first VM after installation, continue to Getting Started.

System Requirements #

Build Dependencies (Source Installation)

Firmware Setup (BIOS/UEFI) #

Before installing QuantaVirt, enable hardware virtualization extensions and IOMMU in your system firmware. The exact menu locations vary by motherboard manufacturer, but the settings are typically found under "CPU Configuration" or "Advanced" menus.

Intel Systems

AMD Systems

ISO Installation #

The QuantaVirt installer ISO boots the host machine, partitions storage, installs the hypervisor, and configures the bootloader. Download the ISO from the Downloads page.

Creating a Bootable USB

# Linux — use dd (replace /dev/sdX with your USB device)
sudo dd if=quantavirt-0.1.0-x86_64.iso of=/dev/sdX bs=4M status=progress oflag=sync

# Windows — use Rufus or Etcher
# Select the ISO, choose DD mode, write to USB

# macOS
sudo dd if=quantavirt-0.1.0-x86_64.iso of=/dev/rdiskN bs=4m

Installation Steps

Boot from the USB device and follow the text-mode installer. The installer performs four stages: hardware detection (verifying VMX/SVM, IOMMU, QUAC 100 presence), disk partitioning (hypervisor root, boot partition, swap, VM storage pool), hypervisor installation (kernel, drivers, management daemon), and bootloader configuration (GRUB or systemd-boot depending on boot mode).

Installer Disk Layout

GRUB Bootloader Setup #

QuantaVirt uses the Multiboot2 protocol for GRUB integration. The hypervisor kernel is loaded as a Multiboot2 payload, with memory map, framebuffer, and module information passed via the Multiboot2 information structure.

GRUB Configuration

# /boot/grub/grub.cfg — QuantaVirt entry
menuentry "QuantaVirt 0.1.0" {
    multiboot2 /boot/quantavirt/quantavirt.bin
    module2    /boot/quantavirt/initramfs.img
    module2    /boot/quantavirt/quac100-fw.bin
    boot
}

# Alternative: with kernel command-line parameters
menuentry "QuantaVirt 0.1.0 (debug)" {
    multiboot2 /boot/quantavirt/quantavirt.bin loglevel=debug serial=on,115200n8 iommu=on
    module2    /boot/quantavirt/initramfs.img
    boot
}

Kernel Parameters

systemd-boot Setup #

On UEFI systems, QuantaVirt can be booted via systemd-boot using the UEFI stub loader. The hypervisor is packaged as a unified kernel image (UKI) that combines the kernel, initramfs, and command line into a single signed EFI binary.

# /boot/efi/loader/entries/quantavirt.conf
title    QuantaVirt 0.1.0
efi      /EFI/quantavirt/quantavirt.efi
options  loglevel=info iommu=on sched=credit2 api=unix

# /boot/efi/loader/loader.conf
default  quantavirt.conf
timeout  5
editor   no

QUAC 100 Driver Installation #

If a QUAC 100 PCIe card is installed, QuantaVirt will detect it during boot via PCI enumeration (vendor 0x1DB7, device 0x0100). The QUAC 100 driver is built into the hypervisor kernel — no separate driver installation is required for the hypervisor itself.

Verifying QUAC 100 Detection

# Check QUAC 100 status from CLI
quantavirt crypto show

# Expected output:
PQC Backend:     QUAC 100 Hardware (CRYPTO_BACKEND_QUAC100)
Device:          0000:03:00.0 [1DB7:0100]
Firmware:        1.0.0 (build 2026.01.15)
BAR0 (MMIO):     0xfe000000 (64 KB)
BAR2 (DMA):      0xfd000000 (1 MB)
Command Ring:    512 entries, head=0 tail=0
Response Ring:   512 entries, head=0 tail=0
QRNG Status:     Healthy (entropy rate: 100 Mbps)
Key Slots:       0 / 256 used
Algorithms:      ML-KEM-512/768/1024, ML-DSA-44/65/87, AES-256-GCM, SHA-3, SHAKE

Firmware Update

# Update QUAC 100 firmware from management shell
quantavirt crypto firmware-update --file quac100-fw-1.0.1.bin --verify

# The card will be unavailable during update (~30 seconds)
# PQC subsystem falls back to software during this time

Building from Source #

# Clone the repository
git clone https://github.com/dyber-pqc/quantavirt.git
cd quantavirt

# Install build dependencies (Ubuntu/Debian)
sudo apt install cmake gcc g++ nasm python3 mtools xorriso \
     libssl-dev pkg-config

# Install Rust (if not already)
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source $HOME/.cargo/env

# Build everything (hypervisor + PQC + tools)
mkdir build && cd build
cmake .. -DCMAKE_BUILD_TYPE=Release
make -j$(nproc)

# Build CLI and GUI (Cargo workspace)
cd ../tools
cargo build --release --workspace

# Create bootable ISO
cd ../build
make iso

# Output: quantavirt-0.1.0-x86_64.iso

CMake Build Options #

Package Installation #

Ubuntu / Debian

# Add Dyber repository
curl -fsSL https://pkg.dyber.org/gpg.key | sudo gpg --dearmor -o /usr/share/keyrings/dyber.gpg
echo "deb [signed-by=/usr/share/keyrings/dyber.gpg] https://pkg.dyber.org/apt stable main" | \
  sudo tee /etc/apt/sources.list.d/dyber.list

# Install packages
sudo apt update
sudo apt install quantavirt            # Hypervisor + bootloader integration
sudo apt install quantavirt-cli        # CLI management tool
sudo apt install quantavirt-gui        # Desktop GUI application

RHEL / Fedora

# Add Dyber repository
sudo dnf config-manager --add-repo https://pkg.dyber.org/rpm/dyber.repo

# Install packages
sudo dnf install quantavirt quantavirt-cli quantavirt-gui

GUI Application Installation #

The QuantaVirt GUI is a Tauri/Svelte desktop application that connects to the QuantaVirt management API. It runs on a separate management workstation — not on the hypervisor host itself.

After installation, launch the GUI and configure the connection to your QuantaVirt host. By default, the management API listens on a Unix socket (/run/quantavirt/api.sock). For remote management, configure the API to listen on TCP (see Management API).

Verifying Installation #

# Check hypervisor version
quantavirt --version
# QuantaVirt 0.1.0 (build 2026.01.15)

# Check system status
quantavirt system show

# Expected output:
Hypervisor:      QuantaVirt 0.1.0
Architecture:    x86_64
CPU Vendor:      GenuineIntel / AuthenticAMD
Virtualization:  VMX (Intel) / SVM (AMD)
IOMMU:           Intel VT-d / AMD-Vi [active]
Physical CPUs:   16 cores (32 threads)
Total Memory:    64 GB (60 GB available for VMs)
Hugepages:       1024 × 2MB allocated
PQC Backend:     QUAC 100 Hardware / Software Fallback
QUAC 100:        Detected at 0000:03:00.0 / Not Present
API Socket:      /run/quantavirt/api.sock [listening]
Active VMs:      0
Uptime:          0d 0h 5m 23s

# Run self-test suite
quantavirt system self-test
# Tests: VMX/SVM entry/exit, EPT/NPT walk, VirtIO probe, PQC ops, QRNG health

Uninstalling #

To remove QuantaVirt, shut down all running VMs, then remove the package and bootloader entry. VM disk images in /var/lib/quantavirt are not removed automatically — back them up or delete them manually.

# Stop all VMs
quantavirt vm list --format=id | xargs -I{} quantavirt vm stop {}

# Remove packages (Ubuntu/Debian)
sudo apt remove quantavirt quantavirt-cli quantavirt-gui

# Remove bootloader entry (GRUB)
sudo rm /boot/grub/grub.cfg.d/quantavirt.cfg
sudo update-grub

# Optional: remove VM images
sudo rm -rf /var/lib/quantavirt