enricobuehler
69fcb6e0b1
Split the docs' single distro×desktop axis (ubuntu-gnome / ubuntu-kde / fedora-kde) into two,
which deduplicates the shared mechanics and scales to distros that run several desktops (Arch):
- Install the host — per distro/OS (ubuntu, fedora, arch, bazzite, steamos-host, windows-host):
GPU driver + package + input group, then a canonical "Configure your desktop" funnel.
- Configure your desktop — per compositor (kde, gnome, gamescope, sway): host.env, compositor
quirks, the headless session, and starting the host.
New shared web-console page (enable · login password · arm pairing) removes the console/password
block that was copy-pasted across all seven host pages. Merged ubuntu-gnome + ubuntu-kde into
ubuntu; renamed fedora-kde to fedora; kept bazzite and steamos-host as dedicated appliance guides
(trimmed of duplication). Moved the KWin headless session, the GNOME EGL/lock traps, and the
gamescope attach/managed model out of the distro pages onto their compositor pages.
Fixed while restructuring: distro-specific paths on kde (kde-desktop-setup.sh is Fedora/Bazzite-only;
the .deb ships host.env.kde under /usr/share/punktfunk-host), the interactive "start the host" step
that was lost in the merge, sway over-claiming Hyprland, and a pre-existing broken anchor in
how-it-works.
Removal of the three old pages was captured by the preceding commit 8ebb614 (a concurrent commit
swept up the staged git-rm); the net docs tree is correct. Fumadocs build + internal link/anchor
check green.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
4.5 KiB
title, description
| title | description |
|---|---|
| Running as a Service | Start the host at boot — for a desktop you log into, or a fully headless always-on machine. |
Running serve in a terminal is fine for trying punktfunk out. To make a machine an
always-available host, run it as a service. There are two cases.
The bundled unit
scripts/punktfunk-host.servicerunsserve --gamestream, so it serves both the nativepunktfunk/1plane and stock Moonlight clients. For a secure native-only host (no GameStream — its pairing runs over plain HTTP and its legacy encryption is weaker), drop--gamestreamfrom the unit'sExecStartand use bareserve.
A. A desktop you log into
If you sit at the machine (or it auto-logs-in to a desktop), run the host as a systemd user service that starts with your session:
mkdir -p ~/.config/systemd/user
cp scripts/punktfunk-host.service ~/.config/systemd/user/
# Put your host.env in place first — see the setup guide for your desktop.
systemctl --user daemon-reload
systemctl --user enable --now punktfunk-host
The host now starts whenever you log in. Check it with systemctl --user status punktfunk-host.
B. A headless, always-on host
To run with no monitor and no login — a machine in a closet that's always ready — you need two things: a desktop session that comes up at boot, and the host service started without a login.
Start by making the host service start at boot even when nobody logs in:
sudo loginctl enable-linger "$USER"
Then bring up a session automatically. How you do that is desktop-specific — auto-login, lock disable, and the session unit differ per compositor, so each is documented on its own page:
- GNOME: GNOME → Headless session.
- KDE Plasma: KDE → Headless session.
- Steam / gamescope: gamescope — the host launches its own session per client, so there's no separate session unit.
Once a session comes up at boot, enable the host user service (section A) and reboot. The host comes up on that session.
Headless Bazzite
On Bazzite, the host launches its own gamescope/Steam session per client, so you don't need a separate session unit — see Bazzite and gamescope.
Windows
punktfunk has first-class Linux and Windows hosts. On Windows it ships as a signed installer with an SCM service and a virtual-display driver — including punktfunk's own indirect display driver the host pushes frames straight into. The Windows host is newer than the Linux host. (Not to be confused with the Windows client, which streams to a Windows PC.)
On Windows the host runs as a LocalSystem service that launches into the interactive session, so it
captures the secure desktop (UAC / lock screen) and survives reboots with nobody logged in — the same
model Sunshine/Apollo use. Because it runs at that privilege level, keep it on a trusted network and be
deliberate about which machine you host on — see Security & Safe Use.
The easy path is the signed installer: download punktfunk-host-setup-<ver>.exe from the package
registry (punktfunk-host-windows) and run it. It drops the host
into C:\Program Files\punktfunk, installs the bundled pf-vdisplay virtual-display driver, and
registers + starts the service for you (/VERYSILENT for unattended). Upgrades and uninstall are
handled through Add/Remove Programs.
Prefer the CLI? Run punktfunk-host service install from an elevated prompt — see
Windows Host. For hardware encode you need a GPU — NVIDIA (NVENC), AMD (AMF), or
Intel (QSV); the host falls back to software H.264 without one.
Firewall scope. The installer opens the streaming + console ports on Private and Domain networks only — not Public. If your LAN is (mis)classified Public, clients won't connect until you set it to Private (Windows Settings → Network), and the host logs a warning when it's on a Public network. For a trusted network Windows insists is Public, tick "Allow connections on Public networks" at install (or pass
--allow-public-networktoservice install). See Security & Safe Use for the reasoning.
Verifying
After a reboot, from another machine on the network:
punktfunk-probe --discover # or just look for the host in a native client / Moonlight
If the host is listed, it's up. If not, check journalctl --user -u punktfunk-host on the host.