enricobuehler
ef39050dbc
Six parallel audits swept the root docs, docs-site, every per-directory README, and the packaging docs; every claim below was verified against the source before editing. - README: Layout gains the six missing crates (pf-client-core, pf-presenter, pf-console-ui, pf-ffvk, pf-driver-proto, punktfunk-tray), clients/session, api/ and ci/; Linux/Windows client rows reflect the shell + Vulkan-session split and the Vulkan Video -> VAAPI/D3D11VA -> software decode chains; the "every client over a C ABI" claim is corrected (Rust clients link the core directly); tiered stats overlay + console shell noted; Apple row mentions AV1. - CONTRIBUTING: drop the dead CLAUDE.md link (deliberately untracked); point at the README's build/invariants sections. SECURITY: 0.9.0. - host-cli/pairing: --allow-pairing/--require-pairing are no-op legacy names — pairing is required by default, --allow-tofu is the real flag; document --data-port and --idle-timeout-ms. - configuration: document PUNKTFUNK_RECOVER_SESSION_CMD (session-crash recovery hook), PUNKTFUNK_MDNS, PUNKTFUNK_DATA_PORT. - virtual-displays/gnome: GNOME per-client scaling shipped (host- persisted) — flip the ❌ to ✅ and describe how it works. - stats: new "Detail levels" section (Off/Compact/Normal/Detailed + per-platform cycle gestures); retire the GTK hand-off note. - clients/install-client/status/roadmap: decode chains, Windows client validation narrowed to HDR-only pending, adaptive bitrate, console shell, Apple AV1, Windows host vendor list. - Sub-READMEs: clients/linux rewritten for the re-architecture; session Windows decode rung + d3d11va knob; Windows tiered overlay; Android minSdk 28; decky file table; host zerocopy/ path; scripts port 47992 and steamos-host.md; pf-dualsense source path. - packaging: canary version bases are tag-derived (<next-minor> via pf-version.sh/.ps1), codecs-extra not ffmpeg-full, document the pinned offline-Skia tarball + SKIA_BINARIES_URL and vulkan-headers. - Convert 15 dangling design/*.md links to the punktfunk-planning prose convention (those docs live in the private planning repo). Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
5.8 KiB
title, description
| title | description |
|---|---|
| Host CLI | The punktfunk-host commands and the flags you'll actually use. |
The host is one binary, punktfunk-host. Most of the time you'll run a single command; the rest reads
its settings from host.env.
serve
The normal way to run a host. By default serve starts the secure native host: the native
punktfunk/1 server (QUIC, SPAKE2 PIN pairing, per-direction AEAD) plus the management API/web
console — all in one process. The native plane is always on; there is no flag to turn it off.
punktfunk-host serve
Add --gamestream (alias --moonlight) to also run the GameStream/Moonlight-compatible planes
(nvhttp pairing, RTSP, ENet control, _nvstream mDNS) — required for stock Moonlight
clients. This is opt-in because GameStream carries inherent on-path weaknesses (pairing over plain
HTTP; its legacy control encryption can reuse GCM nonces), so enable it only on a trusted LAN. The
native plane is immune to those issues.
punktfunk-host serve --gamestream
| Flag | Meaning |
|---|---|
--gamestream / --moonlight |
Also run the GameStream/Moonlight-compat planes (for stock Moonlight clients). Opt-in, trusted-LAN only — see above. |
--native |
No-op. The native punktfunk/1 server always runs in serve; kept only for backward compatibility. |
--native-port <PORT> |
Native QUIC port (default 9777). |
--open |
Don't require pairing — serve any device on the network. Off by default; only for trusted single-user setups. |
--mgmt-bind <IP:PORT> |
Management API address (default 0.0.0.0:47990 — all interfaces, so paired clients can browse the game library over mTLS; pass 127.0.0.1:47990 to keep it loopback-only). |
--mgmt-token <TOKEN> |
Override the bearer token for the management API. |
--no-mdns |
Skip the mDNS adverts (native + GameStream) — for networks/containers where multicast doesn't work. Clients connect via a manually added host instead. Same as PUNKTFUNK_MDNS=0. |
--data-port <PORT> |
Pin the per-session video data plane to this fixed UDP port and stream direct (no hole-punch) — open exactly that port in the host firewall. Same as PUNKTFUNK_DATA_PORT; default is a random port + hole-punch. |
These are the only flags serve accepts.
The management API is always HTTPS. It binds all interfaces by default so a paired client can
fetch the game library over its mTLS certificate — but off loopback that certificate reaches only the
read-only status + library endpoints. The admin surface (arming pairing, removing devices, session
control, library edits) authenticates with a bearer token and is honored from loopback only, so
it is never LAN-exposed even under the default wide bind. If you don't pass --mgmt-token, a token is
auto-generated and persisted to ~/.config/punktfunk/mgmt-token (the bundled web console reads the same
file); --mgmt-token only overrides it. Pass --mgmt-bind 127.0.0.1:47990 to keep 47990 loopback-only.
Every endpoint is documented in the interactive API Reference.
By default the host requires pairing — see Pairing & Trust. On serve you
arm pairing from the web console (or mgmt API); the host then displays a 4-digit PIN. Pass --open to
turn off the mandatory-pairing default and serve any device on the network (trusted single-user setups
only). punktfunk1-host (below) requires pairing by default too; its --allow-tofu flag is the
test-host equivalent of --open.
punktfunk1-host
A standalone native-only host, mainly for testing the punktfunk/1 path without the GameStream server
or web console.
punktfunk-host punktfunk1-host --source virtual
| Flag | Meaning |
|---|---|
--port <N> |
QUIC listen port (default 9777). |
--source synthetic · virtual |
virtual uses a real virtual display + NVENC; synthetic emits test frames. |
--seconds <N> / --frames <N> |
Bound each session by wall-clock seconds or frame count. |
--max-concurrent <N> |
Stream at most N sessions at once (default 4); overflow waits in the queue. |
--max-sessions <N> |
Exit after N sessions (0 = serve forever). |
--allow-tofu |
Also accept unpaired clients (trust-on-first-use) and advertise pairing as optional. Pairing is required by default; trusted LANs only. (--allow-pairing/--require-pairing are the old names for the default behaviour and are accepted as no-ops.) |
--pairing-pin <PIN> |
Use a fixed pairing PIN instead of a fresh random one per ceremony. For test harnesses/CI only — a guessable PIN defeats the ceremony's rate limit. |
--data-port <PORT> |
Pin the video data plane to this fixed UDP port and stream direct (no hole-punch). Same as PUNKTFUNK_DATA_PORT. |
--idle-timeout-ms <MS> |
Disconnect-detection latency — the QUIC control-connection idle timeout (default 8000). |
--no-mdns |
Skip the _punktfunk._udp advert; clients use --connect HOST:PORT. Same as PUNKTFUNK_MDNS=0. |
--max-concurrent and --allow-tofu are punktfunk1-host-only — serve does not accept them.
On serve you arm pairing from the web console instead (--open is its serve-any-device switch),
and concurrency is fixed at the built-in default (4 sessions) rather than settable from the command
line.
Both serve and punktfunk1-host advertise the host on the network so clients can discover it. List
hosts from another machine with punktfunk-probe --discover. Where multicast doesn't work (some
Docker/VLAN setups), pass --no-mdns (or set PUNKTFUNK_MDNS=0) and add the host in the client by
address instead.
Environment
Most behaviour (compositor, video source, input backend, zero-copy) is set in
host.env, not on the command line. When running as a
service, the unit loads host.env for you.