The vmlab.wcl schema

A complete reference of the vmlab.wcl (and host config.wcl) schema, reflected straight from src/config/schema.wcl / host_schema.wcl with WCL's reflection builtins (child_types / type_fields) and the wdoc type_table component — so it can never drift from the code. Each block lists its attributes (type, whether required, description), any nested blocks, and a worked example. Descriptions are the fields' @doc annotations.

§ 1`lab` block

Property	Type	Required	Description
name	utf8	yes	Lab name (DNS label, ≤63 chars); the inline block label
gui	bool	no	Default for all VMs: open a VNC viewer on up (§11); VM gui overrides

Child blocks

Slot	Accepts	Multiple	Description
segments	segment	yes	Virtual L2 network segments in this lab
vms	vm	yes	The VMs in this lab
provisions	provision	yes	wscript provision scripts run on vmlab up, in declaration order
handlers	on	yes	Lifecycle event handlers (failures are logged, never fatal)
records	record	yes	Lab-wide static DNS entries (wildcards allowed) (§9.5)
sinkholes	sinkhole	yes	Lab-wide DNS sinkholes (§9.9)

Example:

wcl

lab "demo" {
  gui = true                       // lab-wide default: show each guest's screen
  vm "box" {
    template = "x86_64/linux-modern"
    memory   = 2GiB
    nic { nat = true }
  }
}

§ 1.1`segment` (in `lab`)

Property	Type	Required	Description
name	utf8	yes	Segment name (DNS label); unique per lab; the inline block label
subnet	utf8	no	CIDR; auto-allocated as a /24 from the host pool if omitted (§9.4)
global	bool	no	Owned by the supervisor and shared across labs (§9.2)
dhcp	bool	no	Enable DHCP (default true) (§9.4)
nat	bool	no	Enable NAT/internet egress for this segment (default false) (§9.7)
mtu	i64	no	Link MTU (576–65535); default jumbo (9000) on nat/global, else 1500
routes_to	list<utf8>	no	Names of other segments to route to — daemon inter-segment routing opt-in (§9.6)

Child blocks

Slot	Accepts	Multiple	Description
dns	dns	no	DNS service override: hand out another server, or opt out (§9.5)
connect	connect	no	Cross-host segment peer over TCP (PSK from host config) (§9.2)
routes	route	yes	Guest routes pushed via DHCP option 121 (§9.6)
records	record	yes	Static DNS entries for this segment (wildcards allowed) (§9.5)
forwards	forward	yes	Host→guest port forwards (§9.8)
block_rules	block	yes	L3 block rules at the switch (§9.9)
redirect_rules	redirect	yes	L3 DNAT redirect rules (§9.9)
sinkholes	sinkhole	yes	DNS sinkhole rules (§9.9)

Example:

wcl

segment "corp" {
  subnet = "10.50.0.0/24"          // omit to auto-allocate a /24 from the host pool
  nat    = true                    // internet egress for this segment
  record { name = "dc01" ip = "10.50.0.10" }
}

`dns` (in `segment`)

Property	Type	Required	Description
server	utf8	no	IPv4 of the DNS server to hand out via DHCP instead of the daemon
enabled	bool	no	Hand out a DNS server at all (default true); false suppresses the DHCP option

Example:

wcl

dns { server = "10.50.0.10" }      // hand out a DC as the resolver via DHCP
dns { enabled = false }            // …or suppress DNS on the segment entirely

`connect` (in `segment`)

Property	Type	Required	Description
host	utf8	yes	Remote supervisor host[:port] to bridge this segment with (required)

Example:

wcl

connect { host = "helios:9999" }   // bridge this segment to a peer supervisor (PSK)

`route` (in `segment`)

Property	Type	Required	Description
dest	utf8	yes	Destination CIDR, e.g. 10.60.0.0/24 (required)
via	utf8	yes	Gateway IPv4 the route points at (required)

Example:

wcl

route { dest = "10.60.0.0/24" via = "10.50.0.254" }   // pushed via DHCP option 121

`record` (in `segment`)

Property	Type	Required	Description
name	utf8	yes	DNS name to resolve; wildcards allowed, e.g. *.internal (required)
ip	utf8	yes	IPv4 address the name resolves to (required)

Example:

wcl

record { name = "srv" ip = "10.50.0.5" }     // wildcards OK: name = "*.internal"

`forward` (in `segment`)

Property	Type	Required	Description
host_port	i64	yes	Host port to listen on (1–65535); unique across the lab (required)
to	utf8	yes	Target as vm:port; the VM must be declared (required)
proto	utf8	no	Protocol: tcp (default) \| udp \| both

Example:

wcl

forward { host_port = 13389 to = "dc01:3389" proto = "tcp" }

`block` (in `segment`)

