Documentation / Proxmox Test VM

Testing Aphotic in a Proxmox VE Guest

Installing a full desktop on the machine you work on is a big first move. A Proxmox guest lets you watch a complete run, pick a profile, break it, and roll back to a snapshot. Changes to install.sh go through a guest here before they ship, so the install path gets exercised in a VM routinely.

[!WARNING] The installer prints a warning when it detects a VM. That is expected, and you can continue past it. The guest below runs Hyprland and the Aphotic shell, so the warning describes a risk rather than a wall. It stays because a VM is not a supported target for daily use.

Two settings decide whether this is usable. Set the display adapter to VirtIO-GPU, which gives the guest the /dev/dri/renderD128 render node Hyprland draws through; Proxmox defaults to std. Then reach the guest over SPICE rather than the browser console, or the SUPER key most of Aphotic hangs off never arrives.

The guest that works

Read off the running dev VM, not copied from a template.

Verified in the guest:

$ hostnamectl | grep -E 'Chassis|Virtualization'
       Chassis: vm 💽
Virtualization: kvm

$ lspci | grep -i vga
00:01.0 VGA compatible controller: Red Hat, Inc. Virtio 1.0 GPU (rev 01)

$ ls /sys/class/drm/
card1  card1-Virtual-1  renderD128  version

$ lsmod | grep virtio_gpu
virtio_gpu            114688  26
virtio_dma_buf         12288  1 virtio_gpu

$ pgrep -a Hyprland
1017983 Hyprland --watchdog-fd 4

Hyprland comes up on its own there. You do not need WLR_RENDERER_ALLOW_SOFTWARE=1, and nothing in Aphotic sets it.

Creating the guest

Substitute your own VM ID, storage name and ISO.

qm create 900 \
  --name aphotic-devvm \
  --machine q35 \
  --bios ovmf \
  --efidisk0 local-lvm:1,efitype=4m,pre-enrolled-keys=0 \
  --cpu host \
  --cores 6 \
  --sockets 1 \
  --memory 12288 \
  --scsihw virtio-scsi-single \
  --scsi0 local-lvm:60 \
  --net0 virtio,bridge=vmbr0 \
  --vga virtio \
  --ostype l26 \
  --ide2 local:iso/archlinux-x86_64.iso,media=cdrom \
  --boot 'order=ide2;scsi0'

--vga virtio is the line to get right. In the web UI it is Hardware → Display → VirtIO-GPU. Quote the --boot value: the semicolon is a shell separator otherwise.

Turn on the guest agent while you are here, which the SPICE section below uses:

qm set 900 --agent 1

Take a snapshot once Arch is installed and before you run install.sh:

qm snapshot 900 clean-arch --description "Arch base, pre-Aphotic"

Then roll back between test runs:

qm rollback 900 clean-arch

Connecting with SPICE

Use a SPICE client, not the browser console. Aphotic binds almost everything to SUPER, and the browser console is where SUPER tends to get swallowed by the host window manager before it ever reaches the guest. A SPICE client grabs the keyboard, so SUPER, SUPER+D, SUPER+W and the rest land in Hyprland.

Enable the QEMU guest agent on the VM:

qm set 900 --agent 1

Open Console → SPICE in the Proxmox web UI. That downloads a small .vv file which your client opens.

On the machine you sit at

Running the dev VM from inside Aphotic over SPICE works, so you can keep the guest in a workspace beside everything else.

spice-space.org carries the client binaries and the Windows guest tools on one page, so pick the client for the OS you are sitting at. The guest side is below.

In the Arch guest

sudo pacman -S spice-vdagent qemu-guest-agent

Nothing to enable. Both units ship static on Arch and start themselves when the virtio ports appear:

$ systemctl is-enabled spice-vdagentd qemu-guest-agent
static
static

$ ls /dev/virtio-ports/
com.redhat.spice.0  org.qemu.guest_agent.0

$ pgrep -a spice-vdagentd
699957 /usr/bin/spice-vdagentd -x

spice-vdagent handles clipboard sharing and display resizing. qemu-guest-agent is what lets Proxmox read the guest’s IP and shut it down cleanly.

VirtIO-GPU and SPICE coexist. The dev VM runs both.

Installing

Same as anywhere else:

git clone https://github.com/T-Crypt/Aphotic-Hypr.git
cd Aphotic-Hypr
./install.sh

Try --dry-run first if you want to read the resolved package list without touching the guest:

./install.sh --profile full --with gaming,dev --dry-run

What a guest will not show you

• 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 path, not the smoothness. Rendering through VirtIO-GPU is not what the shell performs like on metal.
• Multi-monitor behaviour, unless you attach more than one virtual display.

See also

• Installation
• Compatibility
• Troubleshooting

View public Wiki source ↗