Running as a Service

Run the host as a service so it is always there: from login on a desktop, from boot on a headless box.

What the unit startsCopy Anchor Link

The service runs punktfunk-host serve: the Punktfunk plane (punktfunk/2) and the management API. Two more planes stay off until you turn them on under Host in the web console, or in ~/.config/punktfunk/host.env:

Both take effect after a host restart. GameStream pairs over plain HTTP with weaker encryption, so turn it on only on a LAN you trust (Security). systemctl --user cat punktfunk-host shows the unit in effect, drop-ins included.

The browser client (preview)Copy Anchor Link

Set it up with Browser Client. PUNKTFUNK_WEBTRANSPORT_BIND keeps the plane on one interface.

A desktop you log intoCopy Anchor Link

The packages ship a systemd user unit. Enable it once and the host starts at every login:

systemctl --user daemon-reload             # needed on the Bazzite sysext, harmless elsewhere
systemctl --user enable --now punktfunk-host
systemctl --user status punktfunk-host

The host finds your live session by itself, so it needs no host.env and no systemctl --user import-environment. For settings, use the console or copy a template to ~/.config/punktfunk/host.env — they are in /usr/share/punktfunk/ (/usr/share/punktfunk-host/ on Ubuntu); every knob is in Configuration. A line in host.env locks that setting in the console until you delete it. Built from source? Build from source installs the unit.

Restart the host with your desktopCopy Anchor Link

Without this drop-in, restarting Plasma or GNOME (a crash, logging out and back in) leaves the host answering but failing every session at capture. The drop-in makes a desktop restart a host restart:

mkdir -p ~/.config/systemd/user/punktfunk-host.service.d
# /usr/share/punktfunk-host/ on Ubuntu
cp /usr/share/punktfunk/punktfunk-host-desktop-session.conf \
   ~/.config/systemd/user/punktfunk-host.service.d/desktop-session.conf
systemctl --user daemon-reload
systemctl --user reenable punktfunk-host
systemctl --user restart punktfunk-host

On NixOS set services.punktfunk.host.desktopSession = true; instead.

Skip it on a headless box (below). Sway and Hyprland never reach systemd's graphical-session.target, so the drop-in does nothing there: leave the unit disabled and start the host from the compositor config — exec systemctl --user start punktfunk-host (sway) or exec-once = systemctl --user start punktfunk-host (Hyprland). niri-session does reach it, so the drop-in works under niri.

A headless, always-on hostCopy Anchor Link

A box with no monitor and no login needs the host to start without a login, and a desktop session that comes up at boot.

1. Let user services start at boot (the guided installer's --linger does the same):

   Copy Text

   sudo loginctl enable-linger "$USER"

2. Bring up a session at boot:

   • GNOME: GNOME → Headless session.
   • KDE Plasma: KDE → Headless session.
   • Steam / gamescope, Bazzite: nothing to set up — the host starts a session per client (gamescope).

3. Enable the host unit as above, and reboot.

WindowsCopy Anchor Link

The installer registers the host as the PunktfunkHost service: LocalSystem, started at boot, so it captures the lock screen and UAC prompts with nobody logged in. Keep a host with that much reach on a network you trust (Security).

Manage it from an elevated prompt:

punktfunk-host service status
punktfunk-host service restart

Every service subcommand is in Host CLI. The planes in What the unit starts work the same way; host.env is %ProgramData%\punktfunk\host.env. The installer opens the firewall on Private and Domain networks only; a LAN Windows calls Public needs one more step.

VerifyingCopy Anchor Link

After a reboot, from another machine:

punktfunk reachable 192.168.1.50   # exit 0 = the host answered, 2 = it didn't
punktfunk hosts list --probe       # every saved host, online or offline

punktfunk ships with the Linux client packages and the Windows client. Any client that lists the host works too. No answer? Read journalctl --user -u punktfunk-host on the host, or punktfunk-host service status on Windows.

GPU scheduling priorityCopy Anchor Link

PyroWave encodes on the same GPU cores as your game, and on NVIDIA the host converts every frame there before the video engine encodes it. So the host asks the driver to run that work first. The request needs CAP_SYS_NICE, which every Linux install grants to a small helper, punktfunk-encode-worker — never to punktfunk-host.

Never give punktfunk-host a capability — not with setcap, a systemd AmbientCapabilities= line or a NixOS security.wrappers entry. KWin can't identify a host that holds one, and every KDE session fails at capture with:

KWin does not expose zkde_screencast_unstable_v1 to this client

Check both binaries:

getcap /usr/bin/punktfunk-host              # should print nothing
getcap /usr/bin/punktfunk-encode-worker     # /usr/bin/punktfunk-encode-worker cap_sys_nice=ep
sudo setcap -r /usr/bin/punktfunk-host      # clears it; then restart the host

On the Bazzite image /usr is read-only: run sudo punktfunk-sysext update instead. On NixOS the module wraps the worker for you.

Without the grant the stream still runs, at normal priority, but a GPU-bound game adds milliseconds to every frame. The host log then says VkBridge queue at default GPU priority. PYROWAVE_QUEUE_PRIORITY=off and PUNKTFUNK_ENCODE_WORKER=off are the opt-outs — Configuration.

Stopping and removingCopy Anchor Link

systemctl --user stop punktfunk-host        # Linux, until next login
systemctl --user disable --now punktfunk-host
punktfunk-host service stop                 # Windows, elevated

punktfunk-host service uninstall removes the Windows service and its firewall rules; the rest of the install goes through Settings → Apps. A Linux package update restarts the running service for you — Updating. Your config and pairings survive all of this; Uninstall clears them.