enricobuehlerandClaude Opus 5
d383161723
~1150 feat/fix commits landed since v0.19 and the docs drifted badly. This is a full sweep of every page against the code as shipped: ~280 verified corrections, nine new pages, and one deletion. The worst of what was wrong: the quickstart's five-minute path could not work (`serve` never started the web console, so step 3 had no PIN to read); every packaged Linux host runs `serve --gamestream` while security.md told readers to leave GameStream off; HDR was documented as Windows-only; `PUNKTFUNK_SECURE_DDA` was documented as a working knob that nothing reads; `PUNKTFUNK_INPUT_BACKEND` listed a `uinput` value that does not exist and named libei for KDE instead of kwin; README linked three pages deleted on 2026-07-05; and the rpm-ostree update command pointed at a script no package installs. Completeness: about half of what shipped since v0.19 had no page at all. New: support-matrix (what works where, from 217 verified capability cells), input (mouse/touch/pen — and the in-stream chords, so the docs finally say how to get your mouse back), client-settings, profiles-and-links, game-library, clipboard, wake-on-lan, hdr, uninstall. Updating existed but had zero inbound links. status.md is gone: its facts moved into the support matrix, its shell stays as a redirect so the public URL does not 404. roadmap.md is themes now, not a feature checklist — checkboxes are what rotted. Debian is no longer claimed. The .deb's Depends resolve against Ubuntu images, nothing in CI builds or tests Debian, and Debian 12 is below the glibc 2.39 floor. The `debian` in the repo URL is the package format. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
5.1 KiB
title, description
| title | description |
|---|---|
| GNOME (Mutter) | Configure a Punktfunk host for GNOME — host.env, the EGL/lock traps, and a headless session. |
Configure a host running GNOME. The host drives GNOME's Mutter compositor to create a per-client
virtual display over D-Bus (RecordVirtual), zero-copy. This page assumes the host is already
installed — see Ubuntu, Fedora, or Arch.
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.
host.env
The host auto-detects the compositor from your live session on every connect, so the starter
~/.config/punktfunk/host.env is one line:
# ~/.config/punktfunk/host.env (keys are case-sensitive)
PUNKTFUNK_VIDEO_SOURCE=virtual
# GPU zero-copy (dmabuf → CUDA → NVENC) is ON by default; auto-falls back to CPU. Set =0 to force CPU.
Don't set
PUNKTFUNK_COMPOSITOR,WAYLAND_DISPLAY, orXDG_CURRENT_DESKTOPhere. Pinning the compositor turns auto-detection off — per connect and mid-stream — so the host stops following session switches, and stale session values point it at dead sockets. Forcing a backend is a CI / dedicated-appliance posture, not desktop configuration.
You must be on a Wayland session (not X11), and Mutter must be ≥ 48. See the Configuration reference for every option.
The GL/EGL userspace
On NVIDIA, gnome-shell fails to start — or the host logs "GPU … not supported by EGL" — when the
NVIDIA GL/EGL userspace is missing. The base driver package doesn't always pull it in. Install your
distro's NVIDIA GL/EGL userspace package — on Ubuntu it's libnvidia-gl-<version> matching
your driver; on Fedora/Arch it ships with the RPM Fusion / repo driver — then confirm the glvnd
vendor file exists:
ls /usr/share/glvnd/egl_vendor.d/10_nvidia.json # must exist
Installing the driver itself is covered on your distro's install page (Ubuntu, Fedora, Arch).
Do not lock the session
A locked GNOME session blocks screen capture — the host fails with "Session creation inhibited". On an always-on or headless host there's no one to unlock it, so disable the lock:
gsettings set org.gnome.desktop.screensaver lock-enabled false
gsettings set org.gnome.desktop.session idle-delay 0
Start the host
With host.env in place, start the host from inside your GNOME session:
systemctl --user enable --now punktfunk-host
journalctl --user -u punktfunk-host -f # watch it come up and print its identity fingerprint
This unit runs serve --gamestream, so it serves stock Moonlight clients as well
as the native ones. For a native-only host, see
What the unit starts.
A desktop-login host should also follow your session's lifetime, or restarting GNOME Shell leaves the host wired to a compositor that is gone — it keeps answering, and every session after that fails at capture. Add the drop-in from Restart the host with your desktop. Skip it on the headless route below.
Then bring up The Web Console to arm pairing and connect a client. For an always-on box, see the headless session below.
Display scaling you set while streaming sticks per client: the host remembers each device's scale and reapplies it on reconnect — see Persistent scaling.
HDR (GNOME 50+)
The per-client virtual display this page is about always streams SDR — Mutter's RecordVirtual
screencasts are 8-bit upstream, so there is nothing to turn on.
GNOME 50 added HDR screencast for real monitors, and the host can use that route — on the
GameStream/Moonlight plane only, by mirroring a monitor instead of creating one.
HDR → Linux + GNOME has the two settings it needs, which monitor it
checks, and how it degrades when none is in HDR mode; Check it has the
hdr-probe subcommand that names the link that said no.
Headless session
To run with no monitor and no login, keep a GNOME Wayland session up at all times and start the host without a login. Have GDM auto-login your user:
# /etc/gdm3/custom.conf (Ubuntu) · /etc/gdm/custom.conf (Fedora)
[daemon]
AutomaticLoginEnable = true
AutomaticLogin = your-user
Disable the lock (see above), then enable the host user service and let it linger past logout:
systemctl --user enable --now punktfunk-host
sudo loginctl enable-linger "$USER"
Reboot and the host comes up on the auto-login session. Full walkthrough: Running as a Service.
Troubleshooting
More fixes — black screen, discovery, pairing — in Troubleshooting.
Once the host is up, bring the console up and pair — see The Web Console.