A unified automation that installs Ubuntu LTS or Gentoo with
GNOME on Wayland inside a QEMU VM on Apple Silicon (aarch64),
fully unattended. GPU-accelerated
graphics via VirGL (hardware-rendered OpenGL in the guest through the
qemu-virgl tap) and Venus (hardware-accelerated Vulkan over virtio). The script
always discovers the latest version of each distro at runtime — no
hardcoded release numbers.
Already have QEMU installed?
git clone https://github.com/milesbuckton/linux-desktop-vm.git
cd linux-desktop-vm
# One-time: a project venv with the declared dependencies (the script never
# installs Python packages itself; it stops with a clear error if one is missing)
python3 -m venv .venv && .venv/bin/pip install -r requirements.txt
source .venv/bin/activate
# Default = Ubuntu LTS, vCPU = half your host's cores (clamped 2-8), RAM = half host memory (clamped 8-32 GB), 80 GB disk
python setup_vm.py
# Watch progress with the live phase-based progress bar:
python setup_vm.py monitor ~/VMs/ubuntu-ltsThe script downloads the latest cloud image, builds a NoCloud seed ISO
with cloud-init, generates the QEMU launch script; pass --start to also launch it (the default is build-only). Cloud-init Phase 2 (guest install) took 48.0 min on Ubuntu [49.4 min VM total] and 185.1 min on Gentoo [188.6 min VM total] in the latest full-matrix run on an idle host (Gentoo varies with binhost warmth, host load and arm64 source builds); GDM is started on that same boot (there is no reboot), and you log in
with the username and its password (which defaults to the username) from
<target_dir>/install-info.txt.
Guests default to the host's timezone (UTC if it cannot be detected) and locale
en_ZA.UTF-8; en_GB.UTF-8 and en_US.UTF-8 are generated too.
This repo orchestrates a stack of forks and packages (how they fit together: docs/ARCHITECTURE.md):
| Repository | Layer | Role |
|---|---|---|
| linux-desktop-vm (this repo) | Orchestration | Cloud image download, cloud-init NoCloud seed, distro templates (Ubuntu/Gentoo), QEMU launcher, install monitoring, check-vm |
| homebrew-qemu-virgl | Packaging | Homebrew tap: qemu-virgl, virglrenderer, libangle, libepoxy-angle, kosmickrisp |
| milesbuckton/qemu | Hypervisor | Patched QEMU AArch64: HVF, Cocoa gl=es display, virtio-gpu-gl-pci with Venus/blob; ships the edk2-aarch64 firmware |
| miles.buckton/virglrenderer | Host renderer | macOS/HVF fixes, Venus host path (-Dvenus=true); dlopens host Vulkan (MoltenVK or KosmicKrisp, picked by --host-vulkan-driver) |
| miles.buckton/mesa | Host/guest 3D | Built from source in the guest during cloud-init (VirGL + Venus drivers, replacing distro Mesa on Ubuntu and Gentoo); also the KosmicKrisp Vulkan-on-Metal driver (macOS 26+, opt-in host Vulkan driver) |
QEMU is the only supported hypervisor. Key advantages:
| Feature | QEMU |
|---|---|
| Acceleration | HVF (macOS) |
| License | Open source (GPLv2); no registration required |
| Disk format | qcow2 (native) |
| Snapshots | qemu-img snapshot -c (CLI) |
Hypervisor accelerator acronyms (used throughout this README): HVF = Hypervisor.framework (macOS's userspace hypervisor API, since 10.10), TCG = Tiny Code Generator (QEMU's pure-software JIT translator — the "no hardware acceleration" fallback; ~10-20× slower, boot times in hours not minutes). QEMU picks the first of these available on the host via the
hvf:tcgaccelerator fallback chain.
Detect, don't install — the script never auto-installs a hypervisor on your behalf. If no virgl-enabled QEMU is found (see the probe order in ARCHITECTURE.md), the script prints an install hint and exits 3. Stock Homebrew
qemuis never installed or used — not even forqemu-img, which must come fromqemu-virgl(exit 4 otherwise). Python dependencies are never installed: run from the project.venvwithrequirements.txtinstalled.
Works on macOS hosts (Apple Silicon only — Intel Macs are not supported):
- Apple Silicon (aarch64 guests — the validated and only supported path): QEMU (HVF)
Guests run aarch64 on Apple Silicon — the validated and only supported path (the full distro fleet matrix has been built out on aarch64 guests).
The guest always sees virtio-sound audio + xHCI USB 3, so PipeWire/USB code paths are identical. Disk controller, NIC, GPU, and guest-agent stack are picked by the script's Jinja2 templates automatically:
| Subsystem | QEMU |
|---|---|
| Acceleration | HVF (macOS) |
| Disk controller | virtio-blk (virtio_blk) |
| NIC | virtio-net (virtio_net) |
| Audio controller | virtio-sound-pci (virtio_snd), playback + microphone (streams=2; capture needs a current qemu-virgl with CoreAudio input — see Troubleshooting) |
| USB controller | xHCI (xhci_pci) |
| GPU host device | GL: virtio-vga-gl if the build has it, else virtio-gpu-gl-pci (the qemu-virgl tap only has the latter; with Venus adds venus=on,blob=on,hostmem=4G + -vga none); non-GL fallback (only if the virgl build's cocoa GL probe fails): virtio-vga, else virtio-gpu-pci. A non-virgl QEMU is refused (exit 3) |
| GPU kernel driver | virtio_gpu.ko |
| Mesa gallium driver | virgl (virgl_dri.so); llvmpipe (software) only if the cocoa GL probe fails |
| 3D acceleration | Hardware GL (VirGL) + hardware Vulkan (Venus); software (llvmpipe / Lavapipe) only if the cocoa GL probe fails |
| Vulkan | Hardware (Venus, Vulkan-over-virtio) when the QEMU build ships a Venus-capable virglrenderer with a working host Vulkan ICD (MoltenVK by default, or KosmicKrisp via --host-vulkan-driver kosmickrisp); otherwise Lavapipe (software Vulkan). vulkaninfo --summary on a built VM lists two GPUs: GPU0 venus, GPU1 llvmpipe. |
| Display session | Wayland |
| Mouse integration | USB tablet (absolute coords; no capture/release) |
| Window resolution | Follows the QEMU window: resize the window (or go full screen) to change it |
| Host SSH forward | host port (first free in 2222-2321, or --ssh-port) → guest port 22, bound to 127.0.0.1 only (never exposed on the LAN; the generated launcher picks the port each time it starts) |
| Firmware | UEFI via OVMF |
| VM definition file | launch-vm.sh (QEMU argv) |
The guest is configured identically across distros from a desktop user's perspective: sound, USB, 3D-accelerated graphics, NetworkManager, PipeWire, GDM (Wayland session), and cloud-sync tooling.
--distro |
Resolves to | Release model | Hash | Default user | Default hostname | Template | Resolver | Cloud image source | Firmware |
|---|---|---|---|---|---|---|---|---|---|
ubuntu-lts (default) |
Latest Ubuntu LTS | 2-year cadence | SHA256 | ubuntu |
ubuntu-lts-vm |
ubuntu.j2 |
_resolve_ubuntu_lts |
https://cloud-images.ubuntu.com/ |
UEFI |
gentoo |
Latest Gentoo cloud image (rolling) | Rolling | SHA256 | gentoo |
gentoo-vm |
gentoo.j2 |
_resolve_gentoo |
https://distfiles.gentoo.org/releases/ |
UEFI |
What today's cloud images ship inside these VMs (these float with upstream releases, so treat them as a snapshot):
| Distro | Kernel | GNOME Shell |
|---|---|---|
ubuntu-lts (26.04) |
7.0.0-28-generic | 50.1 |
gentoo |
6.18.48-gentoo-dist | 49.7 |
Gentoo only: one GNOME Shell extension is installed and enabled system-wide
(dconf default 05-extensions): dash-to-dock
(dash-to-dock@micxgx.gmail.com). Under the fleet builder the guest fetches
the zip from a host-served local HTTP server (QEMU's 10.0.2.2 gateway,
first free port in 8753-8773) during cloud-init, avoiding GitHub's flaky
first-boot connection. A standalone setup_vm.py build, or a failed
host-served download, falls back to the GitHub release. A shell-version gate skips the install if the
release does not declare the guest's GNOME major; it joins metadata.json
across lines (upstream pretty-prints it, and grep is line-based) and matches
an exact quoted version so a shell major of 5 cannot prefix-match "50".
Ubuntu keeps its stock dock instead. Ubuntu's session mode
(/usr/share/gnome-shell/modes/ubuntu.json) force-enables
ubuntu-dock@ubuntu.com independently of dconf, so Ubuntu neither installs nor
enables dash-to-dock — two dock extensions enabled at once would render two
docks. Gentoo has no session-mode dock at all, so without dash-to-dock its
desktop would ship with no dock. Both the install and the dconf enable are
driven by one install_dash_to_dock flag set per distro, so they cannot drift
apart.
| Extension | Source | Installs on |
|---|---|---|
dash-to-dock (dash-to-dock@micxgx.gmail.com) |
GitHub | Gentoo (whenever the release declares the guest's GNOME major); not on Ubuntu, which keeps stock ubuntu-dock |
The GNOME Extensions GUI is installed on every distro, so the user can install
any other extension themselves from the Extensions app. On Ubuntu 26.04 the
Extensions app ships inside the gnome-shell package itself
(org.gnome.Shell.Extensions) — the old standalone gnome-extensions-app
package no longer exists in the archive.
Every VM built by this tool gets the same curated set of apps via native packages, visible in the GNOME Software GUI.
Same app on both distros; the exact package name differs by distro (the Package naming differences legend below is the canonical per-name reference).
| Slot | What it is |
|---|---|
| Epiphany (default browser) | The default web browser on both distros. Firefox was removed from the app set: Ubuntu's firefox is an apt snap shim (so the removal must purge firefox* and snap remove firefox), and ubuntu-desktop-minimal Recommends firefox anyway — the templates hard-remove it and the verify gate fails the build if it reappears. Chrome still installs as an alternative on both. |
| GNOME Tweaks | Advanced desktop customization (fonts, titlebar, shell themes) — User Themes is pre-enabled and the Shell theme is pinned to the distro default (see GNOME desktop defaults below) |
| Cloud sync CLI | rclone |
| GNOME Console | Terminal (GNOME's default; the templates do not set a default terminal themselves) |
| GNOME Text Editor | Default plain-text "notepad" (replaced gedit in GNOME 42+) |
| yelp | GNOME Help viewer (F1 from any GNOME app opens here) |
| GNOME Videos (Totem) | Default GNOME video player |
| GNOME Loupe | Default GNOME image viewer (replaces Eye of GNOME) — native on both distros (Gentoo: KEYWORDS="~amd64" only, so unmasked with media-gfx/loupe **) |
| Snapshot (camera) | Default GNOME camera (Cheese's successor) — on Gentoo installed via Flathub (org.gnome.Snapshot, no ebuild yet); native on Ubuntu |
| GNOME Clocks | Alarms / world clock / stopwatch — native on both (Gentoo unmasks gnome-extra/gnome-clocks ~arm64) |
| Evolution | Full mail + calendar + contacts groupware client. Geary stays installed as the lightweight alternative. Both pull evolution-data-server anyway, so Evolution adds only its own frontend packages. |
| Sound theme | Event sounds. Ubuntu uses Yaru (yaru-theme-sound), Gentoo keeps freedesktop. |
| Archive Manager (File Roller) | Default GNOME archive extraction and compression GUI (file-roller on Ubuntu; app-arch/file-roller on Gentoo) |
| Contacts | GNOME Contacts address book (gnome-contacts on Ubuntu; gnome-extra/gnome-contacts on Gentoo) |
| Color emoji font | System-wide color emoji support (fonts-noto-color-emoji on Ubuntu; media-fonts/noto-emoji on Gentoo) |
| GL benchmark (glmark2) | Full-screen GL benchmark. Ubuntu gets glmark2-es2-wayland and glmark2-wayland as apt binpkgs (the distro names the per-platform builds; the source package is glmark2, data in glmark2-data); Gentoo has no ebuild, so upstream glmark2 is cloned and built from source into /usr/local/bin for four flavors — glmark2, glmark2-es2, glmark2-wayland, glmark2-es2-wayland — plus its data tree under /usr/local/share/glmark2 (ninja install is what provides the data; a binary alone core-dumps on the first shader). All build deps (wayland-client/cursor/egl, wayland-protocols ≥ 1.12, wayland-scanner, x11, libjpeg, libpng) already ship with the GNOME stack, so nothing extra is emerged. Best-effort on Gentoo (GLMARK2-OK / GLMARK2-SKIP markers; the verify block warns but does not fail). |
| GNOME Papers | Default PDF / document viewer |
| Geary | Lightweight modern GNOME mail client (conversation-threaded, IMAP/OAuth2) |
| GNOME Weather | Native weather app (explicit on both distros; not pulled by the Ubuntu desktop meta) |
| Python tooling | python3 (interpreter) is base on every distro; we add pip and venv where separate |
| GNOME Extensions GUI | Browse/enable/disable GNOME shell extensions |
| Mesa demos (glxgears, glxinfo, eglinfo, es2gears) | GL diagnostics — required by scripts/check-virgl.sh. The Wayland render test (es2gears) is what its render gate runs; on Ubuntu it arrives with mesa-utils-bin, on Gentoo it is built from source (see the package-naming table below). |
| Vulkan tools (vulkaninfo) | Vulkan diagnostics — required by scripts/check-venus.sh |
| NetworkManager systray + connection editor | GUI network settings (the applet in the status area plus the Network Connections editor). Ubuntu gets it from apt network-manager-gnome; Gentoo from gnome-extra/nm-applet (upstream network-manager-applet). Note the Gentoo daemon alone (net-misc/networkmanager) provides no GUI — the applet is a separate package on both. |
| fastfetch | Terminal system-info tool (neofetch successor) |
| Fira Code font | Monospaced coding font with programming ligatures (Ubuntu: apt fonts-firacode; Gentoo: media-fonts/fira-code) |
| Google Chrome | Best-effort install ⁴ — apt google-chrome-stable (vendor repo registered in bootcmd, simulate-validated) on Ubuntu; Portage www-client/google-chrome on Gentoo (EULA accepted via package.license; the arm64 .deb is fetched from dl.google.com — upstream ships no arm64 binpkg). Installs on aarch64 on both. |
| Flatpak + Flathub | flatpak framework preinstalled on both + the Flathub remote registered (GNOME Software's Flatpak plugin installs from it). |
| Flatseal | Flatpak permission manager, installed from Flathub (best-effort ⁴). |
| Gear Lever | Flatpak app manager (upgrade/downgrade/backup), installed from Flathub (best-effort ⁴). |
| Snap packages | Both distros install snapd (runtime for snaps), snap-store, and bing-wall. steam is NOT installed (a classic snap on arm64 pulls in the full Steam runtime and dominated the cloud-init tail). Ubuntu pulls snapd from apt; Gentoo source-builds app-containers/snapd + sys-fs/squashfuse (neither has an arm64 binpkg) and asserts them in its verify block. |
| PowerShell | Best-effort universal tarball install (pwsh) — pulled from the GitHub release for the guest arch and symlinked to /usr/local/bin/pwsh. Not package-manager tracked (no auto-update); chosen over the Microsoft apt repo because it lags the newest distro bases (Ubuntu 26.04). Emits POWERSHELL-OK / POWERSHELL-MISSING in the cloud-init log (best-effort ⁴). |
Every VM boots with its distro's own branded wallpaper as both the desktop background and lock screen, set via system-wide dconf. The branding package per distro:
| Distro | Branding package | Wallpaper source | Accent color |
|---|---|---|---|
| Ubuntu | ubuntu-wallpapers (transitive via ubuntu-desktop-minimal) |
/usr/share/backgrounds/*-final-ubuntu.png |
Orange |
| Gentoo | x11-themes/gnome-backgrounds (explicit; GNOME default) + x11-themes/adwaita-icon-theme + x11-themes/gnome-themes-standard |
/usr/share/backgrounds/ (GNOME default) |
GNOME default (blue) |
Set via system-wide dconf database (/etc/dconf/db/local.d/) so every user inherits these on first login:
| Setting | Value | Why |
|---|---|---|
org.gnome.Epiphany.web enable-webextensions |
true |
Epiphany supports WebExtensions but ships disabled-by-default. We enable it system-wide. |
org.gnome.desktop.interface color-scheme |
'prefer-dark' |
Default to dark mode. Users can flip via Settings → Appearance. |
org.gnome.mutter dynamic-workspaces |
false |
|
org.gnome.desktop.wm.preferences num-workspaces |
1 |
Boot with exactly one workspace, no auto-spawned extras. Toggle back to dynamic via Settings → Multitasking. |
org.gnome.desktop.background picture-uri / picture-uri-dark |
Distro wallpaper | Each distro gets its own branded default desktop wallpaper. |
org.gnome.desktop.screensaver picture-uri |
Distro wallpaper | Lock screen matches the desktop background. |
org.gnome.desktop.sound theme-name |
'Yaru' (Ubuntu) / 'freedesktop' (Gentoo) |
Ubuntu's yaru-theme-sound event sounds. Ubuntu also ships a gschema override (10_ubuntu-settings.gschema.override) setting Yaru as the default; the system dconf database also sets it as the system default (no lock, so users can change it). |
org.gnome.shell enabled-extensions |
Gentoo: Desktop Icons NG (ding@rastersoft.com) + dash-to-dock + User Themes; Ubuntu: Desktop Icons NG + User Themes |
User Themes (user-theme@gnome-shell-extensions.gcampax.github.com, ships in each distro's gnome-shell-extensions package) enabled by default, so GNOME Tweaks shows the Shell dropdown out of the box. Gentoo also enables dash-to-dock (its only dock); Ubuntu's dock comes from its session mode (ubuntu-dock), and enabling a second, uninstalled dock there would be meaningless. |
org.gnome.shell.extensions.user-theme name |
Yaru-dark (Ubuntu) / Adwaita (Gentoo) |
Tweaks → Appearance → Shell pinned to the distro's default shell theme (Ubuntu's dark Yaru variant, matching prefer-dark; GNOME's Adwaita on Gentoo). |
Default browser (x-scheme-handler/http(s), text/html) |
Epiphany (org.gnome.Epiphany.desktop) |
Set system-wide via /etc/xdg/mimeapps.list + per-user xdg-settings, so links open in Epiphany. Chrome remains installed as an alternative (Firefox was removed from the app set). Marker: BROWSER-DEFAULT-OK. |
The installer aims for the same user-facing GNOME desktop everywhere, but Linux distro release cycles and package naming do not fully align.
Loupe (image viewer, media-gfx/loupe) is keyworded ~amd64 only (no
arm64 entry), so it is unmasked with ** in package.accept_keywords and
installed natively by the install script — same path as the other distro.
Snapshot (camera) still has no Gentoo ebuild, so it alone is installed
from Flathub best-effort (org.gnome.Snapshot). The cloud-init log records
SNAPSHOT-FLATPAK-OK / SNAPSHOT-FLATPAK-MISSING markers (best-effort — a
Flathub blip never sinks the build).
Firefox is not installed on either distro. snap-store is installed on both distros:
Firefox added nothing the curated desktop did not already have (Epiphany is the default browser and Chrome is installed as the alternative), and on Ubuntu the apt firefox package is only a snap shim. Removing it is not a one-word template edit: linux_vm-installed VMs boot from a ubuntu-desktop-minimal meta that Recommends firefox, so the templates also purge firefox* + snap remove firefox in post_runcmd and the Ubuntu verify gate fails the build if it reappears. Gentoo simply drops the atom and asserts its absence.
App Center (snap-store) on Gentoo runs against a small PackageKit stub. App Center's Manage tab asks for the snap list and, through PackageKit, for native packages. Gentoo has no PackageKit, so without a stub the tab shows "Something went wrong". templates/gentoo.j2 installs /usr/local/bin/packagekit-stub.py, a D-Bus-activated org.freedesktop.PackageKit service (packagekit-stub.service) that reports no native packages and no updates, and connects snap-store:packagekit-control (marker SNAP-STORE-PK-OK/-FAIL). Result: on Gentoo, Manage lists and updates snaps only; Portage packages are managed with emerge as usual.
Not installed. Adobe has shipped no Linux Reader,
Flathub's community com.adobe.Reader wrapper is x86_64-only and
unmaintained, and the native PDF viewer (Papers / Evince) is installed
on every distro anyway.
The installer targets the same user-facing GNOME desktop everywhere, but distro package managers name the underlying packages differently. The table below is the canonical legend for checking package naming.
Columns are grouped by package-manager family because within a family
the package name is almost always identical (Ubuntu uses apt; Gentoo uses
portage category/name atoms). Exceptions are footnoted.
| Capability | apt (Ubuntu) | portage (Gentoo) |
|---|---|---|
| GNOME desktop meta | ubuntu-desktop-minimal |
gnome-base/gnome |
| Display manager | gdm3 |
gnome-base/gdm |
| GNOME Tweaks | gnome-tweaks |
gnome-extra/gnome-tweaks |
| GNOME Software | gnome-software |
gnome-extra/gnome-software (flatpak via USE) |
| Console (terminal) | gnome-console (transitive via ubuntu-desktop-minimal) |
gui-apps/gnome-console |
| Text editor | gnome-text-editor |
app-editors/gnome-text-editor |
| Camera (Snapshot) | gnome-snapshot |
(Flathub org.gnome.Snapshot — not in tree) |
| Sound recorder | gnome-sound-recorder |
media-sound/gnome-sound-recorder |
| Sound theme (event sounds) | yaru-theme-sound |
x11-themes/sound-theme-freedesktop |
| Archive manager (File Roller) | file-roller |
app-arch/file-roller |
| Contacts | gnome-contacts |
gnome-extra/gnome-contacts |
| Color emoji font | fonts-noto-color-emoji |
media-fonts/noto-emoji |
| Clocks (alarms, world clock) | gnome-clocks |
gnome-extra/gnome-clocks (~arm64 unmasked) |
| Mail + calendar + contacts (Evolution) | evolution |
mail-client/evolution |
| Desktop icons (Ding) | gnome-shell-ubuntu-extensions (ships ding@rastersoft.com) |
gnome-extra/gnome-shell-extension-desktop-icons-ng (KEYWORDS="amd64 x86" only → **-unmasked) |
| PDF viewer (Papers) ² | papers |
app-text/papers |
| Image viewer | loupe |
media-gfx/loupe (**-unmasked; KEYWORDS="~amd64" only) |
| Video player (Totem) | totem |
media-video/totem |
| Mail (Geary) | geary |
mail-client/geary |
| Weather | gnome-weather |
gnome-extra/gnome-weather |
| Web browser (Epiphany) | epiphany-browser |
www-client/epiphany |
| GNOME Bluetooth UI | gnome-bluetooth (transitive via ubuntu-desktop-minimal) |
net-wireless/gnome-bluetooth |
| GNOME Extensions GUI | shipped in gnome-shell (26.04+; standalone gnome-extensions-app removed from the archive); extension packs via gnome-shell-extensions |
gnome-extra/gnome-shell-extensions |
| Bluetooth daemon | bluez |
net-wireless/bluez |
| GVFS backends (MTP / gphoto2) | gvfs-backends (umbrella) |
gnome-base/gvfs (umbrella; mtp USE) |
| Mesa demos (glxgears, glxinfo, eglinfo) | mesa-utils (pulls mesa-utils-bin, which ships es2gears_wayland + eglgears_wayland) |
x11-apps/mesa-progs + eglinfo/es2gears/eglgears built from source (see next row) |
| GL benchmark | glmark2-es2-wayland + glmark2-wayland (both apt binpkgs from the glmark2 source package; data in glmark2-data) |
no ebuild in the tree — upstream glmark2 is cloned and built from source into /usr/local/bin/{glmark2,glmark2-es2,glmark2-wayland,glmark2-es2-wayland} (+ data tree under /usr/local/share/glmark2) by the GLTOOLS step. No extra packages are emerged: for the wayland-gl,wayland-glesv2,x11-gl,x11-glesv2 flavors, meson.build declares only wayland-client/cursor/egl, wayland-protocols ≥ 1.12, wayland-scanner, x11, libjpeg and libpng — all already in the GNOME stack. (An earlier revision tried to emerge x11-libs/glfw, dev-libs/fribidi and x11-libs/libdrm; that category does not exist, so the emerge aborted and glmark2 was never built.) Best-effort (GLMARK2-OK / GLMARK2-SKIP markers); the verify block warns but does not fail on it. gl2mark (the old name) exists in neither the mesa tree nor mesa/demos any more — it was retired upstream. |
| Wayland GLES/OpenGL render test | via mesa-utils-bin — es2gears_wayland |
built from source into /usr/local/bin/{es2gears,eglgears} by the GLTOOLS step. Gentoo has no packaged route: media-libs/mesa has no demos USE flag and the mesa fork tree ships no in-tree demos/, so templates/gentoo.j2 clones gitlab.freedesktop.org/mesa/demos (the same clone that provides eglinfo) and builds them with -Dwayland=enabled. Upstream names them without a _wayland suffix — they are EGLUT-based and auto-detect X11 vs Wayland at runtime; check-virgl.sh probes es2gears_wayland, es2gears, eglgears_wayland, eglgears. |
| Vulkan tools (vulkaninfo, vkcube) | vulkan-tools |
dev-util/vulkan-tools (vulkaninfo only — cube USE is masked on arm64, so vkcube is built from upstream source during install) |
| Vulkan loader + drivers | mesa-vulkan-drivers (loader libvulkan1 comes as its dependency) |
media-libs/vulkan-loader + media-libs/mesa |
| PipeWire | pipewire + pipewire-pulse |
media-video/pipewire (pulseaudio USE provides pipewire-pulse) |
| ALSA plugin | pipewire-alsa |
alsa USE on media-video/pipewire + media-plugins/alsa-plugins[pipewire] |
| JACK plugin | pipewire-jack |
jack USE on media-video/pipewire |
| WirePlumber | wireplumber |
media-video/wireplumber |
| rtkit | rtkit |
sys-auth/rtkit |
| Python pip ³ | python3-pip (+ python3-venv) |
dev-python/pip |
| NetworkManager GUI (systray + connection editor) | network-manager-gnome (transitive via ubuntu-desktop-minimal) |
gnome-extra/nm-applet (upstream network-manager-applet — there is no net-misc/networkmanager-gnome in the tree; an early revision tried that atom and shipped no GUI at all, because its failure was swallowed by ` |
| Fira Code font | fonts-firacode |
media-fonts/fira-code |
| fastfetch | fastfetch |
app-misc/fastfetch |
| lsb-release | lsb-release |
sys-apps/lsb-release |
| net-tools (ifconfig) | net-tools |
sys-apps/net-tools |
| usbutils (lsusb) | usbutils |
sys-apps/usbutils |
| rclone | rclone |
net-misc/rclone |
| Google Chrome | google-chrome-stable |
www-client/google-chrome |
| Flatpak runtime | flatpak |
sys-apps/flatpak |
| Snap runtime (snapd) | snapd |
app-containers/snapd + sys-fs/squashfuse |
| Flatseal (Flathub) | com.github.tchx84.Flatseal |
com.github.tchx84.Flatseal |
| Gear Lever (Flathub) | it.mijorus.gearlever |
it.mijorus.gearlever |
| GNOME backgrounds | gnome-backgrounds (transitive via ubuntu-desktop-minimal) |
x11-themes/gnome-backgrounds |
| Icon theme (Adwaita) | adwaita-icon-theme (transitive via ubuntu-desktop-minimal) |
x11-themes/adwaita-icon-theme |
| GTK themes (standard) | gnome-themes-extra |
x11-themes/gnome-themes-standard |
| Mesa userspace GL stack | (pulled in by desktop meta) | (pulled in by gnome-base/gnome) |
² Both distros now install the papers package; Ubuntu retired the GNOME-47-era evince name in this release.
³ Ubuntu installs python3-venv explicitly alongside python3-pip for consistency. On Gentoo, venv is part of the Python base package.
⁴ Best-effort vendor/third-party installs — Google Chrome and the Flathub apps are best-effort: a vendor-repo or network blip must never sink the build. The guest's cloud-init log records CHROME-OK / CHROME-MISSING and FLATPAK-APPS-OK / FLATPAK-APPS-MISSING markers (each tested against the install command's real exit code — the old | tail -3 || echo FAIL pattern masked failures). On Ubuntu, Chrome is ALSO in the simulate dry-run list — its vendor repo is registered in bootcmd, which runs in simulate mode too — so a Google repo or arch regression surfaces at the simulate gate instead of as a marker in a multi-hour build. On Gentoo the arm64 .deb is fetched from dl.google.com (upstream ships no arm64 binpkg, so --getbinpkgonly can never work), the EULA is accepted via package.license (www-client/google-chrome google-chrome — the google-chrome license sits in the EULA group, NOT @BINARY-REDISTRIBUTABLE), and the emerge runs with --nodeps so it can never merge stock media-libs/mesa over the in-guest mesa-fork install.
| File | Purpose |
|---|---|
setup_vm.py |
Thin shim — delegates to linux_vm/ package (backwards-compat entry point) |
linux_vm/ |
Core package: orchestrator, QEMU launcher, download, templates, monitor |
scripts/build-fleet-sequential.py |
Sequential multi-VM builder (see ARCHITECTURE.md) |
templates/_base.j2 |
Master cloud-init template (Jinja2 inheritance root) |
templates/ubuntu.j2 |
Ubuntu LTS (extends _base.j2 directly; no family template) |
templates/_write_files_common.j2 |
Shared /etc/issue + check-vm diagnostic (included by _base.j2) |
templates/_runcmd_common.j2 |
Shared display manager / vmtools / PipeWire / AccountsService runcmd (included by _base.j2) |
templates/_dconf_common.j2 |
Shared GNOME dconf defaults (included by all family templates) |
templates/_gs_extensions_common.j2 |
Shared GNOME Shell extension install (dash-to-dock: host-served zip, GitHub fallback, shell-version gate) |
templates/_macros.j2 |
Reusable Jinja2 macros for the cloud-init verify gates (VERIFY-OK marker) |
templates/_plymouth_common.j2 |
Shared Plymouth boot-splash setup (theme + grub/initrd regen; included in post_runcmd) |
templates/_app_platforms_common.j2 |
Shared vendor-app platform installs (Google Chrome, Flathub Flatseal/Gear Lever, PowerShell) |
templates/network-config.j2 |
Netplan YAML for DHCP on e* interfaces |
templates/gentoo.j2 |
Gentoo (extends _base.j2 directly) |
templates/meta-data.j2 |
cloud-init meta-data (per-VM identity) |
scripts/lint-templates.py |
Template linter (see ARCHITECTURE.md) |
scripts/smoke-test-cli.py |
CLI contract smoke test (see ARCHITECTURE.md) |
scripts/audit-packages.py |
Cross-distro package alignment audit (see ARCHITECTURE.md) |
scripts/lint-python.py |
pylint gate: whole tree, or --changed-since <ref> for CI (see ARCHITECTURE.md) |
scripts/run-tests.py |
Unit-test gate (Gate 0d): unittest discover over tests/ — template logic plus the fleet control-flow tests |
scripts/check-virgl.sh |
Validates VirGL (hardware GL) in a booted VM |
scripts/check-venus.sh |
Validates Venus (hardware Vulkan) in a booted VM |
linux_vm/venv_bootstrap.py |
Re-execs the gate scripts into the repo .venv exactly once |
docs/CONTRIBUTING.md |
Contributor guide |
requirements.txt |
Host + CI Python dependencies (install into the project .venv; linux_vm/host.py only checks they are importable and never installs anything) |
The templates directory uses Jinja2 template inheritance to deduplicate common cloud-init config. The hierarchy is:
flowchart TB
base["_base.j2"]
ubuntu["ubuntu.j2"]
gentoo["gentoo.j2"]
base --> ubuntu
base --> gentoo
Both distro templates extend _base.j2 directly (no family template). See ARCHITECTURE.md for the full diagram.
Quick notes:
- Host: Apple Silicon Mac only (HVF; Intel Macs unsupported).
- QEMU: the
milesbuckton/qemu-virgltap is required (it also providesqemu-img); stock Homebrewqemuis never used (see table below). - Guest images are fetched automatically: Ubuntu from
https://cloud-images.ubuntu.com/(release found viahttps://changelogs.ubuntu.com/meta-release-lts, verified againstSHA256SUMS); Gentoo fromhttps://distfiles.gentoo.org/releases/arm64/autobuilds/current-di-arm64-cloudinit/(verified against the image's.sha256). - Networking: QEMU user-mode networking (SSH forwarded on
127.0.0.1);-netdev vmnet-*is not used because it needs sudo / thecom.apple.vm.networkingentitlement. - Debugging a QEMU crash:
--startcaptures QEMU's stderr in<target_dir>/qemu-stderr.log; for a VM you launch by hand, rerunbash launch-vm.sh 2> qemu-stderr.log(add-d guest_errors -D <file>for guest errors) — see AGENTS.md.
You install QEMU yourself — the script
detects it and refuses to start
if it can't find a virgl-enabled qemu-system-aarch64 (the error names the
paths it searched and the qemu-virgl install command).
QEMU is open source, no registration required, no commercial gate.
You need the system emulator (qemu-system-aarch64 on Apple Silicon),
qemu-img, and the OVMF firmware blobs for UEFI boot.
| Host | Install command |
|---|---|
| macOS (Apple Silicon) | Stock Homebrew qemu is not supported and never used (no virglrenderer; a non-virgl qemu-system-aarch64 exits 3) — install qemu-virgl (next row). HVF acceleration is built into macOS — no extra step. |
| macOS (hardware GL) | Required: brew tap milesbuckton/qemu-virgl && brew install milesbuckton/qemu-virgl/qemu-virgl (a non-virgl QEMU is rejected, exit 3). QEMU (currently 11.1.90) with virglrenderer + ANGLE/Metal. Prebuilt Apple Silicon bottles (arm64_golden_gate, macOS 27 only) are published as GitHub Release assets and poured by Homebrew — no source build; from-source builds (full Xcode) only if no bottle matches. Verified working on this project's Apple Silicon MacBook Pro host. The launcher auto-detects the GL device (virtio-vga-gl, else virtio-gpu-gl-pci), uses -display cocoa,gl=es, and enables Venus (guest Vulkan over virtio) via the host's MoltenVK ICD (or KosmicKrisp, see Host Vulkan driver); if the cocoa GL probe fails it falls back to a non-GL GPU and the guest renders GL with Mesa llvmpipe (software) and Vulkan with Lavapipe. The formula is keg-only (this build needs kernel-irqchip=off, which the launcher sets). Linking is optional: setup_vm.py (detect_tools) probes ~/VMs/qemu-system-aarch64-gl, then /opt/homebrew/opt/qemu-virgl/bin/qemu-system-aarch64, then /opt/homebrew/bin (then /usr/local/bin, /opt/local/bin), uses the first that exists (refusing it, exit 3, if it is not virgl-enabled), finds firmware next to that binary, and writes its absolute path into the launcher. With qemu-virgl installed, a stock qemu owning the /opt/homebrew/bin link is therefore never reached. macOS-virgl is not yet in upstream QEMU, so a virgl build can never be the absolute latest QEMU. |
qemu-img must come from qemu-virgl, which ships it but is keg-only, so it
is not on PATH. The script uses, in order:
/opt/homebrew/opt/qemu-virgl/bin/qemu-img; a qemu-img next to the
detected virgl qemu-system-aarch64 (symlinks resolved, so a custom GL build
dir works); then qemu-img on PATH only if it resolves into a
Cellar/qemu-virgl keg. A stock qemu qemu-img is never used and nothing
is auto-installed: with no match the build exits 4 with the hint
brew tap milesbuckton/qemu-virgl && brew install qemu-virgl.
The default VM uses half the host's physical CPU cores (clamped to 2-8)
for vCPUs — 8 on an 18-core Apple Silicon MacBook Pro, 2 on a 4-core Apple Silicon Mac — plus half the
host's RAM (clamped 8-32 GB) — 24 GB on a 48 GB Mac — and 80 GB disk (tune via --vcpus / --memory-mb / --disk-gb). Halving
leaves the other half of the cores free for the host and other apps: a
full-core VM on a small busy host starves the guest vCPUs — the guest
kernel soft-locks and cloud-init stalls. For the fastest, most reliable fleet
runs, keep the machine otherwise idle.
# Default: Ubuntu LTS, vCPU = half your host's cores (clamped 2-8), RAM = half host memory (clamped 8-32 GB), 80 GB disk, user password = username (see install-info.txt)
python setup_vm.py
# Or pick any distro explicitly:
python setup_vm.py --distro ubuntu-lts # Ubuntu LTS -- default
# Several VMs at once? Each launcher picks the first free port in 2222-2321
# when it starts (a build without --start binds nothing). Pin ports for
# stable SSH commands and to avoid a race between launchers starting together:
python setup_vm.py --ssh-port 2222 --target-dir ~/VMs/q1 &
python setup_vm.py --ssh-port 2224 --target-dir ~/VMs/q2 &
# Custom settings (defaults: vCPU = half your host's cores / RAM = half host memory clamped 8-32 GB / 80 GB disk)
python setup_vm.py \
--distro ubuntu-lts \
--target-dir ~/VMs/my-vm \
--hostname my-ubuntu \
--username alex \
--vcpus 4 \
--memory-mb 8192 \
--disk-gb 80
# Gentoo instead of Ubuntu (default is build-only; add --start to boot it)
python setup_vm.py --distro gentoo
# Venus on KosmicKrisp instead of MoltenVK (macOS 26+; installed with qemu-virgl)
python setup_vm.py --host-vulkan-driver kosmickrisp --startRun python setup_vm.py --help to see all options. Less common ones:
--cache-dir (shared image cache, default ~/VMs/cache), --vm-name
(display name), --timezone (IANA zone; default = host's), --keep-qcow2
(keep the downloaded cloud image after conversion), --prefetch (download
the image into the cache and exit), --simulate (render user-data in
simulate mode: a package-resolver dry run instead of the full install).
setup_vm.py exit codes: 0 success; 2 unsupported host or invalid
argument; 3 no virgl-enabled QEMU; 4 no qemu-img from qemu-virgl; 5 missing
Python dependency or template; 6 no disk image in the downloaded archive;
7 could not write install-info.txt; 8 disk refused or failed (exists
without --force, VM still running, conversion error) or QEMU failed to
start; 9 cloud-image discovery failed.
Venus forwards the guest's Vulkan calls to a Vulkan driver on the host, and macOS has none of its own, so one is layered on Metal:
| MoltenVK (default) | KosmicKrisp | |
|---|---|---|
| What | Khronos translation layer, Vulkan → Metal | Mesa Vulkan driver (LunarG) built on Metal 4 |
| Conformance | Vulkan 1.4 portability subset | Vulkan 1.3 conformant (no portability subset) |
| Host requirement | any supported macOS | macOS 26+ (Metal 4) |
| Maturity | years of production use | new; fewer extensions, faster-moving |
| Install | pulled in by qemu-virgl |
pulled in by qemu-virgl on macOS 26+ — bottle on macOS 27 (arm64_golden_gate); elsewhere it builds from source (needs LLVM + full Xcode); never installed on older macOS |
Selecting kosmickrisp when it is not installed aborts the build with a
FileNotFoundError naming the brew install command.
--host-vulkan-driver moltenvk|kosmickrisp (default moltenvk)
selects it; the launcher exports VK_DRIVER_FILES and VK_ICD_FILENAMES
pointing at that driver's ICD manifest. scripts/build-fleet-sequential.py
accepts the same flag. MoltenVK stays the default because it is the tested
path; KosmicKrisp is worth trying when a guest app trips over the portability
subset. If one misbehaves, rebuild the launcher with the other.
To build all distros at once, see ARCHITECTURE.md.
Fleet builder warning:
scripts/build-fleet-sequential.pybuilds into~/VMs/<distro>with--force, overwriting any hand-built VM disk there, and its preflight force-kills (SIGKILL) everyqemu-systemprocess whose command line references~/VMs. Shut down VMs you care about (or keep them outside~/VMs) before running it.
| OS | Default --target-dir |
|---|---|
| macOS | ~/VMs/<distro> |
The default is the bare distro name — QEMU is the only supported hypervisor.
Two accounts are created on every VM:
| Account | Default password | Notes |
|---|---|---|
Primary user (matches --username, default = distro-specific user) |
the username itself | The account you log into GDM / Wayland with. Passwordless sudo (cloud-init NOPASSWD:ALL rule), plus the wheel (or sudo) group. |
root |
root |
Set by cloud-init for console emergency access. SSH password login as root is refused by sshd's default PermitRootLogin prohibit-password. |
Override the primary-user password with --password X, LINUX_VM_PASSWORD=..., or --password-stdin (stdin/env avoid exposing it in process listings or shell history). Whatever
passwords end up in use are recorded — and only recorded — in
<target-dir>/install-info.txt (chmod 600). It is the single place to
look for login credentials after a build; the terminal prints them once
in the "Setup complete" summary, and only when stdout is a TTY (so they
never land in captured build logs).
Predictable credentials are safe here because the host SSH forward is loopback-only (never exposed on the LAN) — see GPU & display. If you ever change the launcher to bind the forward on a non-loopback address, regenerate with a stronger password first.
| Ubuntu LTS | Gentoo | |
|---|---|---|
| Release model | 2-year cadence, 5-year support | Rolling |
| GNOME freshness | Stable | Latest (from upstream ebuilds) |
| Default user | ubuntu |
gentoo |
| Sudo group | sudo |
wheel |
| Cloud sync CLI | rclone |
rclone |
| Firmware | UEFI | UEFI |
| First-boot time (Phase 2, latest run) | 48.0 min | 185.1 min (binhost + source builds) |
Ubuntu LTS is the stability track with 5 years of patches — the default Ubuntu target.
When cloud-init finishes, GDM is already running on the first boot (no
reboot). You'll see the GDM login screen — sign in with the username and password from install-info.txt.
echo $XDG_SESSION_TYPE # should print: wayland
gnome-shell --version # latest GNOME for the chosen distroThe VM boots once. Cloud-init installs GNOME, configures services and
starts GDM (systemctl enable --now) on that same boot; it does not
reboot (power_state is deliberately omitted). The fleet builder then
powers the VM off over SSH after VERIFY-OK; run sudo systemctl reboot
yourself if you want the freshly installed kernel.
Don't run the distro's package manager manually during the first boot.
Cloud-init is already running it, and a concurrent apt/emerge
will hit a database lock. If you've logged into the console while
cloud-init is still going, just wait — GDM comes up when it's done.
sudo cloud-init status
# status: running -> still installing, wait
# status: done -> finished, GDM is up
# status: error -> something failed; see logsTo block until done:
sudo cloud-init status --waitWhen you run the unattended build with scripts/build-fleet-sequential.py,
the host-side orchestrator waits a bounded time
for cloud-init to finish — it does not wait forever, and the bound is
per-distro because Gentoo installs far more from source:
| Distro | Guest install-wait loop | Host cloud-init cap |
|---|---|---|
| Ubuntu (apt) | — | 180 min (3 h) |
| Gentoo | 420 min (7 h) | 480 min (8 h) |
The guest cap is deliberately smaller than the host cap: the orchestrator's
timer starts at boot and must still cover the desktop setup steps that run
after the install loop finishes (GDM, dconf, app platforms, snaps, the
verify checks that print VERIFY-OK). If a build hits the bound it reports a
failure and shuts the VM down — Gentoo's slow end is arm64 source builds
landing cold (webkit-gtk, papers Rust, snapd Go, mesa), not a defect, so a
time-out on a heavily loaded host is often just a slow-but-healthy install.
For more detail:
sudo cloud-init analyze show # phase-by-phase timing
sudo journalctl -u cloud-init-final --no-pager | tail -30
sudo tail -f /var/log/cloud-init-output.log # follow liveEach user-data template writes a marker file as its very last runcmd step:
| Distro | Marker path |
|---|---|
| Ubuntu LTS | /var/log/ubuntu-lts-vm-setup.log |
| Gentoo | /var/log/gentoo-vm-setup.log |
ls -l /var/log/*-vm-setup.log
cat /var/log/*-vm-setup.log
# Expected: cloud-init first-boot finished at: YYYY-MM-DD...Every VM gets /usr/local/bin/check-vm. Run it as soon as you see the
login prompt:
check-vmOutput covers:
- cloud-init status and per-module exit codes
- Whether the marker file exists (runcmd completed)
- Network interfaces, DNS, connectivity
- Display manager state and default systemd target
- Package manager state
- IP and SSH command
- Errors in both cloud-init logs
The same IP + SSH line is also baked into /etc/issue, so it shows
above every console login prompt.
cloud-init never finishes:
First boot does a full system upgrade plus desktop install (allow up to
~53 min on Ubuntu and up to ~4.4 h on Gentoo on an idle host; slower
networks and host load may add more). SSH is enabled — from the host,
ssh -p <port> user@127.0.0.1 (user-mode networking: the guest IP is not
reachable from the host) — and tail
/var/log/cloud-init-output.log to watch progress. Or run
setup_vm.py monitor <target_dir> for a phase-based progress bar.
Vulkan: which driver does the guest get?
- QEMU (virtio-gpu): The qemu-virgl build has Venus (Vulkan-over-virtio); with a working host Vulkan ICD (MoltenVK by default, or KosmicKrisp), the guest gets hardware-accelerated Vulkan. The launcher exports
VK_DRIVER_FILESandVK_ICD_FILENAMESpointing at the MoltenVK or KosmicKrisp ICD manifest automatically. Software (Lavapipe, CPU-side Vulkan via LLVM JIT) only if the cocoa GL probe fails and the launcher falls back to a non-GL GPU.
QEMU window opens small (640×480 text mode): Expected for the first ~60 seconds of boot — text-mode VGA happens before the virtio-gpu kernel driver loads. Once GDM starts, the resolution follows the QEMU window size.
QEMU: no cocoa window appears (headless):
The generated launch-vm.sh opens a cocoa window by default — with
-display cocoa,gl=es + a GL device (virtio-gpu-gl-pci)
on a virgl QEMU build, or plain -display cocoa + virtio-gpu-pci otherwise. If you need headless operation (e.g. for CI /
fleet runs), edit the launcher to swap:
-display cocoa,gl=es(or-display cocoa) →-display none- the GL device (if present) → its non-GL sibling (
virtio-gpu-gl-pci→virtio-gpu-pci), and strip,venus=on,blob=on,hostmem=4Gfrom its-devicevalue; the GL-capable device needs a GL display backend, so it must be dropped with-display none
Guest microphone records silence (or no input device):
The guest gets a virtio-snd capture stream (streams=2) fed from the macOS
default input device (a mono mic is mapped to stereo). Two host
requirements:
- QEMU must be a
qemu-virglwith the fork's CoreAudio input support (November 2026 or later; runbrew update && brew upgrade qemu-virgl). An older build plays audio fine but logsvirtio-sound.in"no host audio driver" retries and the mic stays dead. - macOS grants microphone access to the app that launched QEMU (your terminal, e.g. Terminal/iTerm/Ghostty), not to QEMU. Grant it in System Settings → Privacy & Security → Microphone, then restart the VM from that terminal. A VM started from something without mic access (e.g. a background job/launchd agent) gets silence, with no error.
In the guest, wpctl status (or pactl list short sources) should list
an alsa_input… source; the build's first boot logs an AUDIO-IN-OK /
AUDIO-IN-WARN line in /var/log/cloud-init-output.log (warn-only).
SPICE clipboard / USB redirection not available (QEMU):
A -spice server is intentionally not attached. QEMU rejects -spice
alongside a GL display context — -spice + -display cocoa,gl=es aborts
with "Display spice is incompatible with the GL context" (upstream QEMU
constraint: SPICE would never receive display updates once GL owns the
framebuffer, qemu/qemu#1036). The GL display is what makes the virgl
hardware-rendering path work, so the SPICE server lost the trade-off. The
spice-vdagent channel is only added when the QEMU build supports the
spicevmc chardev; the qemu-virgl tap build does not, so with it there is
no vdagent channel (no shared clipboard or auto-resize).
Concurrent QEMU VMs: SSH-forward port unclear or clashing:
Each generated launcher picks the first free host port in 2222-2321 at the
moment it starts (builds without --start bind nothing), so the port can
change between launches, and two launchers starting together can race for
the same port. Pass --ssh-port N to each build for a stable port:
python setup_vm.py --ssh-port 2222 --target-dir ~/VMs/q1 &
python setup_vm.py --ssh-port 2224 --target-dir ~/VMs/q2 &
python setup_vm.py --ssh-port 2226 --target-dir ~/VMs/q3 &Discovery failed: The mirrors / changelogs server is the source of truth. Re-run when network issues clear.
Once the VM is up and you've logged into GDM, the script's job is done — but here are the workflows you'll typically want.
python setup_vm.py monitor ~/VMs/ubuntu-lts # live phase bar, 5-sec refresh
python setup_vm.py monitor ~/VMs/ubuntu-lts --once # snapshot, exitFor live-tail mode (streams every package-manager line via SSH):
python setup_vm.py monitor ~/VMs/ubuntu-lts --tailTail mode requires paramiko (already in requirements.txt) and the per-VM
ssh_key file that the build generates automatically.
- QEMU:
ssh -p 2222 user@127.0.0.1(or whatever port was assigned; printed in the build output). The host forward is loopback-only by design — never accessible from the LAN — so you must SSH to127.0.0.1, not the Mac's LAN IP. Only change the bind inlaunch-vm.shif you understand the exposure.
Two ways to authenticate:
- Password — whatever's in
<target-dir>/install-info.txt. - Per-VM SSH key —
<target-dir>/ssh_key(ed25519, generated at build time). Works as soon as sshd starts inside the guest:ssh -i ~/VMs/ubuntu-lts/ssh_key -p 2222 ubuntu@127.0.0.1
Snapshot the VM before invasive changes; restore in seconds if something
breaks. Use qemu-virgl's qemu-img
(/opt/homebrew/opt/qemu-virgl/bin/qemu-img; it is keg-only, so not on
PATH unless linked).
| Take snapshot | Restore | List |
|---|---|---|
qemu-img snapshot -c <name> disk.qcow2 (VM must be off) |
qemu-img snapshot -a <name> disk.qcow2 |
qemu-img snapshot -l disk.qcow2 |
| Soft shutdown (ACPI) | Force off | Start |
|---|---|---|
Use the QEMU window's Machine → Power Down menu, or system_powerdown in QEMU monitor |
Close the window / kill the qemu process | Re-run the generated launch-vm.sh |
To fully delete a VM and reclaim disk:
rm -rf ~/VMs/ubuntu-lts # QEMU- The cloud image is cached in
~/VMs/cache/<distro>/(--cache-dirto change) and reused while its SHA256 still matches upstream. Ubuntu'scurrent/image keeps the same filename, so a new upstream build fails the hash check and is re-downloaded; Gentoo's timestamped filename changes with each release. - An existing QEMU disk (qcow2) is never overwritten by default: the build stops immediately, before any download, and asks for
--force. With--forcethe disk is rebuilt from the cloud image (all guest data is lost); the VM must be shut down first, or the build refuses. - The seed ISO + VM definition file are always regenerated.
Delete the target directory for a clean re-install.
- ARCHITECTURE.md — internal flow, latest-version discovery, pre-flight gates, timing data, fleet building
- AGENTS.md — maintainer guide, conventions, gotchas
Provided as-is. Adapt the templates and orchestrator to your needs.