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>]"   // 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
  display     = "virtio-vga"
  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>], such as x86_64/[email protected]. 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. 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.

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.
• 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.
• 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.
• 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; 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.

gpu { mode = "passthrough" address = "0000:01:00.0" }

Validation rejects passthrough without an address.

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, and no variable set twice on one block. config-weave ships guest binaries for x86_64 only, so a playbook on a VM with another known arch is rejected.

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" }