Host CLI

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

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

--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.

list-monitors

punktfunk-host list-monitors prints the physical monitors this host's compositor has, by connector name — which is how you name one for Streamed screen (in the console, or as PUNKTFUNK_CAPTURE_MONITOR).

punktfunk-host list-monitors

Kwin:
  HDMI-A-1        1920x1080@60 at +0,+0    scale 1  Dell U2412M  [primary]
  DP-2            2560x1440@144 at +1920,+0  scale 1  ACME 27  [PINNED]

Tags flag what's worth knowing before you pick: primary, disabled (nothing to stream), punktfunk virtual display (one of ours, not a real head), and PINNED for the one currently selected. Linux only — it reads the live compositor, so run it in (or with the environment of) the session you want to stream.

punktfunk-host mirror-test --monitor <CONNECTOR> [--seconds N] [--cpu] then proves the whole path — mirror, capture, frames — with no client involved. It reports the first frame, the frame count and the negotiated size. Screen recording is damage-driven, so move the mouse on the host while it runs; an idle desktop legitimately yields almost nothing.

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.