VM Configuration Format
Each VM stores its configuration as config.json in its folder under the data directory. This document describes the schema. The same model underlies the GUI settings dialogs and the CLI. For the user view, see Creating Virtual Machines.
Top-Level VmConfig #
| Field | Type | Description |
|---|---|---|
id | string | Unique VM identifier (UUID). |
name | string | Display name. |
os_type | OsType | Guest operating system. |
cpu | CpuConfig | CPU topology and options. |
memory | MemoryConfig | RAM size and ballooning. |
disks | DiskAttachment[] | Attached virtual disks. |
network | NetworkAttachment[] | Network adapters. |
display | DisplayConfig | Display backend and graphics. |
boot_order | BootDevice[] | Boot device priority. |
usb | UsbConfig | USB controller and passthrough. |
shared_folders | SharedFolderConfig[] | Host-guest shared folders. |
encryption | EncryptionConfig? | Optional disk encryption settings. |
unattended | UnattendedConfig? | Optional unattended-install settings. |
cdrom | string? | Path to an ISO mounted as CD-ROM. |
ssh_host_port | u16? | Host port forwarded to guest SSH (port 22) in NAT mode. |
description | string | Free-text description. |
tags | string[] | Organizational tags. |
Enums #
OsType
Windows11, Windows10, WindowsServer2022, Ubuntu2404, Ubuntu2204, Fedora40, Debian12, Arch, FreeBSD14, MacOS, KaliLinux, Rocky9, AlmaLinux9, Other(string).
DiskFormat
Qcow2, Raw, Vmdk, Vdi, Qvd (encrypted QCOW2).
DiskBus
VirtIO, Sata, Ide, NVMe.
NetworkMode
Nat, Bridged, HostOnly, Internal.
NetworkAdapter
VirtIO, E1000 (Intel PRO/1000), Rtl8139.
DisplayBackend
Spice, Vnc, Sdl.
BootDevice
Disk, Cdrom, Network, Usb.
UsbVersion
Usb2 (EHCI), Usb3 (xHCI).
Nested Structures #
CpuConfig
| Field | Type | Default | Description |
|---|---|---|---|
cores | u32 | 2 | vCPU cores. |
threads_per_core | u32 | 1 | Threads per core (SMT). |
nested_virt | bool | false | Enable nested virtualization. |
MemoryConfig
| Field | Type | Default | Description |
|---|---|---|---|
size_mb | u64 | 4096 | RAM in megabytes. |
balloon | bool | true | Enable memory ballooning. |
DiskAttachment
| Field | Type | Description |
|---|---|---|
path | string | Path to the disk image. |
format | DiskFormat | Image format. |
size_bytes | u64 | Virtual size. |
encrypted | bool | LUKS encryption (QCOW2/QVD). |
read_only | bool | Mount read-only. |
bus | DiskBus | Controller bus. |
NetworkAttachment
| Field | Type | Description |
|---|---|---|
mode | NetworkMode | Connectivity mode. |
mac_address | string? | MAC (auto-generated if absent). |
adapter | NetworkAdapter | NIC model. |
DisplayConfig
| Field | Type | Default | Description |
|---|---|---|---|
backend | DisplayBackend | Spice | Display protocol. |
gpu_accel | bool | false | GPU acceleration. |
resolution | (u32, u32) | (1920, 1080) | Display resolution. |
fullscreen | bool | false | Fullscreen flag. |
UsbConfig
| Field | Type | Default | Description |
|---|---|---|---|
enabled | bool | true | Enable USB controllers. |
version | UsbVersion | Usb3 | USB controller version. |
passthrough | UsbPassthrough[] | empty | Passed-through devices. |
UsbPassthrough: vendor_id (u16), product_id (u16), label (string).
SharedFolderConfig
| Field | Type | Description |
|---|---|---|
name | string | Mount name / tag. |
host_path | string | Host directory. |
read_only | bool | Read-only access. |
auto_mount | bool | Auto-mount at boot. |
EncryptionConfig
| Field | Type | Description |
|---|---|---|
enabled | bool | Encryption on/off. |
key_id | string | Wrapping-key identifier. |
algorithm | string | Algorithm name (e.g. ML-KEM-768+AES-256-GCM). |
UnattendedConfig
| Field | Type | Description |
|---|---|---|
enabled | bool | Enable unattended install. |
username | string | First user account. |
password | string | User password. |
hostname | string | Guest hostname. |
locale | string | Locale (e.g. en-US). |
timezone | string | IANA timezone (e.g. America/New_York). |
Defaults at a Glance #
A newly created VM defaults to: 2 cores x 1 thread, 4096 MB RAM (balloon on), a SPICE display at 1920x1080 with no GPU acceleration, USB enabled at USB 3.0 (xHCI), a boot order of [Disk, Cdrom], and a single NAT adapter using the VirtIO NIC.