Appendices · reference
Glossary
The words vmlab uses, in alphabetical order, each with the chapter that defines it. Where two words are easy to confuse, such as *login* and *logon* or *snapshot* and *workspace*, the entry says how they differ.
| Term | Meaning |
|---|---|
| agent | vmlab-agent, the process vmlab runs inside every guest, listening on the vmlab.agent.0 virtio-serial port. It carries exec, terminals, file transfer, the workspace watch, metrics and the clipboard. It is baked into a template at build time and shipped with the host for containers. See How vmlab runs a lab. |
| dev machine | A machine carrying the @dev decorator: a machine with a synced workspace, which vmlab keeps in step with a host directory. A lab may mark one of them default = true. See Dev machines and the workspace syncer. |
| event | A named occurrence in a lab, such as vm.crashed or host.disk_low, carried on the lab's event stream and written to the event log. See Events and handlers and the Events reference. |
| fabric | The userspace network vmlab runs every segment on: frame codecs, an L2 switch, DHCP, DNS, a gateway and a NAT engine, all in the lab daemon's process. No tap, bridge or macvlan. See Networking. |
| fast path | An optional kernel-assisted tier of the fabric (afxdp or sockmap) probed at daemon start and used when it works. vmlab fastpath says which tier is active. See Networking. |
| forward | A forward {} on a segment, or a port {} on a container, that maps a host TCP port onto a guest port. Planned as a whole before any is installed. See Networking. |
| global segment | A segment with global = true, owned by the supervisor rather than one lab, so machines from several labs share it; it can also peer with another host over a trunk. See Networking. |
| halt | The state a workspace enters when a sync pass finds a path changed on both sides. The whole workspace stops, both directions, on that one machine; nothing is written or deleted. Resolved from the host with the vmlab dev sync verbs. See Dev machines and the workspace syncer. |
| handler | An on "<event>" { run = … } block in the lab file that runs a wscript when the named event fires. See Events and handlers. |
| host config | vmlab-host.wcl, the per-user file that sets host-wide values: the store location, the viewer command, the fast path mode, the trunk port and PSK. See Host configuration and WSL 2 and the Host configuration file reference. |
| lab | One lab "<name>" {} in a vmlab.wcl: a set of machines and segments brought up and torn down together. Its name is its host-global identity. See The lab file. |
| lab container | A container {} in a lab: an OCI image pulled like a docker image and run inside a micro-VM, so it is a lab machine in every respect. See Lab containers. |
| lab daemon | The per-lab process the supervisor spawns on up: lifecycle, snapshots, the fabric for the lab's segments, events, shares and the syncer. Logs to .vmlab/lab.log. See How vmlab runs a lab. |
| ledger | The host-side record of what the two sides of a workspace last agreed on, per path. Guest changes are drained into it; the note that a re-seed is owed and the halt a restore refuses on both ride it. See Dev machines and the workspace syncer. |
| linked clone | A VM's disk: a qcow2 whose backing file is the template image in the store. Created on up under .vmlab/, kept by down, deleted by destroy. See Templates and the store. |
| login | A login {} block on a machine: a declared guest account a person lands as. vmlab exec --user, vmlab shell --user and a script's as_login select one by label. See Logins. |
| logon | The Windows session vmlab mints for a login: a token from LogonUser and a loaded profile, cached per (account, secret, machine). The Linux equivalent is a real session through su -l or setuid. See Logins. |
| machine | A VM or a lab container. Every verb that takes a machine name accepts either kind. See How vmlab runs a lab. |
| marker file | .vmlab-sync-halt, the file the syncer writes at the guest's workspace root when the workspace halts, and removes when the halt clears. It is the only signal the guest side receives. See Dev machines and the workspace syncer. |
| media | A media {} block: a host folder packed into an ISO or floppy image and attached to a machine, cached by content. See Lab file: vm and its children. |
| micro-VM | The minimal QEMU guest a lab container runs in: vmlab's own kernel and initramfs, with vmlab-cinit as PID 1, booting the image's flattened root filesystem. See Lab containers. |
| OCI artifact | The form a template takes on a registry: a multi-layer, multi-arch OCI package whose tags are the template's versions. See Distributing templates over registries. |
| playbook | A playbook {} block that runs a config-weave playbook inside the guest, as the machine identity. It has no login rung; anything that must land as a user belongs in a provision. See Playbooks. |
| profile | A guest OS profile: WCL data naming the firmware, devices, agent install route and defaults for a family of guests, such as linux-modern or windows-server. Shipped with vmlab and overridable. See Guest OS profiles. |
| provision | A provision "<script>.ws" {} block that runs a wscript against a machine once it is ready, in declaration order. The route for anything that must land as a login. See Guest automation with wscript. |
| prune list | The set of workspace paths the host computes from the layered ignore rules and hands the guest's watch, so the guest never reports what the host would discard. See Dev machines and the workspace syncer. |
| registry | An OCI registry, such as ghcr.io, that templates are pushed to and pulled from by ref. A template field holding a registry ref is pulled on up. See Distributing templates over registries. |
| re-seed | What follows a snapshot restore on a dev machine instead of a normal sync pass: a host-only, digest-based reconcile that carries the rewound guest back to the canonical copy before the watch reopens, and can emit no guest-to-host action. See Snapshots. |
| scratch VM | A VM with template = "scratch": a blank qcow2 with no backing image and no template layer in its hardware chain, for installing an OS from nothing. See Templates and the store. |
| segment | A segment {} in a lab: one L2 network with its own subnet, DHCP, DNS and optional NAT egress, routes and forwards. See Networking. |
| share | A share {} on a machine: a host folder mounted in the guest, over virtiofs on Linux or the bundled SMB server on Windows. See Shared folders. |
| snapshot | A saved state of a machine's disk and memory, captured and restored by vmlab snapshot. Not a workspace backup: a dev machine's source lives on the host. See Snapshots. |
| stat-walk | The syncer's full walk of the guest tree, run only on a watch discontinuity: the first sync, ledger loss, a watch overflow or a dropped channel. An overflow blocks both directions until it completes. See Dev machines and the workspace syncer. |
| store | The per-user directory of installed templates, keyed arch/name@version, written only by the supervisor. vmlab template list reads it. See Templates and the store. |
| supervisor | vmlabd, one per user, started by the CLI on demand. Spawns and reaps lab daemons, keeps the lab registry, owns global segments and trunks, serialises writes to the store, and runs the host watchdogs. Logs to vmlabd.log. See How vmlab runs a lab. |
| syncer | The workspace syncer: the loop in the lab daemon that keeps a dev machine's workspace and the host tree in step, both ways, as the machine's default login. See Dev machines and the workspace syncer. |
| template | A sealed, read-only disk image in the store that VMs clone from. Built from an ISO or cloud image by a template {} file, or pulled from a registry. See Templates and the store. |
| trunk | The PSK-authenticated TCP link two supervisors bridge a global segment over, so machines on two hosts share one L2 segment. The listen port is trunk_port in host config. See Networking. |
| viewer | The VNC client vmlab up opens for a machine with gui = true and vmlab console opens on demand. Chosen from host config, else found on PATH. See Screens, input and vision. |
| VM | A vm {} in a lab: a QEMU guest booted from a linked clone of a template, or from a blank disk when scratch. See Lab file: vm and its children. |
| watchdog | A supervisor check that fires an event on a host condition, such as host.disk_low when the filesystem under the store or a lab's clones passes the configured threshold. See Events and handlers. |
| workspace | The host directory @dev(workspace = …) names, mirrored into a dev machine as a guest-local copy of that canonical host tree. The host copy is what survives destroy. See Dev machines and the workspace syncer. |
| wscript | The scripting language vmlab's provisions, handlers and vmlab script run. vmlab registers its lab, segment and machine API as a wscript host module. See Guest automation with wscript. |
| wscripti | The .wscripti interface file describing that host module, which an editor's wscript language server reads for completion and diagnostics. See wscript API: Lab and Segment. |