enricobuehlerandClaude Fable 5
6617275387
Field triage (Nobara, Discord): the kde.md starter host.env told desktop users to set PUNKTFUNK_COMPOSITOR=kwin, which PINS the backend — detect() short-circuits and the capture-loss rebuild never re-detects — so a mid-stream switch to Game Mode killed the stream instead of following it. A follow-up hardcoded XDG_RUNTIME_DIR=/run/user/1000 anchor broke PipeWire for any non-1000 uid (pw audio connect: Creation failed). Revamp across every starter/example/reference: - Desktop starters (kde/gnome/hyprland/sway) shrink to PUNKTFUNK_VIDEO_SOURCE=virtual + an explicit warning that pinning disables session-following; forcing a backend is CI/appliance-only. - host.env.example: rewritten around auto-detection; anchors demoted to a commented ssh/cron-only block with the uid trap spelled out; the gamescope ATTACH/MANAGED knobs documented (previously missing); case-sensitivity called out. - packaging/bazzite/host.env + README: drop the uid-1000 anchors (a systemctl --user service inherits/derives them); README's stale PUNKTFUNK_COMPOSITOR=gamescope-era template synced to the real one. - packaging/kde/host.env: loud APPLIANCE-ONLY header (it pins on purpose). - configuration.md: session-anchors section inverted to "leave unset", compositor row states the pin consequence, case-sensitivity note. - troubleshooting.md: new "session fails right after editing host.env" section (case, wrong-uid anchors, stale pin, restart-to-apply). - gamescope.md/bazzite.md: attach/managed descriptions match current behavior (managed is the infra-detected default; attach re-modes a box-owned session to the client's resolution). Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
7.7 KiB
title, description
| title | description |
|---|---|
| Bazzite | Set up a punktfunk host on Bazzite — it follows the box between Steam Gaming Mode (gamescope) and the KDE Plasma desktop automatically. |
Bazzite already ships everything a punktfunk host needs — the NVIDIA driver, NVENC, PipeWire, gamescope, and the KDE Plasma desktop. So a Bazzite host is the most "appliance-like" setup, and it streams both of Bazzite's faces:
- Steam Gaming Mode (gamescope) — the couch/handheld game UI.
- The KDE Plasma desktop — the full desktop you get from "Switch to Desktop".
The host auto-detects which one is live and follows the box across the switch — including
mid-stream. You flip between Gaming Mode and Desktop with Bazzite's normal Steam UI /
"Switch to Desktop"; the host just re-targets whatever's running and keeps streaming. Nothing in
host.env forces a mode.
Ideal for a dedicated game-streaming box that you also occasionally want as a remote desktop. For a pure desktop machine, install on Ubuntu or Fedora and configure the KDE or GNOME desktop directly — simpler.
New here? Read Security & Safe Use first — a streaming host is remote control of the machine, so keep it on a trusted LAN or VPN and require pairing.
Install
The host installs as a systemd system extension (sysext) — no rpm-ostree layering. The
Bazzite docs treat layering as a last resort (layered packages slow every OS update and can block
upgrades until removed); a sysext never enters an rpm-ostree transaction: it overlays /usr
read-only from /var/lib/extensions/, survives OS updates, installs and updates without a
reboot, and is removable in one command. This is the same mechanism the Fedora Atomic
maintainers ship via the fedora-sysexts project.
# One-time bootstrap (afterwards the updater is on PATH as `punktfunk-sysext`):
curl -fsSLO https://git.unom.io/unom/punktfunk/raw/branch/main/packaging/bazzite/punktfunk-sysext.sh
sudo bash punktfunk-sysext.sh install # add `--channel canary` for rolling builds
That downloads the newest image (host + tray + web console, SHA-256-verified over HTTPS from punktfunk's package registry), merges it, and applies the udev/sysctl setup on the spot — the host is usable immediately, no reboot. From then on:
sudo punktfunk-sysext update # fetch + merge the newest build
sudo punktfunk-sysext status # channel, installed vs latest version
sudo punktfunk-sysext remove # unmerge and delete — the box is back to stock
Two things to know:
- After a Bazzite major rebase (Fedora 43 → 44) the old image refuses to load rather than
run against mismatched system libraries — run
sudo punktfunk-sysext updateonce and it fetches the image built for the new base. - Already layering punktfunk? Install the sysext (it shadows the layered copy immediately),
then drop the layer so it stops slowing your updates:
sudo rpm-ostree uninstall punktfunk punktfunk-web && systemctl reboot.
For a fully baked appliance image there's also a bootc Containerfile that installs the RPMs
from the registry at image-build time — see packaging/bootc/ in the repo. Plain rpm-ostree
layering from the RPM registry keeps working too (see
packaging/bazzite/README.md), but the sysext is the supported default. Building from source
also works (Bazzite is Fedora Atomic underneath — same steps as Fedora).
Allow controller input
Gamepad and DualSense input needs your user in the input group. On Bazzite, don't use
usermod — the base is immutable and the group is managed by a recipe. Use:
ujust add-user-to-input-group
Then log out and back in. (A controller that's "detected but does nothing" is almost always this permission, not a client problem.)
Configure
The RPM ships a Bazzite-tuned config you can copy as your starting point:
mkdir -p ~/.config/punktfunk
cp /usr/share/punktfunk/host.env.bazzite ~/.config/punktfunk/host.env
The template is deliberately minimal — it does not force a compositor, because the host auto-detects Gaming Mode (gamescope) vs Desktop (KWin) on every connect and follows the switch mid-stream. No session anchors are needed either (a user service inherits the right runtime dir). The only settings that matter (GPU zero-copy is on by default):
PUNKTFUNK_VIDEO_SOURCE=virtual
# GPU zero-copy (dmabuf → CUDA → NVENC) is ON by default; auto-falls back to CPU. Set =0 to force CPU.
PUNKTFUNK_GAMESCOPE_ATTACH=1 # Gaming Mode = attach to the box's own session (see below)
Gaming Mode: attach vs managed
For Gaming Mode there are two models (pick one; the shipped default is attach):
- Attach (
PUNKTFUNK_GAMESCOPE_ATTACH=1, the template's default) — the box owns its gamescope session on its own display, and the host attaches to whatever's live without ever tearing it down (a box-owned autologin session is restarted at the client's resolution on a mismatch). Switching Desktop ↔ Game is rock-solid. - Managed (
PUNKTFUNK_GAMESCOPE_MANAGED=1, and remove the attach line) — the host takes the box's gamescope over and relaunches it headless at the client's exact resolution and refresh — Game Mode on the virtual screen — restoring the box on idle.
Full treatment: Steam / gamescope → Attach vs managed.
Mid-stream Gaming ↔ Desktop following (PUNKTFUNK_SESSION_WATCH) is on by default on
Bazzite/SteamOS. See Configuration for the full list of knobs.
Streaming the KDE Plasma desktop
The virtual output (video) for the Desktop session needs no config — the host package ships an
io.unom.Punktfunk.Host.desktop file whose X-KDE-Wayland-Interfaces grants the host KWin's
restricted screencast protocol on a normal interactive Plasma session (background:
KDE Plasma). After a fresh host install, log out and back into the Desktop session
once so KWin re-reads that grant.
The one thing a normal KDE login lacks is the RemoteDesktop grant for headless input injection. Seed it once (as the streaming user, no root) so the host auto-approves instead of popping an un-answerable dialog:
bash /usr/share/punktfunk/bazzite/kde-desktop-setup.sh
Gaming Mode needs none of this — it auto-attaches.
Run as an always-on host
Bazzite hosts are typically headless. Enable the host service and linger so it starts at boot — see Running as a Service. One host service covers both Gaming Mode and the Desktop; it follows whichever the box is in.
systemctl --user enable --now punktfunk-host
systemctl --user enable --now punktfunk-web # web console: pairing + status
Then open The Web Console for the login password and to arm pairing.
Good to know
These apply to the Gaming Mode (gamescope) path; the KDE Desktop path is unaffected:
- gamescope 3.16.22 or newer is required. Older versions can deadlock during capture. Bazzite's current gamescope is fine; this only bites if you've pinned an old one.
- The mouse cursor isn't included in the captured image — a gamescope limitation for now. (The KDE Desktop path renders the cursor normally.)
- HDR isn't supported yet on the gamescope path — gamescope's capture output is 8-bit. SDR streams normally.
Canonical list: gamescope → Known limits.
Then connect a client — Moonlight works great for couch gaming, and the Apple app for Apple TV / iPad.