Property	Type	Required	Description
cidr	utf8	yes	IPv4 CIDR to drop traffic to/from (required)
proto	utf8	no	Protocol to scope the rule: tcp \| udp \| icmp
port	i64	no	Port to scope the rule (1–65535); requires proto

Example:

wcl

block { cidr = "192.0.2.0/24" proto = "tcp" port = 443 }

`redirect` (in `segment`)

Property	Type	Required	Description
from	utf8	yes	Match destination as ip[:port] (required)
to	utf8	yes	Rewrite destination to ip[:port] (required)
proto	utf8	no	Protocol to scope the rule: tcp \| udp

Example:

wcl

redirect { from = "10.50.0.254:53" to = "10.50.0.10:53" proto = "udp" }

`sinkhole` (in `segment`)

Property	Type	Required	Description
pattern	utf8	yes	DNS name pattern to sink; wildcards allowed (required)
mode	utf8	no	Response: nxdomain (default) \| zero (resolve to 0.0.0.0)

Example:

wcl

sinkhole { pattern = "*.telemetry.com" mode = "nxdomain" }   // or mode = "zero"

§ 1.2`vm` (in `lab`)

Property	Type	Required	Description
name	utf8	yes	VM name (DNS label); unique per lab; the inline block label
template	utf8	yes	<arch>/<name>[@<version>], scratch, or an OCI registry ref (required)
arch	utf8	no	Architecture; required for scratch and registry references
profile	utf8	no	Guest OS profile (hardware defaults); required for scratch
cpus	i64	no	vCPU count (> 0); inherited from template→profile if omitted
memory	std.ByteSize	no	RAM as a byte size, e.g. 8GiB/512MiB; inherited if omitted
disk	std.ByteSize	no	Primary disk size, e.g. 64GiB — scratch VMs only (rejected on cloned VMs)
cdrom	utf8	no	Path to an ISO to attach as a CD-ROM (relative to lab root)
floppy	utf8	no	Path to a floppy image to attach (relative to lab root)
depends_on	list<utf8>	no	VM names to wait for before this one (no cycles)
nested	bool	no	Enable nested virtualisation (host CPU passthrough)
gui	bool	no	Open a VNC viewer on up (§11); the VM always runs headless
display	utf8	no	QEMU display string; inherited from template→profile if omitted
firmware	utf8	no	Firmware: ovmf \| seabios; inherited from template→profile
tpm	bool	no	Enable a TPM 2.0 device; inherited from template→profile
secure_boot	bool	no	Enable secure boot (OVMF only); inherited from template→profile
qemu_args	list<utf8>	no	Raw QEMU flags appended last — escape hatch (§5.2)

Child blocks

Slot	Accepts	Multiple	Description
gpu	gpu	no	GPU acceleration (passthrough / virgl / vulkan)
nics	nic	yes	Network interfaces; no NICs = air-gapped (shares need ≥1 NIC)
extra_disks	disk	yes	Additional disks beyond the primary disk
shares	share	yes	SMB shared folders (require ≥1 NIC) (§7.5)
media	media	yes	ISO/floppy images built from a folder (§6.3)

Example:

wcl

vm "dc01" {
  template = "x86_64/windows-2025"
  cpus     = 4
  memory   = 8GiB
  nic   { segment = "corp" ip = "10.50.0.10" }
  share { host = "./src" guest = "D:\\src" }
}

`gpu` (in `vm`)

Property	Type	Required	Description
mode	utf8	yes	Mode: passthrough \| virgl \| vulkan (required)
address	utf8	no	Host PCI address, e.g. 0000:01:00.0 — required for passthrough

Example:

wcl

gpu { mode = "passthrough" address = "0000:01:00.0" }   // or mode = "virgl" | "vulkan"

`nic` (in `vm`)

Property	Type	Required	Description
segment	utf8	no	Segment name to attach to; required unless nat = true
nat	bool	no	Shorthand: attach to the per-lab built-in NAT segment (§9.7)
ip	utf8	no	Static IPv4 (becomes a DHCP reservation); must be in the subnet, unique
mac	utf8	no	Fixed MAC, e.g. 52:54:00:ab:cd:ef; generated and persisted otherwise
isolated	bool	no	Port isolation: reach gateway/forwards but not segment neighbours (§9.1)

Example:

wcl

nic { segment = "corp" ip = "10.50.0.10" mac = "52:54:00:aa:bb:cc" }
nic { nat = true }                       // per-lab built-in NAT segment shorthand
nic { segment = "dmz" isolated = true }  // port isolation

`disk` (in `vm`)

Property	Type	Required	Description
name	utf8	yes	Disk identifier; the inline block label
size	std.ByteSize	no	Blank disk size, e.g. 10GiB; one of size/from is required
from	utf8	no	Folder copied onto a fresh FAT filesystem; one of size/from is required

