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/FelipeVasquez350/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"

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.

spec

Field	Type	Required	Description
diskImage	string	yes	Path to the disk image file. Can be absolute or relative to the VMFile location.
diskFormat	string	yes	Format of the disk image: qcow2, raw, or iso
resources	object	yes	Resource allocation for the VM

spec.resources

Field	Type	Required	Description
cpu	integer	yes	Number of virtual CPUs to allocate. Must be between 1 and 64.
memory	string	yes	Amount of RAM to allocate. Format: <number><unit> where unit is MiB, GiB, or TiB. Minimum: 128MiB, Maximum: 1TiB.
bootloader	object	yes	Bootloader configuration

spec.resources.bootloader

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

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
• spec.diskImage is present and the resolved path points to an existing file
• spec.diskFormat is one of the supported formats (qcow2, raw, iso)
• spec.resources.cpu is a positive integer between 1 and 64
• spec.resources.memory matches the <number><unit> pattern with a valid unit
• spec.resources.bootloader.type is UEFI or BIOS

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