Skip to content

Dev VM

Jump to bottom
T-Crypt edited this page Oct 6, 2026 · 1 revision

Dev VM

A disposable machine to run the installer and the desktop stack in: for people who do not want a full desktop on the machine they work on, and for agents that need a clean, repeatable environment. The hypervisor differs per host, but the guest spec is the same everywhere, and a broken install costs one reset rather than a reimage.

The guest spec that works

Setting Value Why it matters
Architecture x86_64 KVM Aphotic targets x86_64
Firmware UEFI (OVMF / edk2) The working guests all boot UEFI
Display VirtIO-GPU Gives the guest /dev/dri/renderD128. Hyprland draws through a render node; without one it will not start
CPU host The guest reports the physical CPU straight through
Cores 6 1 thread per core
RAM 12 GiB The working guests use 12 GiB
Disk 60 GiB Base system plus a full profile install
Network A bridge (or NAT) the host can reach So you can SSH in
Access A guest user plus your SSH key Set during the base install (below)

Two of those decide whether the VM is usable at all. The display must be VirtIO-GPU, or there is no render node and Hyprland will not start. And reach the guest console over SPICE (or the libvirt equivalent), not a web console: Aphotic binds almost everything to SUPER, and web consoles are where the SUPER key tends to get swallowed by the host window manager. The Proxmox Test VM page has the full SPICE setup.

These are the requirements an agent needs to satisfy, on any hypervisor: an x86_64 KVM host, 12 GiB of RAM, 6 vCPUs, 60 GiB of disk, UEFI firmware, a VirtIO-GPU device, a network the host can reach, and a guest user with your SSH key.

Base system: the Arch installer ISO

Arch no longer ships prebuilt cloud images (the opencloud images were retired), so the base system is built from the installer ISO. Every hypervisor flow below is the same four steps:

  1. Create the guest to the spec above, with a blank 60 GiB disk.
  2. Boot the latest Arch ISO, https://geo.mirror.pkgbuild.com/iso/latest/archlinux-x86_64.iso.
  3. In the guest console run archinstall: best-effort layout on the 60 GiB disk (wipe it), one user with sudo, paste your SSH public key into it, add openssh and qemu-guest-agent to the package list, install, reboot.
  4. The guest now boots a plain Arch system. Install Aphotic in it: ./install.sh --profile full --no-assistant, then aphotic doctor.

Step 3 takes a couple of minutes at the wizard. To automate it instead, archinstall --dry-run walks the wizard without writing to disk and saves the answers to a config file; archinstall --config <file> re-runs the same install unattended.

libvirt / QEMU (your own machine)

Free, nothing to install besides the tools, and the path most contributors use. On Arch or an Arch-based system:

sudo pacman -S libvirt virt-viewer

Then create the guest, with the ISO as the boot medium and a blank 60 GiB disk as the install target:

virt-install --name aphotic-devvm \
  --location https://geo.mirror.pkgbuild.com/iso/latest/archlinux-x86_64.iso \
  --import \
  --disk size=60 \
  --cpu host \
  --ram 12288 \
  --vcpus 6 \
  --os-variant arch64 \
  --firmware edk2 \
  --video virtio \
  --graphics spice

Open the SPICE window (or virsh console aphotic-devvm) and run archinstall there: best-effort layout on the 60 GiB disk, a user with sudo, your SSH key, openssh and qemu-guest-agent in the packages. Reboot when it is done. On the default NAT network the guest's address is:

virsh net-dhcp-leases default

Once the base system is installed, install Aphotic in the guest (./install.sh --profile full --no-assistant) and log out of Hyprland to see the shell take over the SPICE session. qemu-guest-agent is what lets the host read the guest's address and shut it down cleanly, which is why step 3 installs it.

Proxmox VE

The repo ships a helper shaped on the community-scripts Proxmox VE Helper, at tools/devvm/proxmox.sh in the aphotic-hypr repository:

tools/devvm/proxmox.sh init        # write a commented example devvm.env
tools/devvm/proxmox.sh install     # bootstrap PVE on a bare Debian host
tools/devvm/proxmox.sh create-vm   # create the dev VM from the latest Arch ISO
tools/devvm/proxmox.sh reset       # delete and create it again
tools/devvm/proxmox.sh destroy     # delete it
tools/devvm/proxmox.sh status      # state and address

create-vm downloads the latest installer ISO, imports it as the VM's boot disk, grows the disk to the configured size, and creates the guest to the spec above. It takes a default form (no options: the working guest, unattended on a non-terminal, one confirmation on a terminal) and an advanced form (--vmid, --name, --machine, --cpu, --cores, --ram, --disk, --display, --bridge, --storage, --mac, --vlan, --mtu, --user, --ssh-key, --iso-url, --no-start); values in ~/.config/aphotic/devvm.env are the starting points. The VM boots the ISO, so step 3 above runs in the PVE console, and status reports the address once the guest agent answers.

VPS

Most VPS providers do not give you KVM at all, and the ones that allow nested virtualization give you a headless result: no GPU, so no desktop session to watch. A VPS is useful for the non-visual parts: ./install.sh --config-only exercises the config sync without a desktop, and the aphotic CLI, plugins, and the shell services can be run and tested from a terminal. For the desktop itself, use a bare-metal machine or a host with real virtualization.

Handing it to your own agent

If your agent can shell out on a machine that can run a VM, this prompt gets it to the spec above:

You have a machine that can run a KVM VM (libvirt or Proxmox VE). Create
a VM named aphotic-devvm: x86_64, UEFI firmware, VirtIO-GPU display,
host CPU, 6 vCPUs, 12 GiB RAM, 60 GiB disk, on a network the host can
reach. Boot the latest Arch Linux installer ISO
(https://geo.mirror.pkgbuild.com/iso/latest/archlinux-x86_64.iso). In
the guest console run archinstall: best-effort layout on the disk (wipe
it), one user with sudo, add my SSH public key to the user, install
openssh and qemu-guest-agent, then reboot. Verify the guest is
reachable over SSH and that /dev/dri/renderD128 exists inside it. Report
the guest's address and the evidence.

What a guest will not show you

The guest exercises the install path, not the hardware layer:

  • GPU layers. NVIDIA and AMD detection, the driver installs, and the gpu-vram resource accounting all key off real hardware. A VirtIO-GPU guest exercises none of it.
  • Frame rate. Judge the install, not the smoothness.
  • Multi-monitor behaviour, unless you attach more than one virtual display.

See also

Clone this wiki locally