enricobuehler
23d0452157
The user direction after WP0: ENet exists only for Moonlight, so the native
plane must be provably safe and the compat planes a deliberate choice.
Opt-in, everywhere. Windows already was (unchecked installer task). The three
opt-out surfaces are flipped: the shipped systemd user unit (deb/RPM/Arch/
sysext) no longer bakes --gamestream into ExecStart — a new
PUNKTFUNK_GAMESTREAM=1 host.env knob (pf-host-config, OR-ed with the CLI
flag) is the packaged opt-in; the NixOS module default goes true→false, with
a module-check assertion that unset = native-only; the Deck installer takes
--gamestream to opt in (--no-gamestream kept as explicit-off). Docs
(quickstart, running-as-a-service, moonlight, ubuntu/fedora/arch firewall
sections, gnome/sway, how-it-works) rewritten to the opt-in shape; the
CHANGELOG carries the upgrade note.
Enforced-safe. punktfunk-core is #![deny(unsafe_code)] crate-wide — every
module that parses network bytes is safe Rust as a compile error, not a
census result. Carve-outs are exactly two documented classes, neither of
which interprets attacker bytes: the client surface (abi, client) and the
transport syscall-batching shims (udp/{apple,linux,windows}, qos_windows).
In punktfunk-host, the modules a secure-default host exposes — native
(cfg-not-test: its tests exercise the client C ABI on purpose),
native_pairing, mgmt, mgmt_token, discovery, wol — are #[forbid(unsafe_code)].
Gates: Linux amd64 container clippy --all-targets -D warnings clean over
core+host-config+host; core 204 tests green under the deny; mgmt 46/46,
control 6/6. .133 Windows clippy (shipped features, clean-first,
sentinel-checked) clean — covers the qos_windows/udp-windows carve-outs.
macOS + iOS cargo check green (the apple.rs carve-out compiles for real).
6.9 KiB
title, description
| title | description |
|---|---|
| Quick Start | From nothing to streaming — set up a host and connect your first client. |
This is the shortest path to a working stream. Each step links to the details.
A streaming host is remote control of the machine, so it's built for trusted local networks — keep it on your LAN or a VPN and don't expose it to the internet. Two minutes on Security & Safe Use before you start is worth it.
1. Set up the host
On your gaming machine (NVIDIA, AMD, or Intel GPU), follow the install guide for your system:
Each one covers the GPU driver, the dependencies, and how to install and run the host. After installing, configure for your desktop (KDE / GNOME / gamescope / Hyprland / Sway). Check the Requirements first if you're not sure your machine is a fit.
2. Start the host
On Windows there's nothing to start. The installer registered and started the PunktfunkHost
service, so the host is already running and comes back on every boot. Confirm it:
Get-Service PunktfunkHost
Don't run punktfunk-host serve on top of it — a second host process refuses to touch the
virtual-display driver and collides with the service on its ports. Details:
Running as a Service → Windows.
On Linux you don't run the host by hand either. Every Linux package ships a systemd user unit.
That unit reads ~/.config/punktfunk/host.env and won't start until the file exists, so put it in
place first — your distro and desktop pages (step 1) have the template to copy and what to put in it.
Then enable the unit once, from a terminal inside your desktop session, and it comes back at
every login:
systemctl --user enable --now punktfunk-host
journalctl --user -u punktfunk-host -f # watch it come up and print its identity fingerprint
Once up, the host advertises itself on your local network, so clients find it by name. It works out where your compositor is by itself, so there is nothing to export.
That unit runs the secure native-only host (Punktfunk clients + the management API). Want stock
Moonlight clients too? GameStream compat is opt-in — add
PUNKTFUNK_GAMESTREAM=1 to ~/.config/punktfunk/host.env and restart the unit (trusted LANs only;
its pairing runs over plain HTTP) — see
What the unit starts.
If the host runs a firewall (Fedora enables firewalld, CachyOS enables ufw), open its ports — the
firewall step in your distro guide has the exact commands: punktfunk-native always, plus
punktfunk-gamestream only if you enabled Moonlight compat.
On SteamOS even that is done for you — the install script wrote its own punktfunk-host user
service and started it (GameStream on by default there too; pass --no-gamestream to the install
script for a native-only host). Check it with systemctl --user status punktfunk-host.
3. Open the web console
The console is a separate process from the host, and you need it in the next step — arming PIN pairing is done there.
-
Windows: the installer already set it up and starts it at boot. Open
https://<host-ip>:47992. The login password is the one the installer showed you on its final page; it's stored in%ProgramData%\punktfunk\web-password. -
Linux: on Ubuntu, Fedora and Bazzite the
punktfunk-webpackage comes in with the host but isn't enabled for you. On Arch it's an optional dependency, so install it first (sudo pacman -Syu punktfunk-web— a full-Syu, never a bare-S). Either way, start it as your desktop user, then openhttps://<host-ip>:47992:systemctl --user enable --now punktfunk-web sed -n 's/^PUNKTFUNK_UI_PASSWORD=//p' ~/.config/punktfunk/web-passwordThe second command prints the login password generated on first start.
-
SteamOS: the install script already started the console and printed its URL when it finished. It generated the login password into
~/.config/punktfunk/web.env.
The certificate is the host's own self-signed one, so your browser warns once — trust it and continue. Full details: The Web Console.
4. Connect and pair a client
On the device you want to stream to, use a native Punktfunk client for the lowest latency, or any Moonlight client:
- Native client (Apple, Linux, Windows, Android): install it first — Install a Client has the download for every device (Steam Deck: the Decky plugin). Then open the Punktfunk app — your host appears in the list of hosts found on your network. Select it, and when prompted, pair.
- Anything with Moonlight: add the host (it should be discovered automatically), then pair.
To pair, the host needs to show a PIN. Arm pairing from the web console you opened in step 3 — the host displays a 4-digit PIN, you type it into the client, and they trust each other from then on. Pairing is required by default. Full details: Pairing & Trust.
5. Stream
Once paired, select the host and start streaming. The host creates a virtual display at your device's resolution and refresh, and the picture comes up. Mouse, keyboard, and controllers flow back to the host.
Worth knowing before you need it: on the desktop clients the stream takes your mouse and keyboard when it starts, and again whenever you click into it. Ctrl+Alt+Shift+Q (⌃⌥⇧Q on macOS) hands them back. The other in-stream shortcuts, and the mouse, touch and pen modes, are on Mouse, touch and pen.
Now that it works
Punktfunk does more than mirror a screen:
- Browse the host's installed games and launch one straight into the stream — Game library.
- Save named stream settings, bind them to a host, and start a session from a shortcut or a script — Profiles and links.
- Copy on one machine and paste on the other — Shared clipboard.
- Connect to a host that's asleep — Wake-on-LAN.
- Get a 10-bit HDR picture where the whole chain allows it — HDR.
Keep it running
- Tune the picture — resolution, refresh, bitrate, codec and HDR are all client settings; the host's own knobs are in Configuration.
- Make it always-on — no login, no monitor: Running as a Service.
- Keep it current with Updating; changed your mind? Uninstall.
- Hit a snag? See Troubleshooting.