Getting Started with QuantaVirt

Create and boot your first virtual machine on QuantaVirt. This guide walks through VM creation using both the CLI and GUI, from disk image creation through guest OS installation. Assumes QuantaVirt is already installed per the Installation Guide.

Quick Overview #

Creating a VM on QuantaVirt involves four steps: create a disk image for the guest, write a VM configuration file (JSON), create the VM from that configuration, and start it. QuantaVirt handles all hardware-level setup — VMCS/VMCB allocation, EPT/NPT page table construction, device emulation, and interrupt routing — automatically.

First VM via CLI #

This walkthrough creates a minimal Linux VM with 2 vCPUs, 2 GB RAM, a 20 GB disk, and VirtIO devices. We'll install Ubuntu Server 24.04 as the guest.

Step 1 — Creating a Disk Image #

# Create a 20 GB qcow2 disk image
quantavirt storage create \
  --name ubuntu-root \
  --format qcow2 \
  --size 20G \
  --path /var/lib/quantavirt/images/ubuntu-root.qcow2

# Output:
Created disk image: ubuntu-root
  Format:  qcow2
  Size:    20 GiB (virtual), 196 KiB (actual)
  Path:    /var/lib/quantavirt/images/ubuntu-root.qcow2

Step 2 — VM Configuration File #

Create a JSON configuration file that defines the VM's hardware. Save this as /var/lib/quantavirt/configs/ubuntu-server.json:

{
  "name": "ubuntu-server",
  "description": "Ubuntu Server 24.04 LTS",

  "cpu": {
    "count": 2,
    "model": "host",
    "features": ["+aes", "+avx2", "+sse4_2"]
  },

  "memory": {
    "size": "2G",
    "hugepages": false
  },

  "devices": {
    "storage": [
      {
        "type": "virtio-blk",
        "path": "/var/lib/quantavirt/images/ubuntu-root.qcow2",
        "boot_index": 1
      },
      {
        "type": "virtio-blk",
        "path": "/path/to/ubuntu-24.04-live-server-amd64.iso",
        "readonly": true,
        "media": "cdrom",
        "boot_index": 0
      }
    ],
    "network": [
      {
        "type": "virtio-net",
        "network": "default",
        "mac": "auto"
      }
    ],
    "console": {
      "type": "virtio-console"
    },
    "graphics": {
      "type": "virtio-gpu",
      "vnc": {
        "listen": "127.0.0.1",
        "port": 5900
      }
    }
  },

  "boot": {
    "order": ["cdrom", "disk"],
    "uefi": true
  }
}

Configuration Fields

For the complete configuration schema with all available fields, see the Configuration Reference.

Step 3 — Booting & Installing a Guest #

# Create the VM from config
quantavirt vm create --config /var/lib/quantavirt/configs/ubuntu-server.json

# Output:
Created VM: ubuntu-server
  UUID:    a3f1c7d2-8e4b-4a6f-9c2d-1b5e3f7a8d0c
  vCPUs:   2
  Memory:  2 GiB
  Storage: 2 devices (virtio-blk × 2)
  Network: 1 interface (virtio-net, network=default)
  Console: VNC on 127.0.0.1:5900

# Start the VM
quantavirt vm start ubuntu-server

# Output:
Starting VM: ubuntu-server
  VMCS allocated, EPT constructed
  VirtIO devices initialized
  UEFI firmware loaded
  VM entered VMX non-root mode
  State: RUNNING

# Connect via VNC to complete guest OS installation
# Use any VNC client: virt-viewer, TigerVNC, Remmina
vncviewer 127.0.0.1:5900

# Or connect via serial console
quantavirt vm console ubuntu-server

The VM will boot from the Ubuntu ISO. Complete the standard Ubuntu Server installation through the VNC or serial console. After installation, shut down the guest, remove the CDROM from the configuration or change the boot order, and start the VM again to boot from the installed disk.

Basic VM Operations #

# List all VMs
quantavirt vm list
# NAME              STATE     vCPUs   MEM     UPTIME
# ubuntu-server     running   2       2 GiB   0:12:34

# Show detailed VM information
quantavirt vm show ubuntu-server

# Pause / Resume
quantavirt vm pause ubuntu-server
quantavirt vm resume ubuntu-server

# Graceful shutdown (ACPI power button)
quantavirt vm stop ubuntu-server

# Force power off (immediate)
quantavirt vm stop ubuntu-server --force

# Reset (equivalent to hardware reset button)
quantavirt vm reset ubuntu-server

# Delete VM (preserves disk images)
quantavirt vm destroy ubuntu-server

# Delete VM and its disk images
quantavirt vm destroy ubuntu-server --delete-storage

VM Lifecycle States

First VM via GUI #

The QuantaVirt GUI provides a creation wizard that walks through the same steps visually. Launch the application and connect to your QuantaVirt host.

From the dashboard, click + New VM to open the creation wizard. The wizard has five panels: General (name, description), Hardware (vCPUs, memory, CPU model), Storage (add disks, attach ISOs), Network (select virtual network, MAC address), and Review (summary before creation). After creation, click the â–¶ Start button on the VM card to boot. The built-in VNC viewer opens automatically for console access.

For detailed GUI documentation, see the GUI Guide.

Basic Networking #

QuantaVirt creates a default virtual network during installation that provides NAT-based connectivity. VMs attached to this network receive DHCP addresses and can reach the internet through the host's network stack.

# Show the default network
quantavirt network show default
# Name:     default
# Mode:     NAT
# Bridge:   qvbr0
# Subnet:   10.0.100.0/24
# Gateway:  10.0.100.1
# DHCP:     10.0.100.100 – 10.0.100.254
# DNS:      10.0.100.1 (forwarding)

# Create a bridged network (direct access to physical LAN)
quantavirt network create \
  --name office-lan \
  --mode bridge \
  --interface eth0

For advanced networking — VLANs, PQC-encrypted tunnels, multiple bridges, and firewall rules — see the Networking Guide.

Enabling PQC #

QuantaVirt's PQC subsystem is active by default. If a QUAC 100 is present, all PQC operations are hardware-accelerated. You can enable per-VM PQC features in the configuration:

{
  "name": "secure-vm",
  "cpu": { "count": 4, "model": "host" },
  "memory": { "size": "8G" },

  "pqc": {
    "enabled": true,
    "backend": "auto",
    "attestation": {
      "enabled": true,
      "algorithm": "ML-DSA-65"
    },
    "storage_encryption": {
      "enabled": true,
      "kem": "ML-KEM-768",
      "aead": "AES-256-GCM"
    }
  },

  "devices": {
    "storage": [{
      "type": "virtio-blk",
      "path": "/var/lib/quantavirt/images/secure-root.qcow2",
      "encrypted": true
    }]
  }
}

# Check PQC status for a VM
quantavirt crypto show --vm secure-vm
# Attestation:      Enabled (ML-DSA-65)
# Storage Encrypt:   Enabled (ML-KEM-768 + AES-256-GCM)
# Backend:           QUAC 100 Hardware
# QRNG:              Active (entropy OK)

# Generate attestation report
quantavirt crypto attest secure-vm --output report.json

For the full PQC feature set — algorithm selection, QUAC 100 register-level details, confidential computing, and key management — see PQC & Security.

Next Steps #