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).
4.7 KiB
title, description
| title | description |
|---|---|
| Sway / wlroots | Configure a Punktfunk host on sway. |
Sway can host: the host adds a per-client headless output at the client's exact mode with
swaymsg create_output and captures it through the xdg-desktop-portal-wlr (xdpw) ScreenCast portal,
injecting input via the wlroots virtual pointer/keyboard protocols.
Despite the backend's name, this path is sway specifically. Everything it does for video —
creating the headless output, setting its mode, listing your monitors — goes through sway's IPC
(swaymsg), so a wlroots compositor without that IPC (River, dwl, …) cannot host: the session fails
straight away with swaymsg get_outputs (is the host inside the sway session env — SWAYSOCK?).
Input would be fine there — it uses the wlroots virtual pointer/keyboard protocols, which those
compositors do have — but with no video there is no stream.
On Hyprland? It's a separate first-class backend (its own
hyprctlIPC and xdph portal) — see Hyprland. This page is for sway.
This is not a primary target. It works and is validated live on sway 1.11 (zero-copy), but it sees far less testing than the KDE and GNOME paths — expect rougher edges. If you have a choice, KDE or GNOME are the better-exercised desktops.
This page assumes the package is already installed — see Arch, Ubuntu, or Fedora.
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 a wlroots session, so the starter ~/.config/punktfunk/host.env is one line:
PUNKTFUNK_VIDEO_SOURCE=virtual
# GPU zero-copy capture→encode is ON by default; auto-falls back to CPU. Set PUNKTFUNK_ZEROCOPY=0 to force CPU.
To force the backend (CI/testing — note that pinning turns live-session auto-detection off, so the host stops following session switches):
PUNKTFUNK_COMPOSITOR=wlroots # aliases: sway, wlr
PUNKTFUNK_INPUT_BACKEND=wlr
See Configuration for the full reference.
How it works
- Video — the host adds a headless output at the client's exact mode with
swaymsg create_output. This uses sway's IPC specifically, and so does everything else on the video side (mode setting, monitor listing). (Hyprland is driven by its own backend, not this one.) - Capture — it captures that output through the xdg-desktop-portal-wlr (xdpw) ScreenCast portal. The host writes a managed chooser config so the output pick is automatic — no interactive picker dialog to answer.
- Input — mouse and keyboard are injected via the wlroots virtual pointer and virtual keyboard protocols.
For how long the virtual output lives, and extend-vs-exclusive topology, see Virtual displays.
Requirements
-
A running sway session — its IPC socket (
SWAYSOCK) is what the whole video path runs on. You don't have to export it: the host finds the live sway instance itself on every connect, so asystemd --userhost works even though it never inherited your login shell's environment. On Hyprland, use the Hyprland backend instead. -
xdg-desktop-portal-wlr (xdpw) installed and running — the host captures through its ScreenCast portal. Without it there is no video.
-
ScreenCast routed to xdpw — only if another portal backend (gtk, gnome) is installed alongside it.
xdg-desktop-portalpicks one implementation per interface, and if it hands ScreenCast to the wrong backend the host steers an xdpw chooser nobody is reading. Pin it for your session by creating~/.config/xdg-desktop-portal/sway-portals.conf:[preferred] default=gtk org.freedesktop.impl.portal.ScreenCast=wlrThen
systemctl --user restart xdg-desktop-portal. On a box with only xdpw installed there is nothing to choose between, so you can skip this.
Start the host
With the backend selected, start the host from inside your Sway session:
systemctl --user enable --now punktfunk-host
journalctl --user -u punktfunk-host -f
This unit runs the secure native-only host. To also serve stock Moonlight
clients, GameStream compat is opt-in (PUNKTFUNK_GAMESTREAM=1 in host.env, trusted LANs only) —
see What the unit starts.
Bring up the console and pair
Enable the web console, read its login password, and arm PIN pairing — see The Web Console. Then connect a client.