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. On the machine you stream to, there's a second command — punktfunk, which ships with the client.

punktfunk-host --help prints the most-used of these. plugins, service, driver and tray print their own usage when you run them with no arguments.

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.

ctl

Drive a running host from a terminal: approve a device, type a Moonlight PIN, rename or unpair, stop a session, watch events. Everything the web console does day to day, without a browser — and everything it does is the same management API the console talks to, over loopback.

punktfunk-host ctl status
punktfunk-host ctl pending
punktfunk-host ctl approve 3

display lists live and lingered heads on Hyprland. A reconnect inside keep-alive recasts the same named output, so the list is the truth. Sway still reports an empty displays list — its capture arrives over a sandboxed portal handle the host cannot re-open per attach, so the registry passes those displays through rather than owning them. Read Sway's empty list as this host does not track them, not as "nothing is streaming". Omarchy is Hyprland, so ctl display there lists the lingered heads.

Reading stats

Two numbers named alike measure different things, and the gap between them is large:

• Target is the encoder's bitrate, where adaptive bitrate has settled. It is always available.
• Sent is what actually left the box. It only exists while a capture is recording.

A still desktop shows 300 Mbps of target against 11 Mbps sent, because capture is damage-driven: nothing changed, so nothing was encoded. For the same reason stats prints new frames per second beside repeated ones. A healthy 240 Hz stream of a motionless screen reads 0.0 fps new · 157.2 fps repeated; reading only the first number would say the stream was dead.

Add --json to any verb for machine-readable output: {"v":1,"data":…} on success, {"v":1,"error":{"code":…,"message":…}} on failure, both on stdout. That envelope is the contract — the tables above are for humans and are not stable.

Exit codes

Watching events

watch holds one long-lived connection and reconnects by itself, which makes it the right shape for a status widget or a script. It starts at the live tail; --since 0 replays the host's ring and --since <seq> resumes after an event you saw:

punktfunk-host ctl watch --kinds pairing.pending,stream.'*' | while read -r line; do
  echo "$line"
done

Two synthetic lines are ours rather than the host's:

• {"v":1,"kind":"ctl.resync"} — the stream fell behind the host's catch-up ring, so anything you believe about pending devices or live sessions may be stale. Re-run ctl status / ctl pending instead of trusting your incremental state.
• {"v":1,"kind":"ctl.disconnected","data":{"error":…}} — the connection dropped; a reconnect is already in progress.

The host caps concurrent event streams (the console holds one); past the cap you get a 503 with the host's own message and exit 1.

How it authenticates

ctl reads two files from the host's config directory (~/.config/punktfunk, mode 0700) and nothing else:

• mgmt-token — the operator token the host mints for itself on first start, the same one the web console uses. ctl consumes it and never creates one: a missing token is an error, not a prompt.
• native-cert.pem (or cert.pem on older hosts) — the host's own certificate, which ctl pins before sending the token. If the process answering on the management port presents anything else, the connection fails during the TLS handshake and no credential is ever transmitted — that is exit code 4.

There is deliberately no --token flag and no token environment variable. A credential on a command line or in an environment is readable by other processes on the box through /proc/<pid>/cmdline and /proc/<pid>/environ, which is exactly what the 0700 config directory exists to prevent. The consequence worth knowing: a host started with --mgmt-token (or PUNKTFUNK_MGMT_TOKEN) and no persisted token file cannot be reached by ctl. Every packaged install persists one, so this only affects hand-run dev hosts.

Everything runs over loopback, because the management API honours the admin surface from loopback peers only — ctl adds no listener and no new way in.

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. The graphical client browses the LAN for you, so it needs no command; from a terminal on the client machine, punktfunk hosts list --probe re-checks the hosts you have already saved by asking each one directly — which is how you confirm a routed or VPN host that mDNS never reaches. (punktfunk-probe --discover also browses the LAN, but it is a developer tool built from the repo, cargo run -p punktfunk-probe -- --discover, and no package installs it.) 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.

service (Windows)

The Windows lifecycle surface. The installer runs service install for you, so you only need these when you change something or when the service needs a nudge. Run them from an Administrator prompt.

punktfunk-host service install [--gamestream=on|off] [--allow-public-network]
punktfunk-host service uninstall
punktfunk-host service start | stop | restart | status

See Running as a Service and Windows Host.

tray (Windows)

The status tray is a per-user program started at sign-in, so an update or a crash otherwise leaves you without the icon until the next logon. This is how you get it back without signing out:

punktfunk-host tray start
punktfunk-host tray status
punktfunk-host tray stop

start reports the process it started, or says the tray is already running; status says whether the tray is installed at all (it's an optional component at install time) and whether it's running.

driver (Windows)

The installer installs and removes the bundled drivers, so you rarely touch this. It exists for removing one without uninstalling the host:

punktfunk-host driver uninstall            # the pf-vdisplay virtual display driver
punktfunk-host driver uninstall --gamepad  # the virtual-gamepad driver instead

driver install --dir <stage> [--gamepad] is the install half; it takes the staged driver files the installer lays down, which is why it isn't something you run by hand.

web (Windows)

Print the web console login password, from an elevated PowerShell — the file it reads is ACL'd to Administrators and SYSTEM, so an ordinary prompt gets access denied:

punktfunk-host web password

This is how you get the password after a silent install (winget, /VERYSILENT), which generates one and displays nothing. The wizard shows it on its final page instead, so you only need this later. web setup is the install half and takes the staged console payload, so it isn't run by hand.

plugins

punktfunk-host plugins add|remove|list|enable|disable|status installs plugins and switches the plugin/scripting runner on — the same thing the web console's Plugins page does. Plugins run with the host's privileges, so read Plugins before installing one.

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.

hdr-probe and probe-compositor

Two Linux readiness checks that need no client and no session of their own.

punktfunk-host hdr-probe
punktfunk-host probe-compositor

hdr-probe answers "why isn't my stream HDR?" — it reports, for both Linux HDR routes, whether the box can deliver 10-bit PQ right now: is a monitor in HDR colour mode (the GNOME monitor-mirror route), is the resolved gamescope the punktfunk-gamescope build with the knob on, and does the encoder probe Main10 for HEVC/AV1. Run it with the same environment the host service has, or the answers describe your shell rather than the host — HDR → Check it has that one-liner and reads the output line by line. See HDR on gamescope for the gamescope half.

probe-compositor exits 0 only when the compositor is up and can create a virtual output now — what a session-bringup script should gate on instead of a blind sleep.

There is no hdr-probe on Windows. The Windows equivalent is a GPU colour self-test of the HDR capture conversion — it needs no display and no session, and prints PASS or FAIL with the largest error it saw:

punktfunk-host hdr-p010-selftest 1920x1080 nvidia

Both arguments are optional: your real capture size (heights like 1080 aren't 16-aligned and take a different driver path — the default is a token 64x64) and, on a dual-GPU box, the vendor that encodes: intel, nvidia or amd.

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 reports it in the logs and in the management API's status summary; on Windows the installer warns you before it installs. (The tray stays quiet about it on purpose — an installed-but-idle Sunshine isn't a conflict until it runs.) See Troubleshooting → another streaming host is installed.

punktfunk on the client machine

The client half has its own command, punktfunk — the same core the graphical apps use, with no window, so a script gets what a click gets, including waking a sleeping host and waiting for it.

Its verbs, where it ships, the <host-ref> grammar and the stable exit codes are on Clients → the punktfunk CLI; punktfunk help <command> prints one verb's flags. punktfunk wake has its own exit codes, on Wake on LAN → From the command line.

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.