punktfunk/docs-site/content/docs/host-cli.md

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.

detect-conflicts

punktfunk-host detect-conflicts reports other Moonlight-compatible hosts (Sunshine, Apollo, and forks) installed or running on this machine. Running one alongside Punktfunk is unsupported — they fight over the same ports and virtual-display driver. Prints what it found and exits 1 if any conflict exists, 0 if clean (so installers and scripts can gate on it). The host also runs this check at serve startup and surfaces it in the logs, tray, and — on Windows — the installer. See Troubleshooting → another streaming host is installed.

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.