Concepts

Each concept has its own page — open one from the list below or the sidebar.

- Start here — Getting started using VMLab.

- How vmlab fits together — The big picture: front ends, the two-tier daemon, QEMU processes, the userspace network fabric, templates and clones, and the two guest channels.

- Lab containers — OCI containers as first-class lab machines: each runs in a micro-VM, sharing the VM namespace, segments, snapshots and agent channel (PRD §18).

- Automating labs — The four automation surfaces — provision scripts, event handlers, playbooks, and ad-hoc drives — and how to pick between them.

- Networking model — Networking is declarative: virtual L2 segments with daemon-supplied DHCP/DNS/NAT/routing/L3 filtering in userspace — no vmlab net CLI.

- Provisions & event handlers — provision {} scripts run on vmlab up (failure is fatal); on "event" {} handlers react to lifecycle events (failure is logged).

- Templates — Sealed qcow2 disk images in the local store, referenced by <arch>/<name>[@<version>]; labs boot linked clones of them.

- Linked clones — Labs boot copy-on-write linked clones backed by a template's sealed disk; the template itself is never written to.

- Template build flow — A build resolves the source, boots a synthesised one-VM lab, runs the provisions, then flattens and seals into the store; a failed build leaves nothing behind.

- Scratch VMs — template = "scratch" boots a blank disk with no template; needs explicit arch, profile and disk.

- OCI distribution — Templates push/pull as OCI artifacts (not runnable images) through any OCI registry; chunked, multi-arch.

- Daemon model — A two-tier daemon: the supervisor vmlabd (one per user) plus one lab daemon per running lab, auto-started by the CLI.

- Host config — Optional ~/.config/vmlab/config.wcl tunes the subnet pool, DNS, disk watchdog, viewer command and OCI chunk size.

- Guest OS profiles — Shipped hardware-default sets (windows-11, linux-modern, …); override or extend by dropping *.wcl into ~/.config/vmlab/profiles/.

- Running vmlab in a container — Hosting vmlab itself in Docker/Podman with /dev/kvm; optional eBPF networking adds /dev/net/tun, CAP_BPF and CAP_NET_ADMIN. (For OCI containers as lab machines, see Lab containers.)

- WSL2 — WSL2 is a first-class host — no tap/bridge/macvlan and no CAP_NET_ADMIN; reach guests via port forwards.

- The web console — The browser UI served by vmlab-web: visual lab designer, per-machine consoles and terminals, template builds, playbooks, a whole-lab file editor, and proxied guest web pages.

- Playbooks (config-weave) — Declarative guest configuration via config-weave: playbook {} blocks apply on vmlab up interleaved with provisions, re-run on demand with vmlab playbook check|apply, and drive template builds.

- Network fast path (eBPF) — Optional kernel-accelerated tiers above the userspace switch: AF_XDP (picked by auto) and sockmap (explicit-only); probed at startup, falling back to userspace.

- wscript: overview — A statically typed, Rust-flavoured scripting language; vmlab type-checks scripts at vmlab validate time.

- wscript: types & values — 64-bit ints, floats, strings, bool; no implicit numeric conversion, no truthiness, reference semantics for compound types.

- wscript: functions & control flow — Block-valued fn bodies, closures, if/for/while/loop; ranges are exclusive (0..10) or inclusive (0..=10).

- wscript: pattern matching & errors — Option[T] and Result[T,E] are built in; let-else, match (exhaustive), and ? are the idioms vmlab scripts live on.

- wscript: modules & prelude — use vmlab imports the host module; an always-on prelude is ambient; scripts are single files in v1.