Example:

wcl

disk "data"      { size = 10GiB }         // extra blank disk
disk "formatted" { from = "./payload/" }  // folder copied onto a fresh FAT filesystem

Property	Type	Required	Description
host	utf8	yes	Host directory to share; must exist (required)
guest	utf8	yes	Guest mount path, e.g. /mnt/src or D:\data (required)
readonly	bool	no	Mount read-only (default false)
smb1	bool	no	Enable the SMB1 dialect + auth relaxation for XP/2003-era guests
name	utf8	no	SMB share name; derived from the guest path if omitted

Example:

wcl

share { host = "./src"  guest = "/mnt/src" }
share { host = "~/data" guest = "D:\\data" readonly = true }
share { host = "./old"  guest = "X:" smb1 = true }   // legacy dialect for XP/2003

`media` (in `vm`)

Property	Type	Required	Description
kind	utf8	yes	Image kind: iso \| floppy (required)
from	utf8	yes	Source folder built into the image; must exist (required)
label	utf8	no	Volume label for the image

Example:

wcl

media { kind = "iso"    from = "./unattend/" label = "CIDATA" }
media { kind = "floppy" from = "./drivers/"  label = "DRV" }

§ 1.3`provision` (in `lab`)

Provision script run during vmlab up (§10.4). Optional vms list scopes the script for depends_on satisfaction (§7.2).

Property	Type	Required	Description
script	utf8	yes	Path to the .ws file; must exist and compile; the inline label
vms	list<utf8>	no	VM names this script is scoped to (gates their depends_on) (§7.2)

Example:

wcl

provision "scripts/setup.ws" { }                     // runs on `vmlab up`, in order
provision "scripts/join.ws"  { vms = ["client01"] }  // scoped: gates depends_on

§ 1.4`on` (in `lab`)

Event handler binding (§8.2).

Property	Type	Required	Description
event	utf8	yes	Event name to handle, e.g. vm.crashed; the inline block label
run	utf8	yes	Path to the handler .ws file; must exist and compile (required)

Example:

wcl

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

§ 1.5`record` (in `lab`)

Static DNS entry (wildcards allowed in name) (§9.5).

Property	Type	Required	Description
name	utf8	yes	DNS name to resolve; wildcards allowed, e.g. *.internal (required)
ip	utf8	yes	IPv4 address the name resolves to (required)

Example:

wcl

record { name = "srv" ip = "10.50.0.5" }     // wildcards OK: name = "*.internal"

§ 1.6`sinkhole` (in `lab`)

DNS sinkhole (§9.9): NXDOMAIN by default, or 0.0.0.0 with mode = "zero".

Property	Type	Required	Description
pattern	utf8	yes	DNS name pattern to sink; wildcards allowed (required)
mode	utf8	no	Response: nxdomain (default) \| zero (resolve to 0.0.0.0)

Example:

wcl

sinkhole { pattern = "*.telemetry.com" mode = "nxdomain" }   // or mode = "zero"

§ 2`template` block

Template definition (§6.1), buildable with vmlab template build.

Property	Type	Required	Description
name	utf8	yes	Template name, e.g. linux-modern; the inline block label
arch	utf8	yes	Architecture — selects the QEMU system emulator (required)
version	utf8	yes	Version string, non-empty; name+arch+version is unique (required)
registry	utf8	no	Full OCI repo to publish to / version-bump against (§6.4)
profile	utf8	no	Guest OS profile (hardware defaults) for the build VM
cpus	i64	no	vCPU count for the build VM; inherited by clones
memory	std.ByteSize	no	RAM for the build VM, e.g. 8GiB; inherited by clones
disk	std.ByteSize	no	Working disk size for the build, e.g. 64GiB; required for scratch source
display	utf8	no	QEMU display string for the build VM
firmware	utf8	no	Firmware: ovmf \| seabios
tpm	bool	no	Enable a TPM 2.0 device
secure_boot	bool	no	Enable secure boot (OVMF only)
nested	bool	no	Enable nested virtualisation for the build VM
gui	bool	no	Watch the build VM via a VNC viewer (§11)
qemu_args	list<utf8>	no	Raw QEMU flags for the build VM — escape hatch (§5.2)
first_boot	utf8	no	wscript run on first instantiation of a clone, before ready

Child blocks

Slot	Accepts	Multiple	Description
source	source	no	What the build starts from — exactly one of four forms (required)
media	media	yes	ISO/floppy images attached to the build (§6.3)
provisions	provision	yes	Provision scripts that drive the build
nics	nic	yes	NICs for the build VM (optional; the build VM may be air-gapped)
extra_disks	disk	yes	Additional disks attached during the build

