VM Configuration Schema

QV-REF-SCHEMA Rev 1.0 — January 2026 Reference

Complete JSON schema reference for QuantaVirt VM configuration files. Every field, type, constraint, default value, and validation rule for defining virtual machines.

Schema Overview #

VM configurations are JSON files passed to quantavirt vm create --config <file.json>. The schema version is 1.0. All sizes accept human-readable suffixes: K, M, G, T (powers of 1024).

{
  "name":        /* required — string */
  "description": /* optional — string */
  "uuid":        /* optional — auto-generated UUID v4 */
  "cpu":         /* required — object */
  "memory":      /* required — object */
  "storage":     /* required — array of disk objects */
  "network":     /* optional — array of NIC objects */
  "console":     /* optional — object */
  "graphics":    /* optional — object */
  "usb":         /* optional — array of USB device objects */
  "boot":        /* optional — object */
  "pqc":         /* optional — object */
  "migration":   /* optional — object */
  "security":    /* optional — object */
}

Top-Level Fields #

FieldTypeRequiredDefaultConstraintsDescription
namestring✅—1–64 chars, [a-zA-Z0-9._-]Unique VM name used in CLI/API
descriptionstring❌""0–512 charsHuman-readable description
uuidstring❌auto UUID v4RFC 4122 formatGlobally unique identifier — auto-generated if omitted
cpuobject✅—See cpu schemavCPU configuration
memoryobject✅—See memory schemaRAM configuration
storagearray✅—≥1 diskDisk device attachments
networkarray❌[]0–16 NICsNetwork device attachments
consoleobject❌virtio-consoleSee console schemaSerial / virtio console
graphicsobject❌noneSee graphics schemaDisplay adapter and VNC
usbarray❌[]0–8 devicesUSB host device passthrough
bootobject❌SeaBIOS, disk firstSee boot schemaBoot order, firmware, direct kernel boot
pqcobject❌disabledSee pqc schemaPost-quantum cryptography settings
migrationobject❌defaultsSee migration schemaLive migration policies
securityobject❌defaultsSee security schemaSEV-SNP / TDX / secure boot

cpu Object #

FieldTypeRequiredDefaultConstraintsDescription
countinteger✅—1–256Number of virtual CPUs
modelstring❌"host""host" or named model"host" = full CPUID passthrough; named = mask to model baseline
featuresstring[]❌[]"+flag" or "-flag"CPUID feature overrides (e.g. ["+aes", "-avx512f"])
topologyobject❌1 socket, N cores, 1 threadsockets × cores × threads = countvCPU topology exposed via CPUID 0x1F
topology.socketsinteger❌11–8Number of CPU sockets
topology.coresinteger❌=count1–128Cores per socket
topology.threadsinteger❌11–2Threads per core (SMT)
pinobject❌none (float){"0":4,"1":5}vCPU → pCPU pinning map
weightinteger❌2561–65535Scheduler weight (Credit/Credit2)
capinteger❌0 (unlimited)0–100Max % of one pCPU per vCPU (0 = no cap)
numa_nodeinteger❌auto0–NPreferred NUMA node for scheduling and memory allocation

Named CPU Models

Model NameBaselineNotable Features
Skylake-ServerXeon Scalable 1st GenAVX-512, AES-NI, ADX
Cascadelake-ServerXeon Scalable 2nd Gen+ VNNI
Icelake-ServerXeon Scalable 3rd Gen+ SHA-NI, VPCLMULQDQ
SapphireRapidsXeon Scalable 4th Gen+ AMX, AVX-512 BF16
EPYCAMD EPYC 7001AVX2, AES-NI, SHA
EPYC-RomeAMD EPYC 7002+ RDPID, WBNOINVD
EPYC-MilanAMD EPYC 7003+ VAES, VPCLMULQDQ
EPYC-GenoaAMD EPYC 9004+ AVX-512

memory Object #

FieldTypeRequiredDefaultConstraintsDescription
sizestring✅—"128M"–"4T"VM RAM size (e.g. "512M", "8G")
hugepagesstring|bool❌falsefalse, "2M", "1G"Use hugepages for EPT/NPT backing
balloonboolean❌false—Enable VirtIO memory balloon for dynamic sizing
max_sizestring❌=size≥sizeMaximum memory for hot-add (e.g. "32G")
preallocboolean❌false—Pre-allocate all memory at VM creation (avoids page faults)
encryptedboolean❌falseRequires SEV or TDXHardware memory encryption (SEV AES-128 / TDX AES-128)

storage[] Array #

Each element defines a virtual block device attached to the VM.

