steamify-cachyos-dev/.claude/skills/steam-machine-iso/SKILL.md

name, description

name	description
steam-machine-iso	Use when working on the Steam Machine CachyOS ISO (repo steammachine-cachyos-live-iso) or Steamify's install-time mode (steamify.sh --defaults, --first-login) - building the ISO in podman (in the test VM, or on the Steam Machine), the Calamares Steamify step, simulating the installer in the test VM, and testing the first desktop login.

Steam Machine ISO and Steamify's install-time mode

A CachyOS live ISO for the Steam Machine that installs Steamify's default setup during the install. Two repos:

• steamify-cachyos (Steamify): steamify.sh --defaults applies what the menu would preselect, no prompts, passwordless sudo required. Without a session (installer) user_systemctl only changes unit files, the theme replaces an untouched /etc/skel Plasma layout so Plasma builds Vapor's at first login, and lib/first-login.sh leaves a one-time autostart (--first-login: single user's launcher on the new layout, then the app, next to CachyOS Hello). See AGENTS.md there.
• steammachine-cachyos-live-iso (fork of CachyOS-Live-ISO), branch work never on master:
  • archiso/airootfs/usr/local/bin/calamares-online.sh (the installer launcher) copies CachyOS's settings_online.conf over /etc/calamares/settings.conf on every start, so a shipped settings.conf is lost: it seds shellprocess@steamify (+ its instance) in before cleanup_calamares right after that copy.
  • modules/shellprocess_steamify.conf runs /usr/local/bin/steamify-install ${ROOT} ${USER} outside the chroot; that gives the user a temporary NOPASSWD rule, runs the bundle with arch-chroot ... runuser -u <user> -- env -i ... --defaults, logs to /var/log/steamify-install.log in the target, never fails the install.
  • steamify-prepare.sh [steamify checkout] puts the bundle on the ISO (archiso/airootfs/usr/local/share/steamify/steamify.sh, git-ignored): from a checkout, else the newest release; refuses one without --defaults.

Everything visible

The user watches the Steam Machine over Moonlight: run builds and tests in a Konsole on its desktop (or open one that follows the log), never hidden.

ssh steammachine bash -c "'export XDG_RUNTIME_DIR=/run/user/1000 DBUS_SESSION_BUS_ADDRESS=unix:path=/run/user/1000/bus; systemd-run --user -q konsole --hold -e bash -c \"tail -n 50 -F ~/projects/iso-build.log\"'"

Steam Machine gotchas

• Login shells there and in the VM are fish: wrap loops in bash -c '...' or pipe a script to bash -s.
• Never pkill -f <pattern> from a remote command containing that pattern: it kills its own shell (exit 255).
• The VM's host key lives in ~/projects/steamify-cachyos-dev/known_hosts. Scripts calling plain ssh (vmreset.sh) need a wrapper first in PATH: /tmp/steamify-sshwrap/ssh = exec /usr/bin/ssh -o UserKnownHostsFile=$HOME/projects/steamify-cachyos-dev/known_hosts -o StrictHostKeyChecking=accept-new "$@" (recreate after a reboot).
• Run vmreset.sh as a systemd user unit with -p KillMode=process, a unique unit name, --setenv=REPO=$HOME/projects/steamify-cachyos, the wrapper PATH and SSH_AUTH_SOCK (connect with ssh -A, keep the session open with --wait). Without KillMode=process QEMU dies with the unit; without REPO QEMU fails on the old repo path and the script waits 5 minutes for SSH.

Adding a Calamares page/module for Steamify: check it's real first

Before writing any QML/config for a Calamares page, or building an ISO to test one: confirm the module type is actually installed on this Calamares build. A .conf file existing under archiso/airootfs/etc/calamares/modules/ does not mean the module exists — CachyOS's branding ships some vestigial config files with no matching .so. Check in a live session (boot the ISO, scripts/vmisoboot.sh, no install needed):

