winvm

winvm runs a local Windows 11 build VM on plain libvirt and QEMU, for a Linux machine that is not the CI farm. It installs Windows unattended, provisions the farm's MSVC toolchain, starts and stops the VM, runs a build in the guest that survives a dropped connection, keeps snapshots, and copies the Windows toolchain out for a cross build on the host.

winvm is the C++ port of the script integration/winvm/winvm, which was deleted on 2026-10-11 after the two drove a real guest the same way (script-ports §SCP-D-11, §SCP-T-8.2). The verbs, their arguments, the options, the exit codes and the ==> progress lines are the script's. The verbs live in the library libwinvm, so kiln and cross-sweep call the same functions. The script stays in the tree until a run on a real guest shows that the two do the same (§SCP-T-8.2).

To set up a VM and use it day to day, follow A local Windows 11 build VM.

Usage

winvm [options] check                    host requirements, loudly; changes nothing
winvm [options] fetch                    download and verify the ISOs and installers
winvm [options] create                   install Windows unattended, snapshot "installed"
winvm [options] provision                install the pinned toolchain, snapshot "provisioned"
winvm [options] start | stop | status
winvm [options] ssh [command...]         key auth, stock cmd.exe on the other end
winvm [options] run <label> <command>    run it detached: it survives an ssh drop
winvm [options] wait <label> [minutes]   block until that command ends; its exit code
winvm [options] screenshot <file.png>    what the console shows now
winvm [options] sysroot <folder>         copy the toolchain of a host cross build into <folder>
winvm [options] runtime <sysroot>        add what a Windows package carries to a sysroot
winvm [options] hostqt                   fetch this host's Qt tools of qt_version into cross_host_qt
winvm [options] snapshot list
winvm [options] snapshot save <name>     the VM must be shut off
winvm [options] snapshot restore <name>  the VM must be shut off; discards the changes since

The options come before the verb. Everything after the verb belongs to the verb, so winvm ssh dir /s gives /s to the guest.

Build and run it from the repository root:

qbs run -p winvm -- status

winvm runs on Linux. On another system it exits 2 and does nothing, except with --dry-run.

Verbs

Exit codes

Output

winvm writes its product to stdout: the ==> progress lines, the report of check, status and snapshot list, and the lines of a dry run. It writes a failure to stderr as winvm: <message>. The output of the programs it starts, such as the progress of curl, goes straight to the terminal.

Configuration

integration/winvm/winvm.conf holds the whole shape of the VM, as key = value lines. A blank line and a line that starts with # are skipped. A value runs to the end of the line, without the spaces around it. Every key is required. Nothing is read from an environment variable.

A file that breaks a rule is refused with the file, the line where there is one, and the rule, for example winvm.conf:12: unknown key 'colour' or winvm.conf: vcpus must be even (two threads per core).

State layout

<state_dir>/
  cache/            ISOs and installers, with SHA256SUMS
  disks/            current.qcow2, the writable top layer
  nvram/  tpm/      UEFI variables and TPM state
  snapshots/        one folder per snapshot: disk.qcow2, VARS.fd, tpm/, created
  secrets/          guest password, answer CD, known_hosts (mode 700)
  domain.xml        the definition given to libvirt
  provision-stage/  the scripts that provision copies into the guest
  provision.log, provisioned.json

Snapshots

A snapshot is a frozen qcow2 layer plus copies of the UEFI variables and the TPM state. Windows ties the three together, so they are saved and restored together. save moves current.qcow2 into the snapshot, makes it read-only and starts a new empty overlay on it. restore makes a new empty overlay on the chosen layer and copies the variables and the TPM state back. Neither copies the disk, and neither deletes a file. A snapshot name is letters, digits, ., _ and -.

Dry run

winvm --dry-run <verb> prints what the verb would do and changes nothing:

$ winvm --dry-run --dry-state running stop
+ virsh -q -c qemu:///session dominfo octomy-win11
+ virsh -q -c qemu:///session dominfo octomy-win11
+ virsh -q -c qemu:///session domstate octomy-win11
==> Shutting 'octomy-win11' down
+ virsh -q -c qemu:///session shutdown octomy-win11 --mode acpi
+ virsh -q -c qemu:///session dominfo octomy-win11
+ virsh -q -c qemu:///session domstate octomy-win11

A line that starts with + is an external command, quoted as a shell would read it. A line that starts with # is a file change. The dry run keeps a model of the domain: define makes it shut off, start makes it running, shutdown shuts it off. ssh answers 0. A wait whose .rc file is missing ends at once. A verb that needs an answer from the network, such as hostqt, stops where the answer is missing.

What it starts

winvm starts virsh, qemu-img, ssh, scp, ssh-keygen, xorriso, curl, patch and 7z, each by its absolute path and never through a shell. libvirt starts qemu-system-x86_64, passt, virtiofsd and swtpm. The JSON, the digests, the disk use, the free space, the memory and the port checks are done in the program.

The library

libwinvm (src/libs/libwinvm/) holds the configuration (winvm::Config), the renderers of the domain, the answer file and the run script, and each verb as a function of winvm::Vm. The paths of the external programs are one winvm::Programs value, and the programs start through a winvm::Runner. A test gives the paths of program-stub copies, or a runner that records each command, so testWinvm runs create, snapshot save and snapshot restore end to end without a VM.