Lab file: vm and its children

This chapter is the field-by-field reference for the vm {} block and every block it can carry. The blocks a vm shares with a container (login, nic, provision, playbook) are documented here once and referenced from container and its children. How a VM's hardware resolves is explained in the lab file guide; what the schema does not say is enforced by vmlab validate, and each entry below lists those rules.

vm {}

One virtual machine. The only required field is template; every hardware value not set here is inherited from the template's recorded hardware, then from the guest OS profile.

vm "<name>" {
  template    = "<arch>/<name>[@<version>][#<variant>]"   // or "scratch", or a registry ref
  arch        = "x86_64"
  profile     = "linux-modern"
  cpus        = 2
  memory      = 4GiB
  disk        = 64GiB          // scratch VMs only
  cdrom       = "./isos/boot.iso"
  floppy      = "./boot.img"
  depends_on  = ["dc01"]
  nested      = false
  gui         = false
  agent_update = true
  prevent_sleep = false
  clock       = "host"         // or "snapshot", or "2020-01-01T00:00:00Z"
  display     = "virtio-vga"
  cpu_model   = "pentium3"
  accel       = "tcg"
  firmware    = "ovmf"
  tpm         = false
  secure_boot = false
  qemu_args   = []
  gpu       { … }
  nic       { … }
  disk "…"  { … }
  share     { … }
  media     { … }
  login "…" { … }
  provision "…" { … }
  playbook "…" { … }
}

Template references

The template value takes one of three forms, and the form decides what else the block must say.

