Introduction · explanation

Introduction

6 min read · 2026-09-02 · vmlab 0.9

vmlab is a single-host lab orchestrator for QEMU/KVM. You declare a lab in one file, vmlab.wcl, and vmlab brings it up as a unit: the virtual machines, the containers, the networks between them, and the scripts that configure the guests once they boot. There is no libvirt in the path. vmlab drives QEMU directly over QMP and talks to each guest over its own agent.

What a lab is made of

A lab is a named group of machines and segments, defined in WCL, a typed configuration language. vmlab validates the whole file against a schema before it starts anything, so a mistyped field or a NIC on a segment that does not exist is reported before a single QEMU process runs.

• A segment is a virtual L2 network with its own DHCP, DNS, NAT and port forwards. See Networking.
• A VM is a linked clone of a template, a sealed base disk you build once from installer media or pull from a registry. See Templates and the store and Distributing templates over registries.
• A container is an OCI image run inside its own micro-VM, so it sits on the same segments and has the same snapshots and agent channel as a VM. See Lab containers.
• Provision scripts and playbooks configure a guest after it boots. Provisions are wscript, an imperative language with a typed guest API. Playbooks are config-weave plays with a drift check. See Guest automation with wscript and Playbooks.
• Snapshots, both online and offline, are taken per machine or lab-wide. See Snapshots.
• A dev machine is any VM or container marked @dev. vmlab keeps a workspace on it in step with a directory on the host, so you edit with your own tools and build in the guest. See Dev machines and the workspace syncer.

Every guest is reached through exactly two doors. QMP carries power state, devices and the screen. The agent, vmlab-agent, runs inside the guest on a virtio-serial port and carries command execution, file transfer, interactive terminals, log tailing and readiness. The agent never touches the guest's network, so an air-gapped machine is as scriptable as one with internet egress. A guest that cannot run the agent is still driven through the screen with keystrokes, image matching and OCR. See Screens, input and vision.

A login is the account a person lands as inside a guest, through vmlab exec, vmlab shell or a script. It is a login {} the lab file declares, and the agent mints it with no guest network involved. See Logins.

Who this manual is for

You build and run virtual machines on a Linux workstation and want the whole environment written down in a file you can commit, share and rebuild. Typical readers are engineers standing up a Windows domain to test against, a cluster of Linux hosts to rehearse a deployment on, a disposable development box that builds your checkout, or a security lab that must stay off the network.

The manual assumes you are comfortable in a shell and have used a hypervisor before. It does not assume you know WCL or wscript. The tutorials introduce each as it is needed, and the reference chapters define every field and function.

How this manual is organised

The manual has five parts. Read them in order the first time, then use the reference and command chapters as a lookup.

1. Getting started is a sequence of tutorials. You install vmlab, bring up a lab with one container, run a VM from a registry template, build a template from an ISO, and write a provision script. Each tutorial ends with a working lab on your host.
2. The guide explains how vmlab works and why: the two daemons, the lab file, templates, networking, containers, shared folders, snapshots, scripting, vision, playbooks, logins, dev machines, profiles, host configuration and events.
3. Reference defines every block and field of the lab file, the host configuration file, the guest OS profiles, every function of the wscript API, the events, the files vmlab writes, and the wire protocol with its error codes.
4. Commands documents each vmlab verb with its synopsis, options and exit status, one chapter per top-level verb.
5. Appendices hold the troubleshooting guide, the glossary, and a tour of the example labs shipped with the source.

Platform requirements at a glance

vmlab runs on Linux, or on Windows inside WSL 2. It needs /dev/kvm for native acceleration. Guests may be x86_64, aarch64 or riscv64. A guest whose architecture matches the host runs under KVM. Any other architecture is emulated, which works but is slow. Install lists the exact packages. Host configuration and WSL 2 covers the WSL 2 setup, where nested virtualisation must be switched on for /dev/kvm to appear.

Tool	What vmlab uses it for
qemu-system-<arch>, qemu-img	Running guests and managing qcow2 disks
SeaBIOS	BIOS guest firmware; UEFI firmware (OVMF, AAVMF) ships with vmlab
swtpm	A TPM 2.0 device for guests that want one
passt	Part of the userspace network fabric
xorriso, mtools, mkfs.vfat	Building ISO and floppy images from folders
smbd from Samba, virtiofsd	Shared folders
sqfstar from squashfs-tools	Flattening container images for micro-VMs
tesseract	OCR of the guest screen
A VNC viewer	vmlab console and gui = true

The network fabric is entirely userspace. vmlab creates no tap devices, no bridges and needs no capabilities, which is what makes it work unchanged under WSL 2.