VMFile Reference

A VMFile is a YAML manifest that describes a virtual machine image. It defines the image metadata (name, author, description) and the VM specification (disk image path, format, resource allocation, and bootloader type). VMFiles are used with vmr import to register local disk images into the VM Registry.

Minimal Example

apiVersion: vmregistry.io/v1alpha1

metadata:
  name: "myuser/my-vm"

spec:
  diskImage: "disk.qcow2"
  diskFormat: "qcow2"
  resources:
    cpu: 2
    memory: "4GiB"
    bootloader:
      type: "BIOS"

Full Example

apiVersion: vmregistry.io/v1alpha1

metadata:
  name: "nixos-server/nixos-k3s-vm"
  description: "A base server image for a kubernetes cluster on nixos."
  author: "Felipe350"
  source: "https://github.com/VM-Registry/vm-registry-examples"
  labels:
    os: "nixos"
    role: "k3s-node"
    arch: "x86_64"

spec:
  diskImage: "oci-nixos-vm-image.qcow2"
  diskFormat: "qcow2"
  resources:
    cpu: 2
    memory: "4GiB"
    bootloader:
      type: "BIOS"

Remote Disk Image Example

Instead of a local diskImage path, spec.diskImageSource can be used to have the daemon download the disk image directly from an http(s) URL at import time. This is useful for importing upstream cloud images without first downloading them to the machine running vmr.

apiVersion: v1

metadata:
  name: "myuser/ubuntu-minimal"

spec:
  diskImageSource:
    url: "https://cloud-images.ubuntu.com/minimal/releases/noble/release/ubuntu-24.04-minimal-cloudimg-amd64.img"
    sha256: "3f2b1c9e8a7d6f5e4c3b2a1908f7e6d5c4b3a2918f7e6d5c4b3a2918f7e6d5c"
  diskFormat: "qcow2"
  resources:
    cpu: 2
    memory: "2GiB"
    bootloader:
      type: "BIOS"

diskImage and diskImageSource are mutually exclusive — exactly one of them must be set. See spec.diskImageSource below.

Schema

Top-Level Fields

Field	Type	Required	Description
apiVersion	string	yes	API version of the VMFile format. Valid values: vmregistry.io/v1alpha1, v1
metadata	object	yes	Metadata about the VM image
spec	object	yes	Specification of the VM image

metadata

Field	Type	Required	Description
name	string	yes	Name of the VM image. May use namespace/name format. Only lowercase letters, numbers, hyphens, underscores, and dots are allowed. Maximum 255 characters.
description	string	no	Human-readable description of the VM image
author	string	no	Author or maintainer of the VM image
source	string	no	Source URL or reference for the VM image
labels	map	no	Key-value labels for the VM image. Keys: max 63 chars, alphanumeric plus -, _, .. Values: max 255 chars. See well-known labels.

metadata.labels.graphics

Labels are free-form, but graphics is a well-known label: it declares the graphics family the image supports — typically the vendor whose drivers are installed in the guest, e.g. nvidia, amd, or intel. The value is free-form and may list more than one family, comma-separated (nvidia, amd).

This label is purely declarative. GPUs are a host-specific runtime choice (PCI addresses differ per host), so they are never baked into the image. The label lets tooling and operators know which GPU an image expects; the device itself is attached at run time with vmr run --gpu (or vmr edit --gpu, or the compose gpus field).

When you attach a GPU with --gpu, the daemon compares the chosen GPU's vendor against this label and prints a warning (it does not fail) if they don't match — for example, attaching an AMD card to an image labelled graphics: nvidia.

metadata:
  name: ml/trainer
  labels:
    graphics: nvidia

spec

Field	Type	Required	Description
diskImage	string	yes*	Path to the disk image file. Can be absolute or relative to the VMFile location. ~/ is expanded to the home directory.
diskImageSource	object	yes*	Remote source to download the disk image from at import time. See spec.diskImageSource.
diskFormat	string	yes	Format of the disk image: qcow2, raw, or iso
installer	boolean	no	Treat the disk image as installer media (e.g. an ISO to boot and install from). Default: false.
resources	object	yes	Resource allocation for the VM
cloudInit	object	no	Cloud-init configuration baked into the image

* Exactly one of diskImage or diskImageSource must be set.

spec.diskImageSource

