steamify-cachyos-dev/README.md

cachyos-gamescope-boot dev environment

A QEMU/KVM test VM running CachyOS (KDE Plasma 6) for developing and testing cachyos-gamescope-boot, plus helper scripts and a Claude Code skill that documents the test workflow.

Only scripts and docs live here. The ISO, disk image, UEFI variable stores, logs and screenshots are generated locally. .gitignore is an allowlist: it ignores everything and un-ignores only the tracked files, so add any new tracked file to it explicitly.

Requirements

• Linux host with KVM, qemu-system-x86_64 (GTK/OpenGL display, virtfs/9p) and qemu-img (Ubuntu: sudo apt install qemu-system-x86 qemu-utils ovmf).
• OVMF firmware at /usr/share/OVMF/OVMF_CODE_4M.fd and OVMF_VARS_4M.fd.
• curl and sha256sum for get-iso.sh.
• Optional: an NVIDIA dGPU for --nvidia (PRIME offload of the virgl renderer).

Windows

run.ps1 and get-iso.ps1 are Windows versions. They need QEMU for Windows (or set QEMU_DIR) and the "Windows Hypervisor Platform" feature (-accel whpx). Windows QEMU has no 9p shares: copy the repo into the guest with scp -P 2222 -r ..., and authorize your key with .\add-ssh-key.ps1 -User <vm-user>.

Quick start

./get-iso.sh        # download and verify the latest CachyOS desktop ISO
./run.sh install    # first run creates disk.qcow2 (60G) and vars.fd, boots the ISO

Install CachyOS with the KDE Plasma desktop and plasma-login-manager as login manager. Power off and snapshot (only while the VM is off):

qemu-img snapshot -c clean disk.qcow2 && cp vars.fd vars.clean.fd

Boot the installed system (./run.sh) and, in the guest, enable SSH with key auth and passwordless sudo through the read-only vmtools share:

sudo mount -t 9p -o trans=virtio,version=9p2000.L vmtools /media && /media/guest-ssh-setup.sh

Adding your SSH key

guest-ssh-setup.sh authorizes the host's public keys. run.sh copies them at every start from ~/.ssh/*.pub into share/host-keys.pub (git-ignored), which the guest sees as /media/host-keys.pub. So:

1. Make sure you have a key on the host; create one if ls ~/.ssh/*.pub shows nothing:

   ssh-keygen -t ed25519
   

2. Start (or restart) the VM with ./run.sh, so the key is copied into the share.

3. In the guest, run the setup script (above). It installs and starts sshd, opens port 22 if a firewall is active, adds every host key to ~/.ssh/authorized_keys (without duplicates) and gives the guest user passwordless sudo.

4. Test from the host: ssh -p 2222 <vm-user>@localhost true should return without asking for a password.

If you ran the setup script before the key existed (it prints "No host keys were shared"), or you want to add another key later, either restart the VM and run the setup script again, or copy the key over SSH with the guest user's password:

ssh-copy-id -p 2222 <vm-user>@localhost

On Windows, use .\add-ssh-key.ps1 -User <vm-user> instead (it creates a key if needed). If SSH hangs at "banner exchange", sshd isn't running in the guest or a firewall blocks port 22; check with systemctl is-active sshd in the guest.

Power off and snapshot again:

qemu-img snapshot -c ssh-ready disk.qcow2 && cp vars.fd vars.ssh-ready.fd

Connect with ssh -p 2222 <user>@localhost. The project repo is shared read-write as 9p tag repo; in the guest: sudo mount -t 9p -o trans=virtio,version=9p2000.L repo /mnt.

run.sh options

[REPO=/path/to/cachyos-gamescope-boot] ./run.sh [install] [--nvidia] [--vulkan] [--fremont]

• install: boot the installer ISO
• --nvidia: render the guest's virtio-gpu (virgl) on the host NVIDIA dGPU
• --vulkan: expose Vulkan to the guest (venus; unstable)
• --fremont: fake the Valve Steam Machine (Fremont) DMI data via -smbios
• REPO defaults to $HOME/projects/cachyos-gamescope-boot

Helper scripts

• scripts/vmreset.sh [--fremont]: restore ssh-ready, boot, mount the repo, autologin into Plasma
• scripts/vmrun.sh '<menu input>': run the wizard in the guest's Plasma session with scripted input
• scripts/vmwatch.sh '<menu input>' [label]: same, but in a visible Konsole window in the VM
• scripts/vmshot.sh <out.png>: screenshot the guest's desktop
• scripts/vmstate.sh: print the state of every wizard component
• scripts/cmp.sh [save]: save / diff the guest's KDE configs against a baseline

They use VM_USER (default theupriser), VM_PORT (2222) and VM_HOST (localhost).

Claude Code skill

The full test workflow is documented in .claude/skills/cachyos-vm-testing/SKILL.md; Claude Code picks it up when run from this repo.