enricobuehler
346385bad8
`punktfunk-gamescope` had never been published to the apt registry — not in any release. It was built inside the host job's Ubuntu 24.04 image, where it cannot build: our pin vendors wlroots 0.19.3, which floors `wayland-server` at 1.23.1, and noble ships 1.22.0 (it also lacks libxcb-errors-dev and has only libdisplay-info 0.1.1). Every rung of that path was a `::warning::` returning 0 and the one hard gate ran last by design, so v0.26.0 and v0.27.0 both released with the package missing while docs-site told apt users to install it. The same tags shipped it fine for Arch, Fedora 44 and Bazzite. It now builds in its own job on Debian 13 (ci/gamescope-trixie.Dockerfile), the oldest apt base the tree configures on. One package serves Debian 13 AND Ubuntu 26.04 — measured by installing and running it on both — because the build also vendors libdisplay-info via the new `--extra-fallback` option: linked against the distro copy it demands `libdisplay-info2` on trixie, which Ubuntu 26.04 does not have (it carries libdisplay-info3). The option is opt-in, so the Arch/Fedora/nix outputs are byte-for-byte unchanged. Ubuntu 24.04 gets no gamescope package and cannot — its wayland is too old to run one however built. Debian 13 is now a documented host target. That needed no packaging change at all: the host .deb's glibc-2.39 floor and bundled FFmpeg already made it installable, and it had been working for a long time while docs-site said Debian was unsupported and unverified. Verified by installing: host, web console and plugin runner install, resolve every soname and run. The desktop client stays Ubuntu-26.04-only (built there, floors at `libc6 >= 2.43`; Debian 13 has 2.41). Compositor detection now answers Cinnamon (Mint, LMDE) with the route that works instead of advice that cannot help. Muffin forked from Mutter 3.36: `org.cinnamon.Muffin.ScreenCast` has only RecordMonitor/RecordWindow, never RecordVirtual, and xdg-desktop-portal-xapp implements no ScreenCast — so no value of PUNKTFUNK_COMPOSITOR makes a Cinnamon desktop host a virtual display. The error names headless gamescope, which needs no desktop compositor. The XDG sniff moved into a pure function so those branches are testable; Cinnamon is matched before GNOME, since it is a GNOME derivative and the generic arm would otherwise hand it the Mutter backend (caught by the new test). New `smoke-install` job installs every published package from the registry in pristine ubuntu:24.04, ubuntu:26.04 and debian:trixie images, asserts each binary resolves its libraries and runs, and insists the version served is the one this run built. Nothing in deb.yml had ever installed a package it produced, which is how both of the above survived unnoticed. ⚠ Bootstrap: seed `punktfunk-gamescope-trixie:latest` into the LAN registry once (docker.yml builds it thereafter) or the new job cannot start.
8.3 KiB
title, description
| title | description |
|---|---|
| Debian | Install the Punktfunk host on Debian 13 with apt — including LMDE and Linux Mint. |
Install a Punktfunk host on Debian 13 ("trixie") or newer from the apt registry. This page covers the distro-level setup — GPU driver, package, gamepad access. How the host creates its virtual display and injects input is desktop-specific, so pick your desktop on the configure pages afterward rather than here.
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.
Which releases. The host package needs glibc 2.39 or newer; Debian 13 has 2.41, so it installs and runs there. Debian 12 (bookworm) has glibc 2.36 and cannot install it — build from source (Ubuntu appendix, which applies here too) or upgrade. Check yours with
ldd --version.
The desktop client is not packaged for Debian yet.
punktfunk-clientis built on Ubuntu 26.04 and floors atlibc6 >= 2.43(Debian 13 has 2.41), on top of needing GTK4 ≥ 4.20. On a Debian box, stream to it with a different client — the Flatpak, or a build from source. The host, the web console and the plugin runner all install normally.
What works on Debian 13
| Package | Debian 13 | What it is |
|---|---|---|
punktfunk-host |
✅ | The streaming host |
punktfunk-web |
✅ | The browser management console |
punktfunk-scripting |
✅ | The plugin/script runner |
punktfunk-gamescope |
✅ | The patched gamescope (HDR + cursor + real refresh) |
punktfunk-client |
❌ | Desktop client — libc6 >= 2.43, see above |
1. GPU driver
On NVIDIA, the driver lives in Debian's non-free-firmware / non-free components, which a
default install does not enable. Add them, then install the driver:
sudo apt install software-properties-common
sudo apt-add-repository contrib non-free non-free-firmware
sudo apt update
sudo apt install nvidia-driver firmware-misc-nonfree
Reboot, then confirm the driver and KMS modeset — Wayland on NVIDIA needs modeset=1:
nvidia-smi
cat /sys/module/nvidia_drm/parameters/modeset # should print Y
If modeset is not Y:
echo 'options nvidia-drm modeset=1' | sudo tee /etc/modprobe.d/nvidia-drm.conf
sudo update-initramfs -u && sudo reboot
Secure Boot: with Secure Boot enabled, Debian's DKMS-built NVIDIA module must be signed and its key enrolled before it will load. If
nvidia-smican't talk to the driver, enrol the MOK (sudo mokutil --import /var/lib/dkms/mok.pub, reboot, choose Enrol MOK) or disable Secure Boot in firmware.
On AMD/Intel none of the NVIDIA steps apply. Encode runs on the Mesa stack: Vulkan Video for
HEVC and AV1 (mesa-vulkan-drivers), with VAAPI for H.264 and as the fallback —
mesa-va-drivers on AMD, intel-media-va-driver on Intel (the latter is in non-free).
2. Install the host (apt)
The registry is public — no auth needed, just trust its signing key:
sudo install -d -m 0755 /etc/apt/keyrings
curl -fsSL https://git.unom.io/api/packages/unom/debian/repository.key \
| sudo tee /etc/apt/keyrings/punktfunk.asc >/dev/null
echo "deb [signed-by=/etc/apt/keyrings/punktfunk.asc] https://git.unom.io/api/packages/unom/debian stable main" \
| sudo tee /etc/apt/sources.list.d/punktfunk.list
sudo apt update
sudo apt install punktfunk-host
punktfunk-host Recommends the browser console (punktfunk-web), so apt pulls it in by default.
The NVIDIA driver is not a dependency — you installed it out of band in step 1. Later updates
are sudo apt update && sudo apt upgrade; restart the running host afterwards so it picks up the
new binary:
systemctl --user restart punktfunk-host
The stable component above is the stable channel. To track pre-release builds instead, see
Release Channels.
3. Grant gamepad access
Virtual gamepads inject through /dev/uinput, gated by the input group. Add yourself and re-login:
sudo usermod -aG input "$USER" # re-login to apply
Also join punktfunk if you want the virtual Steam Deck controller (paddles, trackpads, gyro) —
it reaches games as a real USB device over usbip, which is what makes Steam Input adopt it. Join it
only on a machine you trust: writing the usbip attach file can materialise arbitrary emulated USB
hardware.
sudo usermod -aG punktfunk "$USER" # re-login to apply
4. Check it installed
punktfunk-host --version # the binary is on PATH
punktfunk-host detect-conflicts # exits 1 if Sunshine/Apollo is also installed
Two hosts on one machine is the most common reason a clean install never streams — see Troubleshooting.
5. Open the firewall (if you have one)
Debian ships no firewall enabled by default, so out of the box there is nothing to open. If you run one, the package installs the openers:
# ufw:
sudo ufw allow punktfunk-native
# firewalld:
sudo firewall-cmd --reload # load the installed definitions
sudo firewall-cmd --permanent --add-service=punktfunk-native
sudo firewall-cmd --reload
Add punktfunk-gamestream for Moonlight compat and punktfunk-web (TCP 47992) to reach the console
from another device. Full port lists are in
packaging/debian/README.md.
Cinnamon, Linux Mint and LMDE
A Cinnamon desktop cannot host a virtual display, and no setting changes that. Punktfunk gives
each client its own screen at that device's exact resolution by asking the compositor to create a
virtual output. Cinnamon's compositor, Muffin, has no such API: it forked from Mutter 3.36, and
its org.cinnamon.Muffin.ScreenCast interface offers only RecordMonitor and RecordWindow —
never the RecordVirtual that Mutter gained in 42. Its portal backend
(xdg-desktop-portal-xapp) implements no ScreenCast either, so the route that serves Sway and
Hyprland is closed too. This is upstream's to fix, not a Punktfunk setting.
What does work on a Mint or LMDE box is gamescope: the host starts its own headless gamescope for each connecting client and runs the game inside it, so it needs no desktop compositor at all. Your Cinnamon session keeps running untouched; the stream is the game, not the desktop.
sudo apt install punktfunk-gamescope
echo 'PUNKTFUNK_COMPOSITOR=gamescope' >> ~/.config/punktfunk/host.env
systemctl --user restart punktfunk-host
The pin is required: auto-detection reads the live session, finds Cinnamon, and stops with an error
rather than guessing. Set a game to launch with
PUNKTFUNK_GAMESCOPE_APP or per-session launch commands, then see
Steam / gamescope for the rest.
Install
punktfunk-gamescope, not Debian's. Debian ships nogamescopepackage at all, and the patched build is what gives the stream HDR, a visible cursor, and the client's real refresh rate instead of a hardcoded 60 Hz.
If you want to stream the desktop from a Mint box, the answer today is to run a KDE, GNOME, Sway or Hyprland session instead — all four expose a virtual-output API.
Configure your desktop
How the host creates its virtual display and injects input depends on your desktop, not your distro:
Then bring up The Web Console to arm pairing and connect your first client. To run the host at boot — including fully headless — see Running as a Service.
Next steps
- Keep it current — Updating the Host.
- Remove it again — Uninstalling.
- Something not working? — Troubleshooting.
- Build from source (Debian 12, or tracking
main) — the Ubuntu appendix applies unchanged; Debian 13'slibavcodec-devis new enough to build against.