| Filename | Latest commit message | Latest commit date |
|---|---|---|
|
Some checks failed
extension-new / extension (push) Failing after 4s
Co-Authored-By: Claude Sonnet 5.5 <[email protected]> Claude-Session: https://claude.ai/code/session_01UZqwpEuvsZPDaT1EV6KAvq |
||
| .. | ||
| create-vm.sh | ||
| guest-exec.py | ||
| provision.sh | ||
| README.md | ||
| start-vm.sh | ||
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.fdright afterprovision.sh(qemu-img snapshot -c clean disk.qcow2while it is stopped,qemu-img snapshot -a clean disk.qcow2to 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
targetfolders grow; deleteC:\ci\target-tauriin the guest from time to time. - Update the runner / tools: run
provision.shagain (it is idempotent: it only installs what is missing; a new Rust version is the-RustVersionparameter of the.ps1, which must matchRUST_VERSIONof 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.shinstalls 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'... QMPscreendump(seeqmp.sockin 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 withwiminfofromwimtools, 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.shwas interrupted:./create-vm.sh --dir D --resumewaits 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.