Installation

This chapter covers installing QuantaBox on each supported platform, installing the QEMU engine it depends on, and enabling hardware acceleration. For download links and system requirements, see Downloads.

Before You Begin #

QuantaBox needs two things to run guests well:

1. The QEMU engine: the execution layer that runs virtual hardware.
2. Hardware acceleration: your CPU's virtualization extensions, exposed through a platform backend (KVM, Hyper-V/WHPX, or Hypervisor.framework). Without it, VMs still run but only under slow software emulation.

You can install QuantaBox first and add these afterward; quantabox status will tell you what is detected.

Windows #

1. Download QuantaBox-1.0.0-Setup-x64.exe from Downloads.
2. Run the installer. Accept the license agreement.
3. Choose an install location (default: C:\Program Files\Dyber\QuantaBox).
4. Select optional components: desktop shortcut, file associations for .qcow2/.ova, and the bundled QEMU engine if offered.
5. Finish. Launch QuantaBox from the Start Menu or desktop shortcut.

Enabling acceleration (recommended)

QuantaBox uses the Windows Hypervisor Platform (WHPX). Enable it once:

1. Open Turn Windows features on or off.
2. Tick Windows Hypervisor Platform (and Hyper-V if you also want it).
3. Reboot.
4. Ensure CPU virtualization (Intel VT-x / AMD-V) is enabled in your firmware/BIOS.

Confirm with quantabox status. The Hypervisor line should read Hyper-V.

Linux #

Install the package for your distribution:

# Debian / Ubuntu / Mint / Pop!_OS
sudo apt install ./quantabox_1.0.0_amd64.deb

# Fedora / RHEL / Rocky / AlmaLinux
sudo dnf install ./quantabox-1.0.0-1.x86_64.rpm

# Any distro (portable)
chmod +x QuantaBox-1.0.0-x86_64.AppImage
./QuantaBox-1.0.0-x86_64.AppImage

Enabling KVM acceleration

1. Confirm your CPU supports virtualization and it is enabled in firmware.
2. Verify the KVM device exists:

   ls -l /dev/kvm

3. Add your user to the kvm group so QuantaBox can access it without root:

   sudo usermod -aG kvm "$USER"

   Log out and back in for the group change to take effect.

Confirm with quantabox status. The Hypervisor line should read KVM.

macOS #

1. Download QuantaBox-1.0.0-universal.dmg from Downloads.
2. Open the disk image and drag QuantaBox into Applications.
3. On first launch, macOS may warn about an app downloaded from the internet. Open it via right-click, then select Open to confirm.

Acceleration on macOS

macOS provides Hypervisor.framework out of the box on both Intel and Apple Silicon. Nothing to enable. quantabox status should report Hypervisor.framework.

The QEMU Engine #

QuantaBox runs guests through QEMU. The Windows installer can bundle a compatible build. On Linux and macOS, install QEMU from your package manager:

# Debian / Ubuntu
sudo apt install qemu-system-x86 qemu-utils

# Fedora / RHEL family
sudo dnf install qemu-kvm qemu-img

# macOS (Homebrew)
brew install qemu

QuantaBox searches standard install locations automatically, including:

• Windows: C:\Program Files\qemu\, MSYS2 mingw64\bin
• Linux: /usr/bin, /usr/local/bin
• macOS: /opt/homebrew/bin, /usr/local/bin

It needs both qemu-system-x86_64 (to run VMs) and qemu-img (to manage disks). Verify detection:

quantabox status

The QEMU line shows the detected version, or not found if it could not be located. If QEMU is installed in a non-standard path, set its location in Settings > Engine.

First-Run Data Directory #

On first launch QuantaBox creates a data directory that stores your VMs, downloaded ISOs, snapshots, and backups:

You can change this in Settings. The directory contains subfolders such as vms/, isos/, and backups/.

Verifying the Installation #

Run a quick health check:

quantabox status

A healthy install reports the app version, a detected hypervisor (or None for software fallback), your platform and architecture, the encryption suite (ML-KEM-768 + AES-256-GCM), the data directory, and a detected QEMU version.

You are ready to move on to Getting Started.