• Store reference <arch>/<name>[@<version>][#<variant>], such as x86_64/windows-11@26100.1 or x86_64/windows-11#win3d. The arch is always written; a bare windows-11 is rejected. Without a version the highest version in the store is used. The template must be in the store, and an arch field, if present, must match.
• Registry reference, such as ghcr.io/owner/ubuntu-24.04:1.0, with an optional #<variant> after the tag or digest. Recognised by a first path segment holding a dot, a colon or localhost. It requires an explicit arch. vmlab up pulls it if it is absent from the store and never re-pulls it implicitly. See Distributing templates over registries.
• scratch: no backing image. The VM gets a blank disk and no template layer. It requires arch, profile and disk, and boot media is yours to attach.

Known architectures are x86_64, x86, aarch64, riscv64, loongarch64, s390x and ppc64.

The #<variant> suffix selects one disk of a template version that has variants. Without it the template's default variant is used, or its only disk when it has none. A variant name is 1 to 32 lowercase letters, digits and hyphens, starting with a letter or digit. #base names the unsealed base disk and is refused on a template that has variants. The rules are in Templates.

Validation

• The name is a DNS label and no other VM or container in the lab has it.
• cpus is at least 1. memory and disk are non-negative sizes.
• disk on a store or registry template is an error; clones inherit the template's disk. Use disk "name" {} blocks for extra disks.
• A #<variant> names a variant the store template has, and is not #base on a template with variants. The error lists the template's variants, the default marked.
• Every name in depends_on exists in the lab, and the dependency graph across VMs and containers has no cycle.
• profile, if set, names a known profile.
• cdrom and floppy name files that exist under the lab root.
• clock is host, snapshot, or an RFC 3339 date-time such as 2020-01-01T00:00:00Z.
• secure_boot = true is rejected when the firmware resolves to seabios. Either value may have been inherited, so the message names the layer each came from.
• secure_boot_keys (other than microsoft) or secure_boot_vars is rejected where secure boot resolves off, naming the layer each side came from. A key store inherited from below the layer that turned secure boot off is not an error. The two are rejected together on one block, and secure_boot_vars must name an existing file.
• A VM with share {} blocks that are not transport = "virtiofs" needs at least one nic {}, because SMB is reachable only over a segment.
• A playbook {} on a VM whose arch is known to be something other than x86_64 is rejected unless it names a guest_bin; config-weave ships guest binaries for x86_64 only.

vm "winsrv" {
  template = "x86_64/windows-server-2025"
  cpus = 4
  memory = 8GiB
  nic {
    segment = "lan"
    ip = "10.70.0.10"
  }  # DHCP reservation
  share {
    host = "./shared"
    guest = "S:"
  }  # auto-mounted when ready

  # Runs once winsrv is ready; nix01 depends on it, so it waits.
  provision "scripts/setup.ws" { }
}

The @dev decorator

@dev is written on the line before a vm or container block and marks it as a dev machine: when a workspace is named, vmlab syncs that directory onto it and keeps the two copies in step. It is a decorator rather than a child block because it states something about the machine; nothing it carries is a setting the guest sees. A bare @dev is complete. Any number of machines may carry it, and zero is normal.

@dev(default = true, workspace = "./workspace", workspace_guest = "C:\\src")
vm "dev01" { … }

Unset arguments resolve in the order @dev argument, then the machine's effective profile, then the vmlab floor of /src. A profile that sets no workspace_guest still hosts a dev machine. The schema rejects an unknown argument, a wrong type, a repeated @dev, or @dev on a block that is not a vm or container. Validation adds one rule: two machines with default = true is an error naming both. With more than one @dev machine and none declaring default = true, the lab has no default; the selection ladder in vmlab dev then needs an argument. The dev-container example carries it on a container:

@dev(default = true, workspace = "./workspace")
container "dev01" {
  image   = "alpine:3.22"
  profile = "container"
  // A dev machine builds things, and a container names its own size when
  // the profile's floor is not the right one.
  cpus    = 2
  memory  = 1GiB
  // `:idle` keeps the micro-VM up without running the image's entrypoint
  // — a dev container has no service to be.
  mode    = :idle
  nic { segment = "lan" }

  // The container identity floor (§19.2): the agent is root and root needs
  // no credential to become an account, so a Linux `login {}` may declare
  // the account alone. `elevated` is a validation error on this side.
  login "dev" { user = "dev" default = true }

  provision "scripts/dev-user.ws" { }
  provision "scripts/home-bits.ws" { }
}

login {}

A labelled identity on a machine: the guest account exec, shell and a script's as_login run as. See Logins. Repeatable, so one account may be declared twice at different elevation, and --user selects between labels.

login "<label>" {
  user     = "PROBE\\dev"
  password = "…"
  elevated = true
  default  = false
}

The family the rules are judged against is the machine's resolved profile: a name starting with windows is Windows, one starting with linux is Linux, and anything else, including custom and a registry template not yet pulled, is unknown and gets neither family rule. A container is always Linux. Validation enforces:

• On a Windows family, every login has a password; the agent runs as LocalSystem and there is no credential-free logon.
• On a Linux family, no login declares elevated; root is root, and the field would be read nowhere.
• No two logins on one machine share a label.
• At most one login on a machine sets default = true; the message names both.

nic {}

One network interface, attached to a declared segment or to the lab's built-in NAT segment. A machine with no nic {} blocks has no network hardware at all. See Networking.

nic {
  segment  = "corp"      // or: nat = true
  ip       = "10.50.0.10"
  gateway  = false
  mac      = "52:54:00:ab:cd:ef"
  isolated = false
}

Validation enforces these rules:

• Exactly one of segment or nat = true is set. Both is an error; neither is an error.
• segment names a segment declared in the lab.
• ip parses as an IPv4 address, lies inside the segment's declared subnet, is not the network, broadcast or gateway address, and is unique across the lab. A static IP needs a segment with a declared subnet, and is not supported on the built-in NAT segment.
• mac parses as a MAC address and is unique across the lab.
• gateway = true needs a declared segment, a static ip equal to the segment's first usable address, a segment without nat = true, a segment that is not global, and no other gateway NIC on that segment.

disk {}

An additional disk beyond the primary one: blank at a given size, or a fresh FAT filesystem with a folder copied onto it, or both.

disk "data" { size = 10GiB }
disk "payload" { from = "./payload/" }

At least one of size and from must be set; both together is allowed. A from folder must exist under the lab root.

share {}

A host directory mounted into the guest, over virtiofs when host and guest support it, otherwise over SMB served at the segment gateway. See Shared folders.

share {
  host      = "./shared"
  guest     = "/mnt/src"
  readonly  = false
  smb1      = false
  name      = "src"
  transport = "auto"
}

The derived name joins the alphanumeric runs of the guest path with underscores, so /mnt/src becomes mnt_src and D:\data becomes d_data. Validation requires host to be a directory, a derivable or explicit name, and rejects smb1 = true with transport = "virtiofs". A VM whose shares are not all virtiofs needs a NIC.

media {}

An ISO or floppy image built from a folder and attached to the machine. Built images are content-addressed under the lab's .vmlab/ directory, so an unchanged folder is not rebuilt.

media { kind = "iso" from = "./unattend/" label = "UNATTEND" }

Validation requires from to be a directory under the lab root.

gpu {}

GPU acceleration for the VM. At most one per VM. Passthrough hands a host device to the VM exclusively; virgl and vulkan render on the host GPU, which stays shared. The GPU itself is a host GPU, declared by name in the host configuration file: a PCI address is a fact about one machine, and the lab file travels between machines.

gpu { mode = "vulkan" }                    // the host's default GPU
gpu { mode = "vulkan" host_gpu = "AMD1" }  // a named one

The lab daemon picks the host GPU when the VM starts. A host_gpu this host declares is used. A host_gpu it does not declare makes virgl and vulkan warn and take the host's default; passthrough refuses, naming the host's GPUs, because passing through a different card takes it away from the host. No host_gpu takes the default. When nothing resolves — no GPU declared, or the name missing and no default — virgl and vulkan render where QEMU puts them, and passthrough refuses. vmlab status -v shows the picked GPU as host_gpu=<name>.

A paravirtual GPU is the guest's only display adapter: virtio-vga-gl on x86 machines, virtio-gpu-gl with -vga none on virt. vulkan adds venus=true,blob=true,hostmem=4G.

vmlab reads the picked GPU's render node and kernel driver from /sys/bus/pci/devices/<address>/. The render node goes on the egl-headless display. Under vulkan the driver sets VK_LOADER_DRIVERS_SELECT in QEMU's environment: *radeon* for amdgpu, *intel* for i915 and xe, *nvidia* for nvidia; a host GPU's vulkan_icd replaces that with VK_DRIVER_FILES. vmlab also loads its own implicit layer, VK_LAYER_VMLAB_pci_filter, through VK_ADD_IMPLICIT_LAYER_PATH, with VMLAB_VK_PCI_ADDRESS set to the GPU's address. The layer hides every other physical device, so the guest sees one Venus device even when two identical cards both match the driver filter. The other Vulkan loader variables are cleared, and MESA_VK_DEVICE_SELECT is never set, because it breaks Venus. vmlab up warns when a virgl or vulkan VM gets no host GPU and the host has more than one render node. Each run's qemu.log starts with the QEMU command line and the variables vmlab set. Under passthrough the address becomes -device vfio-pci,host=<address>.

Validation runs the same pick: it rejects an empty host_gpu; a passthrough name this host lacks, or passthrough with nothing to pick; a picked GPU whose address names no PCI device, or no render node under virgl or vulkan; and a vulkan_icd that does not exist. A virgl or vulkan name this host lacks is a warning. The v0.24 fields address and vulkan_icd moved to the host config, and a lab still carrying either fails with the message in Troubleshooting.

provision {}

A wscript provision script run on vmlab up once this machine is ready. It runs once, at its position among the machine's provision and playbook blocks. See Guest automation with wscript.

provision "scripts/setup.ws" { }

Validation checks the file exists and compiles it, reporting compile errors against the block. Across machines, steps follow the order the machine blocks appear, with depends_on gating when each becomes eligible.

playbook {}

A config-weave playbook applied on vmlab up, interleaved with the machine's provisions in declaration order, and runnable on demand with vmlab playbook check and apply. See Playbooks.

playbook "playbooks/baseline" {
  play = "baseline"
  var "tz" { value = "UTC" }
}

Validation requires a non-empty play, a path that is a directory holding a playbook.wcl, a timeout greater than zero, and no variable set twice on one block. guest_dir and guest_bin must be absolute for the machine's guest family: a drive-letter path on Windows, a path starting with / on Linux (every container), and either where the family is unknown. On Windows guest_bin must also end in .exe. config-weave ships guest binaries for x86_64 only, so a playbook on a VM with another known arch is rejected unless it names a guest_bin.

var {}

One variable override for the enclosing playbook {}, passed to config-weave as --var name=value for this machine's run only.

var "tz" { value = "UTC" }

Validation requires the name to be letters, digits and underscores, not starting with a digit, because config-weave binds each override as a let inside the guest.

on {}

An event handler, declared inside lab {}. The handler script runs when the named event fires; a failing handler is logged and never fatal. See Events and handlers and the event list.

on "vm.crashed" { run = "scripts/collect-dumps.ws" targets = ["dc01"] }

Validation requires a known event name and a script that exists and compiles. targets may only be set on vm.*, container.* and snapshot.* events; a lab-wide event with targets is an error. A vm.* event may target only VMs and a container.* event only containers, and every target must exist.

on "vm.crashed"    { run = "scripts/collect-dumps.ws" }
on "host.disk_low" { run = "scripts/alert.ws" }