Example:

wcl

template "linux-modern" {
  arch    = "x86_64"
  version = "1.0"
  profile = "linux-modern"
  disk    = 20GiB                  // working disk size for the build
  source "iso" { url = "https://releases.ubuntu.com/.../x.iso" sha256 = "abc123…" }
  provision "scripts/install.ws" { }
}

§ 2.1`source` (in `template`)

Template build source (§6.1): exactly one of the four forms.

Property	Type	Required	Description
kind	utf8	yes	Source kind: iso \| qcow2 \| template \| scratch; the inline label
path	utf8	no	Local file path — iso/qcow2; mutually exclusive with url
url	utf8	no	Remote artefact URL — iso/qcow2; requires sha256
sha256	utf8	no	SHA-256 of the remote artefact; required with url
from	utf8	no	Source template <arch>/<name>[@<version>] — kind template (layered build)

Example:

wcl

source "iso"      { path = "./isos/win11.iso" }           // local installer ISO
source "iso"      { url = "https://…" sha256 = "…" }      // downloaded + verified
source "qcow2"    { path = "./base.qcow2" }               // existing disk as base
source "template" { from = "x86_64/linux-modern@1.0" }    // layered build
source "scratch"  { }                                     // blank disk

§ 2.2`media` (in `template`)

ISO/floppy image built from a folder (§6.3).

Property	Type	Required	Description
kind	utf8	yes	Image kind: iso \| floppy (required)
from	utf8	yes	Source folder built into the image; must exist (required)
label	utf8	no	Volume label for the image

Example:

wcl

media { kind = "iso"    from = "./unattend/" label = "CIDATA" }
media { kind = "floppy" from = "./drivers/"  label = "DRV" }

§ 2.3`provision` (in `template`)

Provision script run during vmlab up (§10.4). Optional vms list scopes the script for depends_on satisfaction (§7.2).

Property	Type	Required	Description
script	utf8	yes	Path to the .ws file; must exist and compile; the inline label
vms	list<utf8>	no	VM names this script is scoped to (gates their depends_on) (§7.2)

Example:

wcl

provision "scripts/setup.ws" { }                     // runs on `vmlab up`, in order
provision "scripts/join.ws"  { vms = ["client01"] }  // scoped: gates depends_on

§ 2.4`nic` (in `template`)

Property	Type	Required	Description
segment	utf8	no	Segment name to attach to; required unless nat = true
nat	bool	no	Shorthand: attach to the per-lab built-in NAT segment (§9.7)
ip	utf8	no	Static IPv4 (becomes a DHCP reservation); must be in the subnet, unique
mac	utf8	no	Fixed MAC, e.g. 52:54:00:ab:cd:ef; generated and persisted otherwise
isolated	bool	no	Port isolation: reach gateway/forwards but not segment neighbours (§9.1)

Example:

wcl

nic { segment = "corp" ip = "10.50.0.10" mac = "52:54:00:aa:bb:cc" }
nic { nat = true }                       // per-lab built-in NAT segment shorthand
nic { segment = "dmz" isolated = true }  // port isolation

§ 2.5`disk` (in `template`)

Additional disk (§5.2): blank by size, or pre-formatted from a folder.

Property	Type	Required	Description
name	utf8	yes	Disk identifier; the inline block label
size	std.ByteSize	no	Blank disk size, e.g. 10GiB; one of size/from is required
from	utf8	no	Folder copied onto a fresh FAT filesystem; one of size/from is required

Example:

wcl

disk "data"      { size = 10GiB }         // extra blank disk
disk "formatted" { from = "./payload/" }  // folder copied onto a fresh FAT filesystem

§ 3`host` block

Property	Type	Required	Description
subnet_pool	utf8	no	Segment auto-allocation pool (CIDR); default 10.213.0.0/16 (§9.4)
dns_suffix	utf8	no	Suffix for auto-registered VM names; default vmlab.internal (§9.5)
dns_upstream	utf8	no	Upstream resolver ip[:port]; default: the host resolver
disk_low_percent	i64	no	host.disk_low watchdog threshold percent (0–100); default 10 (§8.1)
psk	utf8	no	Pre-shared key for cross-host segment links (§9.2)
viewer	utf8	no	VNC viewer command; {} is replaced by the target (§11)
oci_chunk_size	std.ByteSize	no	OCI layer chunk size for template push; default 512MiB (§6.4)

Example:

wcl

host {
  subnet_pool      = "10.213.0.0/16"   // segment auto-allocation pool (default shown)
  dns_suffix       = "vmlab.internal"
  dns_upstream     = "1.1.1.1"
  disk_low_percent = 10
  viewer           = "vncviewer {}"    // {} = target
  oci_chunk_size   = 512MiB
}