An alternative to diskImage for importing a disk image directly from a remote URL. When set, the client does not read, download, or upload any disk image data — the daemon fetches the image itself from url at import time (vmr import).

Field	Type	Required	Description
url	string	yes	HTTP(S) URL to download the disk image from.
sha256	string	yes	Expected SHA-256 checksum of the downloaded image, as 64 lowercase hex characters.

sha256 is required, not optional: the daemon verifies the downloaded bytes against it and rejects the import if they don't match. This protects against corrupted downloads as well as tampered or replaced files served in place of the expected image (e.g. a man-in-the-middle). The same size bounds that apply to local disk images (1 MiB–100 GiB) apply to the downloaded image.

spec.resources

Field	Type	Required	Description
cpu	integer	yes	Number of virtual CPUs to allocate.
memory	string	yes	Amount of RAM to allocate. Format: <number><unit> where unit is MiB, GiB, or TiB.
disk	string	no	Disk size for the VM (e.g. 60GiB). If omitted, the disk image's own size is used.
diskBus	string	no	Disk bus type (e.g. virtio, sata, scsi). Defaults to the daemon's standard bus.
architecture	string	no	Target CPU architecture (e.g. x86_64, aarch64). Defaults to the host architecture.
bootloader	object	yes	Bootloader configuration

GPUs are not declared here

A GPU is a host-specific runtime choice — PCI addresses differ from machine to machine — so GPUs are never baked into an image's spec. Instead, an image declares the graphics family it supports with the graphics metadata label, and the actual device is attached at run time with vmr run --gpu, vmr edit --gpu, or the compose service gpus field. See the GPUs guide for the full workflow.

spec.resources.bootloader

Field	Type	Required	Description
type	string	yes	Bootloader firmware type: UEFI or BIOS

spec.cloudInit

Cloud-init data baked into the image at import time. All fields are optional.

Field	Type	Required	Description
userData	string	no	Inline cloud-init user-data (YAML cloud-config or script)
metaData	string	no	Inline cloud-init meta-data
networkConfig	string	no	Inline cloud-init network configuration

Disk Formats

Format	Description
qcow2	QEMU Copy-On-Write v2. Recommended for most use cases — supports snapshots, compression, and thin provisioning.
raw	Raw disk image. Maximum I/O performance but no copy-on-write or compression support.
iso	ISO 9660 optical disk image. Typically used for installer media or read-only boot images.

Bootloader Types

Type	Description
UEFI	Modern UEFI firmware. Recommended for guests that support it — required for Secure Boot and GPT disks larger than 2 TiB.
BIOS	Legacy BIOS firmware. Use for older guest operating systems or MBR-partitioned disks.

Memory Format

Memory values must be specified as an integer followed by a unit suffix with no spaces:

Unit	Description	Example
MiB	Mebibytes (1,048,576 bytes)	512MiB
GiB	Gibibytes (1,073,741,824 bytes)	4GiB
TiB	Tebibytes (1,099,511,627,776 bytes)	1TiB

WARNING

Values without a unit suffix or with unsupported units (e.g., MB, GB) are rejected during validation.

Path Resolution

The diskImage field supports both absolute and relative paths:

• Absolute paths are used as-is (e.g., /home/user/images/disk.qcow2)
• Relative paths are resolved from the directory containing the VMFile

When using vmr import ./path/to/VMFile, the CLI resolves relative disk image paths from the VMFile's parent directory. You can override this with the --context flag to specify a different base directory.

Validation

The daemon validates VMFiles at import time. The following checks are performed:

• apiVersion is present and matches a known version
• metadata.name is present and non-empty
• Exactly one of spec.diskImage or spec.diskImageSource is set
• spec.diskImage is present and the resolved path points to an existing file
• spec.diskImageSource.url uses the http or https scheme
• spec.diskImageSource.sha256 is 64 lowercase hex characters, and the downloaded image's checksum must match it
• The disk image (local or downloaded via diskImageSource) is between 1 MiB and 100 GiB
• spec.diskFormat is one of the supported formats (qcow2, raw, iso)
• spec.resources.cpu is a positive integer
• spec.resources.memory matches the <number><unit> pattern with a valid unit (MiB, GiB, or TiB)
• spec.resources.bootloader.type is UEFI or BIOS

For real-time validation in your editor as you write VMFiles, see the LSP component.