FieldTypeRequiredDefaultConstraintsDescription
typestring❌"virtio-blk"virtio-blk, nvme, ahci, ideStorage controller type
pathstring✅—Absolute pathPath to disk image or block device
formatstring❌auto-detectraw, qcow2, encryptedDisk image format
readonlyboolean❌false—Mount disk read-only
mediastring❌"disk"disk, cdromMedia type
boot_indexinteger❌none0–99Boot priority (lower = higher priority)
cachestring❌"writeback"none, writeback, writethrough, directsyncHost cache mode
iostring❌"threads"native, threadsI/O backend (native requires cache:none or directsync)
queuesinteger❌11–64Multi-queue count (VirtIO-blk only, match vCPU count)
discardboolean❌false—Pass TRIM/UNMAP to host (VirtIO-blk only)
io_limitstring❌unlimitede.g. "500M"I/O bandwidth limit (bytes/sec)
iops_limitinteger❌unlimited1–1000000I/O operations per second limit
encryptedobject❌none—PQC disk encryption (see below)

storage[].encrypted Object

FieldTypeDefaultValuesDescription
kemstring"ML-KEM-768"ML-KEM-512, ML-KEM-768, ML-KEM-1024Key encapsulation mechanism for key wrapping
aeadstring"AES-256-GCM"AES-256-GCM, ChaCha20-Poly1305Authenticated encryption for disk sectors

network[] Array #

FieldTypeRequiredDefaultConstraintsDescription
typestring❌"virtio-net"virtio-net, e1000, e1000eNIC device model
networkstring✅—Existing network nameVirtual network to attach to
macstring❌auto 52:54:00:xx:xx:xxValid MAC addressMAC address (auto-generated if omitted)
queuesinteger❌11–16Multi-queue (VirtIO-net only, match vCPU count)
vhostboolean❌true—Enable vhost-net kernel acceleration
vhost_userobject❌none—vhost-user socket configuration for DPDK
vhost_user.socketstringcond.—Unix socket pathvhost-user socket path
vhost_user.serverboolean❌false—true = QuantaVirt creates socket; false = connects
mtuinteger❌1500576–9000Maximum transmission unit
vlaninteger❌none1–4094802.1Q VLAN tag
offloadobject❌all enabled—Offload feature toggles
offload.tsoboolean❌true—TCP segmentation offload
offload.gsoboolean❌true—Generic segmentation offload
offload.groboolean❌true—Generic receive offload
offload.csumboolean❌true—TCP/UDP checksum offload
pqc_tunnelboolean❌false—Encrypt this NIC's traffic with PQC
pqc_kemstring❌"ML-KEM-768"ML-KEM variantsKEM for tunnel key exchange
pqc_aeadstring❌"AES-256-GCM"AEAD ciphersBulk cipher for tunnel encryption

console Object #

FieldTypeDefaultValuesDescription
typestring"virtio-console"virtio-console, serialConsole device type
logstringnoneFile pathLog console output to file

graphics Object #

FieldTypeDefaultValuesDescription
typestring"none"virtio-gpu, noneGPU device type
virglbooleanfalse—Enable Virgl 3D acceleration
vncobjectnone—VNC remote display settings
vnc.listenstring"127.0.0.1"IP addressVNC bind address
vnc.portinteger59001024–65535VNC listen port
vnc.passwordstringnone≤8 charsVNC authentication password
vnc.websocketbooleanfalse—Enable WebSocket transport (for GUI)

usb[] Array #

FieldTypeRequiredDescription
vendor_idstring✅USB vendor ID (hex, e.g. "0x046d")
product_idstring✅USB product ID (hex, e.g. "0xc52b")
businteger❌Host USB bus number (for disambiguation)
portinteger❌Host USB port number

boot Object #

FieldTypeDefaultValuesDescription
orderstring[]["disk","cdrom"]disk, cdrom, networkBoot device priority
uefibooleanfalse—true = OVMF/UEFI; false = SeaBIOS/legacy
secure_bootbooleanfalseRequires uefi:trueEnable UEFI Secure Boot
kernelstringnoneFile pathDirect kernel boot — path to vmlinuz
initrdstringnoneFile pathDirect kernel boot — path to initramfs
cmdlinestringnoneKernel argsDirect kernel boot — kernel command line

pqc Object #

FieldTypeDefaultValuesDescription
enabledbooleanfalse—Enable PQC subsystem for this VM
backendstring"auto"auto, quac100, softwareauto = QUAC 100 if available, else software
attestationobjectdisabled—VM attestation settings
attestation.enabledbooleanfalse—Enable boot-time attestation
attestation.algorithmstring"ML-DSA-65"ML-DSA-44, ML-DSA-65, ML-DSA-87Digital signature algorithm for attestation
storage_encryptionobjectdisabled—PQC storage encryption defaults for this VM
storage_encryption.enabledbooleanfalse—Encrypt all disks by default
storage_encryption.kemstring"ML-KEM-768"ML-KEM variantsKey encapsulation for disk key wrapping
storage_encryption.aeadstring"AES-256-GCM"AEAD ciphersBulk cipher for sector encryption