ls /usr/lib/calamares/modules                    # real module types, e.g. packagechooser (not packagechooserq)
pacman -Ql cachyos-calamares-next | grep viewmodule

Found on this build (2026-09-28): packagechooserq (arbitrary custom QML, qmlFilename) does not exist — only packagechooser does. Its mode: optionalmultiple supports multi-select, but only with Shift/Ctrl-click (plain clicks replace the selection; unusable for a real user) despite the misleading static label text ("Choose a product from the list. The selected product will be installed." shows in both single- and multi-select modes — don't trust it). Confirm real multi-select from the actual global-storage write in the foregrounded debug log (pkexec-wrapper calamares -D6), not the label text: Config::updateGlobalStorage(const QStringList&) logs "<instance>" selected "id1,id2,id3" (comma-separated) when it works.

Test a page live, without any ISO rebuild: in the booted live session, edit /etc/calamares/modules/<module>_<instance>.conf and the matching module reference in /etc/calamares/settings.conf, then relaunch (pkexec-wrapper calamares -D6). If Calamares is already running (e.g. an earlier failed launch left its window open), a second launch just prints "Calamares is already running." — close the first window (Afbreken/Cancel, confirm) before relaunching. Only spend the 13+ minute ISO build once the page's module and rendering are confirmed this way.

Building the ISO in the test VM (preferred)

Building the ISO in the test VM (preferred)

The build needs no real hardware: run it in the test VM (CachyOS; create it with the vm-install skill), not on the Steam Machine. Not tried yet in the VM: note what differs here. In the VM (vm_ssh, visibly in a Konsole there):

sudo pacman -S --needed --noconfirm podman git
git clone https://github.com/theupriser/steammachine-cachyos-live-iso ~/projects/steammachine-cachyos-live-iso
sudo mount -t 9p -o trans=virtio,version=9p2000.L repo /mnt     # the Steamify checkout (REPO)
cd ~/projects/steammachine-cachyos-live-iso && git checkout feat/steamify && ./steamify-prepare.sh /mnt

then the same podman run as below (paths in the VM; ~/projects/iso-build.log). The ISO (~3.2 GB) fits the 60G disk; copy it out with vm_scp "$VM_USER@$VM_HOST:~/projects/steammachine-cachyos-live-iso/out/desktop/*.iso" . (scripts/common.sh), then install it with scripts/vminstall.sh --iso. Give the VM more room with a bigger disk if out/, build/ and the package cache grow over several builds (sudo rm -rf build out between builds).

Building the ISO (podman on the Steam Machine)

Only podman is installed on the Steam Machine itself; the build tools live in the container. Rootful (loop devices, mounts), so sudo podman ps shows it, not a rootless podman GUI. Clone: ~/projects/steammachine-cachyos-live-iso.

cd ~/projects/steammachine-cachyos-live-iso
git checkout feat/steamify && ./steamify-prepare.sh ~/projects/steamify-cachyos
sudo rm -rf build out
systemd-run --user --collect -q -u isobuild-$(date +%s) --working-directory=$PWD bash -c \
  "sudo podman run --rm -t --pids-limit=-1 --ulimit nofile=65536:65536 --privileged --network=host \
     -v $HOME/projects/iso-cache:/var/cache/pacman/pkg \
     -v $PWD:/iso -w /iso docker.io/cachyos/cachyos:latest bash -c \
     'pacman-key --init && pacman-key --populate && pacman -Syu --noconfirm --needed archiso mkinitcpio-archiso git squashfs-tools grub sudo && ./build-live-modules.sh && ./build-calamares-modules.sh && { ./buildiso.sh -p desktop -w || ./buildiso.sh -p desktop -c -w; }' \
   > $HOME/projects/iso-build.log 2>&1"

-v ~/projects/iso-cache:/var/cache/pacman/pkg keeps the downloaded packages (~3 GB) between builds (mkdir -p ~/projects/iso-cache once): the container's own tools and mkarchiso's pacstrap -c both use that cache, so only updated packages are downloaded. Clear it with sudo rm -rf ~/projects/iso-cache/* if it grows too large.

build-calamares-modules.sh builds Calamares' packagechooserq (the Steamify page's module; CachyOS's package leaves it out) from CachyOS's Calamares source against the installed cachyos-calamares-next, into airootfs, with the version it was built for in built-for (the prebuilt .so is no longer committed). build-live-modules.sh builds the power-off fix for the ISO's kernels (live session; needs the source steamify-prepare.sh puts on the ISO). Output: out/desktop/steamify-cachyos-*.iso (~3.2 GB, ~10 min). The build ends with chown: missing operand + ERROR: An unknown error: harmless, buildiso.sh chowns to $SUDO_USER, unset as root; the ISO is already written. Each flag fixes a failure seen before:

• --network=host: the default network has no DNS here (every mirror "Resolving timed out").
• --pids-limit=-1: otherwise the last ~9 packages alphabetically fail with GPGME error: Inappropriate ioctl for device / "missing required signature".
• pacman-key --init/--populate: the image's keyring isn't initialised.
• The retry with -c keeps the work dir and cache for a flaky pass.

Never start a build while one runs (sudo podman ps): both use build/ and out/, and rm -rf build out breaks the running one. Don't stop a running build to try something else without checking its log first (grep -ac GPGME ~/projects/iso-build.log). The repo's CI recipe (archlinux:base-devel, .github/workflows/build.yml) works too but pulls from one slow mirror.

Testing Steamify's install-time mode in the VM

scripts/vminstallsim.sh [--fresh] (VM up via vmreset.sh --fremont, branch rsynced to ~/projects/steamify-cachyos): creates isotest (never logged in), runs /mnt/steamify.sh --defaults for it without any session, visibly. Every component should print OK and exit: 0. Use --fresh after changes: an earlier run's single user mode edits the skel layout, and the theme then (rightly) refuses.

First desktop login as that user:

1. The first-login step (~/.local/share/steamify/bin/first-login, removes itself) starts the app through run-app, which always downloads the newest release (releases/latest/download/steamify-app.sh): before a release that shows the old version. For the branch's app, start it by hand afterwards as that user: copy /mnt to /opt/steamify-test (chmod -R a+rX), then sudo -u isotest XDG_RUNTIME_DIR=/run/user/1001 DBUS_SESSION_BUS_ADDRESS=unix:path=/run/user/1001/bus systemd-run --user /opt/steamify-test/ui/steamify-ui.
2. Gamescope doesn't run in the VM: Session=plasma.desktop in /etc/sddm.conf.d/zz-steamos-autologin.conf, remove /etc/plasmalogin.conf.d/00-test-autologin.conf, reboot.
3. Expect: Steam Deck wallpaper (Vapor layout), primaryActions=3 in isotest's plasma-org.kde.plasma.desktop-appletsrc, the autostart entry gone, steamify-ui running next to cachyos-hello.
4. Screenshot: QMP screendump gives "no surface" with virgl; use sudo -u isotest env XDG_RUNTIME_DIR=/run/user/1001 DBUS_SESSION_BUS_ADDRESS=unix:path=/run/user/1001/bus WAYLAND_DISPLAY=wayland-0 spectacle -b -n -f -o /tmp/shot.png.

Testing the ISO itself

Unattended: VM_DIR=~/projects/iso-vm scripts/vminstall.sh --iso <built iso> --fremont (vm-install skill) installs it with the ISO's headless cachyos-installer; Calamares and its Steamify step don't run then, so run steamify-install from the live script for that part. Through Calamares by hand, as below.

Install the built ISO in a new VM (~/projects/iso-vm: copy of run.sh, share symlink, cachyos.iso symlink to the build, own disk/vars; power the test VM off first, both use port 2222; run.sh install --fremont as a user unit), through Calamares, then check /var/log/steamify-install.log in the installed system. In the chroot uname -r is the live kernel: module loads and checks against the running kernel may fail even when DKMS built for the installed kernels. Real hardware (Steam Machine, USB stick) is the final test: gamescope, LEDs, CEC, power-off.

Live-session quirks

• Copy/paste doesn't reach QEMU over Moonlight: type commands with python3 scripts/qmptype.py <vm dir>/qmp.sock "<command>" (US layout, adds Enter; the VM window's terminal must have focus). QMP screendump gives "no surface" with virgl: screenshot the Steam Machine's desktop instead (spectacle -b -n -f -o /tmp/host.png in its session).
• CachyOS Hello refuses to start the installer on a self-built ISO ("testing ISO"): run calamares-online.sh in Konsole.
• cachyos-calamares-next 3.4.2-13 needs libboost_*.so.1.91.0 while the repos ship Boost 1.92: steamify-prepare.sh puts 1.91's libraries on the ISO (from archive.archlinux.org) until CachyOS rebuilds it.
• Driving the ISO VM's Calamares with scripts/qmpkey.py/qmpclick.py/ qmptype.py (scripts/vmisoboot.sh for a VM without virgl, so qmpshot.py screendumps work): qmptype.py's character map has no > or & — a typed command using either raises "no key for" and, worse, can leave an unterminated quote in the shell's input buffer (a stray " from a half-typed command), after which every later command you type gets silently absorbed into that one open string instead of running. Symptom: the prompt shows a bare > continuation instead of [user@host ~]$. Fix: send Ctrl+C first (send-key with ctrl+c), then retype. Prefer | tee over > file, and multiple head/tail calls over one long redirected command. Calamares page buttons (Volgende/Terug) move vertically as page content grows/shrinks: re-shot and re-locate the button after every page change, don't reuse a fixed y-coordinate. A second pkexec-wrapper calamares -D6 while an earlier failed instance's window is still open just prints "Calamares is already running.": close that window first (its Cancel/Afbreken button, then confirm the "really cancel?" dialog).
• Run pkexec-wrapper calamares -D6 in its own Konsole tab: it stays in the foreground and blocks that tab's shell. Typing into the same tab afterwards just echoes the text inertly into Calamares' stdin (no error, nothing runs). Open "New Tab" in Konsole for commands.

Keeping this cheap: don't poll screenshots

Repeated qmpshot.py + image analysis to detect "is it booted yet" burns a lot of tokens per image. Prefer cheap, text-only signals instead:

• Boot readiness: pass VM_SERIAL=<dir>/serial to run.sh/vmisoboot.sh (it logs console=ttyS0 to a plain text file via a QMU chardev socket). Wait with a background tail -F <dir>/serial | grep -E "Reached target Graphical Interface|sddm|plasmashell|login:|Failed|panic" — one line of text per event, no image tokens at all.
• Driving the wizard/Calamares: script a fixed sequence of qmpkey.py/qmptype.py/qmpclick.py calls from a known page layout instead of screenshotting after every step to "see where we are". Only take a screenshot at real decision points (to show the user, or to verify a page layout changed) — not as a polling mechanism.
• When the user is driving by hand (as in a live install), just ask them what they see / what step they're on instead of screenshotting the VM yourself — they're already looking at it.
• If you must poll for "is the screen non-black yet", a single low-res screenshot at the end of a serial-log-driven wait is enough; don't loop screenshots every few seconds.
• Calamares' Welcome page applies its keyboard layout to the live session immediately (a live typing preview). If it's not US (e.g. Dutch after picking Nederlands), qmptype.py's US-layout key map silently sends the wrong characters afterwards: / becomes -, (/) get garbled, with no "no key for" error. setxkbmap us does nothing on Wayland. Probe with a symbol-free command (echo test123) after any language/keyboard step, and fix the layout from the live session's own settings before typing paths or shell syntax again.