jumPhp/tools/runner/windows-vm/README.md
2026-11-07 18:25:39 +01:00

7.1 KiB

A headless Windows VM on Linux, as a CI runner for Windows builds

For a Linux user who needs Windows jobs (the Windows library of the Tauri runtime, .exe, installers): QEMU/KVM runs a Windows 10 VM with no window; install-windows-runner.ps1 is installed inside it. The full guide (which runner for which job, security, troubleshooting) is docs/ci-runner.md (en français).

Based on a setup in daily use (unattended Windows 10 install, virtio drivers, the QEMU guest agent to drive PowerShell without SSH). Verified end to end on a Debian host: create-vm.sh (French Windows 10 Pro 22H2 ISO, 2 vCPU, 3 GB) then provision.sh, see "What was tested" at the end.

Licence, plainly

  • Windows needs a licence you own. This kit installs Windows 10 Pro without a product key it would activate; the generic key it uses (published by Microsoft) only lets Setup choose the Pro edition. An unactivated Windows 10 runs (watermark, no personalization) but you must hold a licence for it.
  • Nothing is downloaded from Microsoft by these scripts, and no Windows image is shipped here. You download the ISO yourself, from Microsoft's page: https://www.microsoft.com/software-download/windows10ISO (from a browser: "Windows 10 (multi-edition ISO)", your language, 64-bit). Never use an ISO from another source.
  • Evaluation ISOs expire (the Enterprise LTSC 2021 evaluation ISO was seen installing already expired; others stop after 90 days and the VM then shuts down every hour). Use the multi-edition ISO above.
  • Windows 10 no longer receives free security updates since October 2025: keep the VM throw-away, with nothing personal in it (see the security section of the guide).

What you need on the host

Linux with KVM (/dev/kvm, you in the kvm group), 8 GB of RAM or more (the VM takes 8 GB by default, 4 GB is enough for the Tauri library), 80 GB of disk (sparse file), and:

sudo apt install qemu-system-x86 qemu-utils ovmf genisoimage python3 curl     # Debian / Ubuntu
sudo dnf install qemu-kvm qemu-img edk2-ovmf genisoimage python3 curl         # Fedora

Steps

cd tools/runner/windows-vm            # or: bin/jumphp runner:scripts ~/runner-kit && cd ~/runner-kit/windows-vm

# 1. create the VM (about 15 to 40 minutes, unattended; the virtio-win CD, ~700 MB, comes from the Fedora project)
./create-vm.sh --iso ~/Downloads/Win10_22H2_English_x64.iso --dir ~/windows-ci-vm
#    other language: --locale fr-FR --timezone "Romance Standard Time"   (the locale must be in YOUR ISO)
#    the administrator "ci" password is random, saved in ~/windows-ci-vm/credentials.txt (mode 600)

# 2. install the runner INSIDE it (token of ONE user or organization; 20 to 60 minutes the first time)
export JUMPHP_RUNNER_TOKEN=<registration token>          # forge: Settings > Actions > Runners > Create new runner
./provision.sh --dir ~/windows-ci-vm --scope org/<name> --name win-vm

# 3. daily use
./start-vm.sh --dir ~/windows-ci-vm            # start (headless); Windows starts the runner by itself at boot
./start-vm.sh --dir ~/windows-ci-vm status
./start-vm.sh --dir ~/windows-ci-vm stop       # clean shutdown through the guest agent

WINVM_DIR=~/windows-ci-vm in your environment replaces --dir everywhere.

The files

File Role
create-vm.sh builds the disk, the UEFI variables, the answer-file CD (Autounattend.xml + firstlogon.ps1), boots the Windows ISO headless (answers "press any key" over QMP), waits for the end, reboots on the normal virtio hardware, deletes the answer file (it holds the password). --no-wait / --resume split it in two.
start-vm.sh headless QEMU/KVM. start, stop (guest agent), status, kill. Ports on 127.0.0.1 only: RDP 3390, SSH 2222, and the guest agent socket <dir>/qga.sock.
guest-exec.py PowerShell in the guest through the QEMU guest agent: -c 'cmd', -f script.ps1, --put LOCAL REMOTE, --put-env VAR REMOTE, --detach, --ping. No SSH, no network.
provision.sh copies ../install-windows-runner.ps1 into the guest and runs it there (detached, followed to the end). The token comes from the environment and goes to a file only Administrators can read, deleted at once by the guest wrapper: never on a command line (ps).

Open a desktop on the VM when you need to (activation, a dialog): xfreerdp /v:127.0.0.1:3390 /u:ci (password in credentials.txt). The port is bound to localhost: from another machine, go through an SSH tunnel.

Day-to-day notes

  • Reset to a clean state: stop the VM and take a copy of disk.qcow2 + vars.fd right after provision.sh (qemu-img snapshot -c clean disk.qcow2 while it is stopped, qemu-img snapshot -a clean disk.qcow2 to go back). The runner's credentials are on that disk: after a revert the runner is still registered.
  • Auto-start with your machine: a systemd user service running start-vm.sh --dir ... start, or just start it when you need builds; jobs wait in the forge's queue while the runner is off.
  • Disk: Rust's target folders grow; delete C:\ci\target-tauri in the guest from time to time.
  • Update the runner / tools: run provision.sh again (it is idempotent: it only installs what is missing; a new Rust version is the -RustVersion parameter of the .ps1, which must match RUST_VERSION of the workflow).
  • Remove everything: ./start-vm.sh --dir D stop, delete the folder D, then delete the runner in the forge.

Troubleshooting

  • cannot reach the guest agent socket: the VM is not running (start-vm.sh status), or Windows is still booting (the agent answers some 30 s after the logon screen). create-vm.sh installs it from the virtio-win CD.
  • /dev/kvm is missing or not writable: enable virtualization in the BIOS; sudo usermod -aG kvm $USER, log in again.
  • The install seems stuck: take a look with python3 - <<'EOF' ... QMP screendump (see qmp.sock in the VM folder), or RDP once Windows is up. Setup needs the ISO language to match --locale; the edition name must exist in the ISO (--image-name "Windows 10 Pro"; list them with wiminfo from wimtools, or give --image-index).
  • The disk is virtio-blk: a Windows ISO older than Windows 10 1903 may not take the drivers path; use 22H2.
  • create-vm.sh was interrupted: ./create-vm.sh --dir D --resume waits for the end and finishes.
  • Everything else about the runner itself (registration, labels, jobs): the troubleshooting section of the guide.

What was tested

Host Debian 13, QEMU 10, KVM; ISO Win10 22H2 French multi-edition from Microsoft's page. create-vm.sh --locale fr-FR produced a working Windows 10 Pro (French) in about 15 minutes with the guest agent, virtio network, RDP and OpenSSH running, and start-vm.sh (headless, localhost-only ports) restarted it. provision.sh + install-windows-runner.ps1 were run on this fresh VM (log in the session notes) and, in a second VM that already had the tools, re-run to check idempotence. Not tested: other locales, Windows 11 (needs TPM and Secure Boot, not covered), non-Debian hosts, hosts without KVM.