migration Object #

FieldTypeDefaultValuesDescription
allowedbooleantrue—Allow this VM to be migrated
max_downtime_msinteger3001–10000Maximum acceptable downtime in milliseconds
bandwidthstring"1G"Size stringMaximum migration bandwidth
compressbooleanfalse—Enable page compression during transfer
auto_convergebooleanfalse—Throttle guest CPU if dirty rate exceeds transfer rate

security Object #

FieldTypeDefaultValuesDescription
sevobjectdisabled—AMD SEV configuration
sev.enabledbooleanfalse—Enable AMD SEV memory encryption
sev.policyinteger0BitmaskSEV guest policy (see AMD SEV API spec)
sev.esbooleanfalseRequires EPYC 7002+Enable SEV-ES (encrypted register state)
sev.snpbooleanfalseRequires EPYC 7003+Enable SEV-SNP (integrity + attestation) — beta
tdxobjectdisabled—Intel TDX configuration
tdx.enabledbooleanfalseRequires Xeon 4th Gen+Enable Intel TDX trust domain — beta

Validation Rules #

RuleConstraintError if Violated
CPU topology consistencysockets × cores × threads = countQV_ERR_INVAL: CPU topology does not match count
Memory minimumsize ≥ 128MQV_ERR_INVAL: memory size below minimum (128 MB)
At least one storage devicelen(storage) ≥ 1QV_ERR_INVAL: no storage devices configured
Disk path existsFile or block device at pathQV_ERR_NOENT: disk image not found
Network existsNamed network must existQV_ERR_NOENT: network 'X' not found
UEFI required for Secure Bootsecure_boot requires uefi: trueQV_ERR_INVAL: secure_boot requires UEFI firmware
SEV requires AMD EPYCHost must have AMD SEV capabilityQV_ERR_NODEV: AMD SEV not available on this host
TDX requires Intel Xeon 4th+Host must have TDX capabilityQV_ERR_NODEV: Intel TDX not available on this host
Native AIO requires direct cacheio: "native" requires cache: "none" or "directsync"QV_ERR_INVAL: native AIO incompatible with writeback cache
Name uniquenessNo other VM with same nameQV_ERR_EXIST: VM name already in use

Complete Examples #

Minimal Linux VM

{
  "name": "minimal-linux",
  "cpu": { "count": 1 },
  "memory": { "size": "512M" },
  "storage": [
    { "path": "/var/lib/quantavirt/disks/minimal.qcow2" }
  ]
}

High-Performance Database Server

{
  "name": "postgres-prod",
  "description": "Production PostgreSQL server",
  "cpu": {
    "count": 16,
    "model": "host",
    "topology": { "sockets": 1, "cores": 16, "threads": 1 },
    "pin": { "0":0,"1":1,"2":2,"3":3,"4":4,"5":5,"6":6,"7":7,
             "8":8,"9":9,"10":10,"11":11,"12":12,"13":13,"14":14,"15":15 },
    "numa_node": 0
  },
  "memory": { "size": "64G", "hugepages": "1G", "prealloc": true },
  "storage": [
    {
      "type": "virtio-blk", "path": "/dev/nvme0n1p4", "format": "raw",
      "cache": "none", "io": "native", "queues": 16
    }
  ],
  "network": [
    { "type": "virtio-net", "network": "datacenter", "queues": 16, "vhost": true }
  ],
  "boot": { "uefi": true }
}

PQC-Secured Confidential VM

{
  "name": "classified-workload",
  "cpu": { "count": 8, "model": "EPYC-Milan" },
  "memory": { "size": "32G", "hugepages": "2M", "encrypted": true },
  "storage": [
    {
      "type": "virtio-blk",
      "path": "/var/lib/quantavirt/disks/classified.qcow2",
      "format": "encrypted",
      "encrypted": { "kem": "ML-KEM-1024", "aead": "AES-256-GCM" },
      "queues": 8
    }
  ],
  "network": [
    {
      "type": "virtio-net", "network": "secure-enclave",
      "pqc_tunnel": true, "pqc_kem": "ML-KEM-1024", "pqc_aead": "AES-256-GCM"
    }
  ],
  "boot": { "uefi": true, "secure_boot": true },
  "pqc": {
    "enabled": true, "backend": "quac100",
    "attestation": { "enabled": true, "algorithm": "ML-DSA-87" },
    "storage_encryption": { "enabled": true, "kem": "ML-KEM-1024", "aead": "AES-256-GCM" }
  },
  "security": {
    "sev": { "enabled": true, "snp": true }
  }
}
← Configuration Reference PQC Algorithm Parameters →