Skip to content

About

Unattended Linux VMs with GNOME on Wayland, built under QEMU/HVF on Apple Silicon via Jinja2 cloud-init templates and a seven-gate fleet builder.

Topics

Resources

Contributing

Stars

1 star

Watchers

0 watching

Forks

Repository files navigation

Linux + GNOME on VM — Automated Installer

Pylint

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.

Quick start

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-lts

The 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.

Components

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)

Hypervisor

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:tcg accelerator 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 qemu is never installed or used — not even for qemu-img, which must come from qemu-virgl (exit 4 otherwise). Python dependencies are never installed: run from the project .venv with requirements.txt installed.

Works on macOS hosts (Apple Silicon only — Intel Macs are not supported):

  • Apple Silicon (aarch64 guests — the validated and only supported path): QEMU (HVF)

Guest CPU architecture

Guests run aarch64 on Apple Silicon — the validated and only supported path (the full distro fleet matrix has been built out on aarch64 guests).

Virtual hardware

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.

Supported distros

--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

Guest kernels and GNOME versions

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

Curated GNOME Shell extensions

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.

Apps preinstalled on every VM

Every VM built by this tool gets the same curated set of apps via native packages, visible in the GNOME Software GUI.

Native packages (both distros)

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 ⁴).

Distro branding (wallpaper + lock screen)

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)

GNOME desktop defaults (dconf, both distros)

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.

Distro alignment caveats

The installer aims for the same user-facing GNOME desktop everywhere, but Linux distro release cycles and package naming do not fully align.

Camera and image viewer on Gentoo

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).

Web browser and Snap store

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.

Adobe Reader

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.

Package naming differences

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.

Files

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
Loading

Both distro templates extend _base.j2 directly (no family template). See ARCHITECTURE.md for the full diagram.

Prerequisites

Quick notes:

  • Host: Apple Silicon Mac only (HVF; Intel Macs unsupported).
  • QEMU: the milesbuckton/qemu-virgl tap is required (it also provides qemu-img); stock Homebrew qemu is never used (see table below).
  • Guest images are fetched automatically: Ubuntu from https://cloud-images.ubuntu.com/ (release found via https://changelogs.ubuntu.com/meta-release-lts, verified against SHA256SUMS); Gentoo from https://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 / the com.apple.vm.networking entitlement.
  • Debugging a QEMU crash: --start captures QEMU's stderr in <target_dir>/qemu-stderr.log; for a VM you launch by hand, rerun bash 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 + OVMF

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.

Shared: qemu-img

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.

Host resources (multi-core matters)

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.

Usage

# 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 --start

Run 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.

Host Vulkan driver (MoltenVK or KosmicKrisp)

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.py builds into ~/VMs/<distro> with --force, overwriting any hand-built VM disk there, and its preflight force-kills (SIGKILL) every qemu-system process whose command line references ~/VMs. Shut down VMs you care about (or keep them outside ~/VMs) before running it.

Default target directory

OS Default --target-dir
macOS ~/VMs/<distro>

The default is the bare distro name — QEMU is the only supported hypervisor.

Default credentials

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.

Distro Comparison (in this script's defaults)

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.

Verifying the install

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 distro

First boot — what to expect

The 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.

How to tell whether cloud-init has finished

sudo cloud-init status
# status: running   -> still installing, wait
# status: done      -> finished, GDM is up
# status: error     -> something failed; see logs

To block until done:

sudo cloud-init status --wait

How long the build will wait before giving up

When 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 live

The "ground truth" marker

Each 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...

Built-in diagnostic: check-vm

Every VM gets /usr/local/bin/check-vm. Run it as soon as you see the login prompt:

check-vm

Output 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.

Troubleshooting

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_FILES and VK_ICD_FILENAMES pointing 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=4G from its -device value; 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-virgl with the fork's CoreAudio input support (November 2026 or later; run brew update && brew upgrade qemu-virgl). An older build plays audio fine but logs virtio-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.

Day-2 operations

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.

Watching cloud-init progress

python setup_vm.py monitor ~/VMs/ubuntu-lts        # live phase bar, 5-sec refresh
python setup_vm.py monitor ~/VMs/ubuntu-lts --once # snapshot, exit

For live-tail mode (streams every package-manager line via SSH):

python setup_vm.py monitor ~/VMs/ubuntu-lts --tail

Tail mode requires paramiko (already in requirements.txt) and the per-VM ssh_key file that the build generates automatically.

SSH into a running VM

  • 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 to 127.0.0.1, not the Mac's LAN IP. Only change the bind in launch-vm.sh if you understand the exposure.

Two ways to authenticate:

  1. Password — whatever's in <target-dir>/install-info.txt.
  2. 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

Snapshots

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

Stopping / starting a VM

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

Cleanup

To fully delete a VM and reclaim disk:

rm -rf ~/VMs/ubuntu-lts     # QEMU

Re-running

  • The cloud image is cached in ~/VMs/cache/<distro>/ (--cache-dir to change) and reused while its SHA256 still matches upstream. Ubuntu's current/ 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 --force the 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.

Further reading

  • ARCHITECTURE.md — internal flow, latest-version discovery, pre-flight gates, timing data, fleet building
  • AGENTS.md — maintainer guide, conventions, gotchas

License

Provided as-is. Adapt the templates and orchestrator to your needs.

About

Unattended Linux VMs with GNOME on Wayland, built under QEMU/HVF on Apple Silicon via Jinja2 cloud-init templates and a seven-gate fleet builder.

Topics

Resources

Contributing

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages