cloudhost

Start the required operating system with its distribution-specific launcher:

./run-debian13.py
./run-almalinux10.py
./run-fedora44.py
./run-ubuntu2604.py
./run-windows11.py

All virtual machines use OVMF/UEFI firmware. Each launcher creates a private, persistent OVMF_VARS_4M.fd variable store in the VM state directory.

Closing the QEMU window stops a foreground VM. To keep the launcher in the background while still showing the graphical window:

./run-debian13.py --daemon

The launcher uses KVM when /dev/kvm is accessible, forwards host port 2222 to guest port 22, and creates .vm/debian13/disk.qcow2 as a 20G writable overlay with the original qcow2 image as its backing file. The base image therefore stays unchanged. Run ./run-debian13.py --help for the supported environment variables.

The Debian VM hardware (8G memory, 8 CPUs, drives, network) is defined in the QEMU config file qemu/debian13.ini; the machine type and architecture-specific devices are in qemu/debian13-<os>-<arch>.ini (os linux or darwin, arch amd64 or arm64), together with the accelerators. Edit these files to change the settings. The launcher fills in the ${...} file path placeholders of qemu/debian13.ini, writes the result to .vm/debian13/qemu.ini and starts QEMU with -readconfig for that file followed by the one for the host system and guest architecture. QEMU arguments given after -- override the config files, for example ./run-debian13.py -- -m 4G -smp 4.

The launchers accept --state-dir DIR to keep the VM disk, seed ISO, UEFI variables, PID file and console log in DIR instead of the default .vm/<name>/. The option takes precedence over the corresponding *_STATE_DIR environment variable:

./run-debian13.py --state-dir /srv/vms/debian13-test --daemon

With --download-only, a launcher only downloads the media it would fetch automatically and then exits without creating a VM disk or starting QEMU: the base image for Debian, AlmaLinux, Fedora and Ubuntu, and the VirtIO tools ISO for Windows 11 (whose installation ISO and base QCOW2 are supplied manually):

./run-fedora44.py --download-only

If .vm/debian13/seed.iso is missing, the launcher automatically builds it from seediso/debian13/user-data, seediso/debian13/meta-data, and seediso/debian13/network-config before starting the VM.

Image download URLs and implementation are maintained in the vm-images submodule. Clone this repository with its submodules, or initialize it later:

git submodule update --init --recursive

The launchers prefer vm-images/download-images.sh when the submodule is initialized. Otherwise, they fall back to ../vm-images/download-images.sh for compatibility with the previous sibling-repository layout. Set VM_IMAGE_HELPER to use another helper path explicitly.

If the Debian base image is missing, the launcher calls the selected image helper with debian13.

AlmaLinux 10

Start an AlmaLinux 10 Generic Cloud VM with:

./run-almalinux10.py

When the shared AlmaLinux image is missing, the launcher calls the selected image helper with almalinux10. It creates the writable overlay .vm/almalinux10/disk.qcow2 and uses the NoCloud configuration in seediso/almalinux10/. SSH is forwarded to host port 2223 by default:

ssh -p 2223 guofang@localhost

AlmaLinux settings use the ALMA_VM_ prefix. For example:

ALMA_VM_MEMORY=4G ALMA_VM_CPUS=4 ALMA_VM_SSH_PORT=2224 ./run-almalinux10.py

Run ./run-almalinux10.py --help for all supported settings. The seed ISO is stored alongside the VM disk at .vm/almalinux10/seed.iso. If it already exists after editing its source files, rebuild it explicitly with ./seediso/almalinux10/build-seed.sh .vm/almalinux10/seed.iso.

Fedora 44

Start a Fedora 44 Cloud Base VM with:

./run-fedora44.py

The launcher downloads the fedora44 image through the shared helper when it is missing, creates .vm/fedora44/disk.qcow2, and builds its NoCloud seed from seediso/fedora44/. SSH is forwarded to host port 2224 by default:

ssh -p 2224 guofang@localhost

On the first boot, cloud-init updates package metadata and installs Fedora's GNOME package group through its native package module, then reboots the guest. Keep the VM running until this initial installation and reboot have completed.

Like the Debian VM, the Fedora VM hardware (8G memory, 8 CPUs, drives, SSH port 2224) is defined in qemu/fedora44.ini, with the accelerators, machine type and platform-specific devices in qemu/fedora44-<os>-<arch>.ini. Other Fedora settings use the FEDORA_VM_ prefix. Run ./run-fedora44.py --help for the complete list of overrides.

Ubuntu 26.04

Start an Ubuntu 26.04 LTS (Resolute Raccoon) cloud image VM with:

./run-ubuntu2604.py

The launcher downloads the ubuntu2604 image through the shared helper when it is missing, creates .vm/ubuntu2604/disk.qcow2, and builds its NoCloud seed from seediso/ubuntu2604/. Like the Debian seed, it injects the current user's SSH public key and points APT at the USTC mirror (ubuntu-ports on arm64). SSH is forwarded to host port 2225 by default:

ssh -p 2225 guofang@localhost

On the first boot, cloud-init installs ubuntu-desktop-minimal (GNOME) and ibus-table-wubi, makes the graphical target the default and reboots the guest. Keep the VM running until this initial installation and reboot have completed.

The VM hardware (8G memory, 8 CPUs, drives, SSH port 2225) is defined in qemu/ubuntu2604.ini, with the accelerators, machine type and platform-specific devices in qemu/ubuntu2604-<os>-<arch>.ini. Other Ubuntu settings use the UBUNTU_VM_ prefix. Run ./run-ubuntu2604.py --help for the complete list of overrides.

Windows 11 23H2

On first boot, the Windows 11 launcher creates a writable system-disk overlay from the shared Windows 11 QCOW2 base image:

./run-windows11.py

It creates a persistent 64G disk at .vm/windows11/disk.qcow2, automatically partitions it, completes OOBE, creates the local administrator guofang with the initial password wang, and enables Remote Desktop on localhost:3389. During the first login it also silently installs the VirtIO drivers (the guest tools installer on amd64, the Arm64 driver packages from the VirtIO ISO with pnputil on arm64), without which the guest has no network on arm64. The installer includes the VirtIO drivers, SPICE vdagent, and QEMU Guest Agent. The launcher exposes the vdagent channel for host/guest clipboard integration and the QEMU Guest Agent at .vm/windows11/qemu-guest-agent.sock. Change the password after first login. The OpenSSH Server is downloaded through Windows Update, which can be slow, so it is not installed automatically: run 05-Install-OpenSSH-Admin.bat from the Installers folder on the desktop as administrator, then connect with ssh guofang@localhost -p 2222; it also installs the host's configured SSH public key for passwordless administrator login. The Windows VM hardware (8G memory, 8 CPUs, system disk, devices) is defined in qemu/windows11.ini, with the accelerators and machine type in qemu/windows11-<os>-<arch>.ini; the launcher renders the former to .vm/windows11/qemu.ini and loads both with -readconfig. Only the network and the installation media are still set by the launcher. QEMU arguments after -- override the config files, for example ./run-windows11.py -- -m 4G -smp 4. The generated answer-file ISO is stored beside the disk as .vm/windows11/seed.iso.

To install from the Windows ISO instead, use ./run-windows11.py --install-from-iso. This choice only applies while creating a missing system disk; subsequent starts always boot the existing system disk normally. During ISO installation, the launcher resolves its tools ISO through the shared image helper and downloads it when missing. Override the base QCOW2, source ISO, tools ISO, RDP port, or SSH port with the WIN11_VM_ environment variables shown by ./run-windows11.py --help. For example, when the VirtIO ISO is elsewhere:

WIN11_VM_TOOLS_ISO=/custom/path/virtio-win.iso ./run-windows11.py --install-from-iso