enricobuehler
1dc8dc7f0d
apple / swift (push) Successful in 1m11s
rpm / build-publish (43, bazzite, punktfunk-fedora-rpm) (push) Has been cancelled
rpm / build-publish (44, fedora-44, punktfunk-fedora44-rpm) (push) Has been cancelled
docker / build-push (--build-arg FEDORA_VERSION=44, ci, ci/fedora-rpm.Dockerfile, punktfunk-fedora44-rpm) (push) Has been cancelled
docker / build-push (., web/Dockerfile, punktfunk-web) (push) Has been cancelled
docker / build-push (ci, ci/fedora-rpm.Dockerfile, punktfunk-fedora-rpm) (push) Has been cancelled
docker / build-push (ci, ci/rust-ci.Dockerfile, punktfunk-rust-ci) (push) Has been cancelled
docker / build-push (docs-site, docs-site/Dockerfile, punktfunk-docs) (push) Has been cancelled
docker / deploy-docs (push) Has been cancelled
decky / build-publish (push) Has been cancelled
deb / build-publish (push) Has been cancelled
ci / rust (push) Has been cancelled
ci / web (push) Has been cancelled
ci / docs-site (push) Has been cancelled
ci / bench (push) Has been cancelled
android / android (push) Successful in 3m49s
apple / screenshots (push) Has been cancelled
arch / build-publish (push) Has been cancelled
The mgmt REST API has bound 0.0.0.0:47990 by default since ae51276 so paired
clients can browse the game library over mTLS, but every packaged firewall
opener still excluded 47990 and the docs still claimed it was loopback-only.
On any host with an active firewall (ufw/firewalld) the LAN game-library
feature was silently broken.
Add 47990/tcp to the native firewall profiles (punktfunk.ufw [punktfunk-native]
+ punktfunk-native.xml) and correct the stale "loopback-only by default" text
across the debian/arch/bazzite READMEs and the docs site (incl. the factually
wrong --mgmt-bind default in host-cli.md, 127.0.0.1 -> 0.0.0.0). Opening the
port adds no admin exposure: off-loopback mgmt::require_auth serves only the
read-only status/library allowlist to a paired client cert; the bearer-token
admin surface stays loopback-only regardless of the bind.
Windows was already sound (shared parse_serve binds 0.0.0.0; service.rs already
firewall-opens 47990) — add a clarifying comment so the rule isn't mistaken for
accidental over-exposure.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
85 lines
4.6 KiB
Markdown
85 lines
4.6 KiB
Markdown
---
|
|
title: Host CLI
|
|
description: 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`](/docs/configuration).
|
|
|
|
## `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.
|
|
|
|
```sh
|
|
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](/docs/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.
|
|
|
|
```sh
|
|
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. |
|
|
|
|
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**](/api).
|
|
|
|
By default the host **requires pairing** — see [Pairing & Trust](/docs/pairing). 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). The pairing flags below are `punktfunk1-host`-only and do **not** apply to `serve`.
|
|
|
|
## `punktfunk1-host`
|
|
|
|
A standalone native-only host, mainly for testing the `punktfunk/1` path without the GameStream server
|
|
or web console.
|
|
|
|
```sh
|
|
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-pairing` | Accept PIN pairing; the host prints a PIN when a client pairs. |
|
|
| `--require-pairing` | Only serve paired devices (implies `--allow-pairing`). |
|
|
|
|
`--max-concurrent`, `--allow-pairing`, and `--require-pairing` are **`punktfunk1-host`-only** — `serve` does not
|
|
accept them. On `serve` you arm pairing from the web console instead, 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`.
|
|
|
|
## Environment
|
|
|
|
Most behaviour (compositor, video source, input backend, zero-copy) is set in
|
|
[`host.env`](/docs/configuration), not on the command line. When running as a
|
|
[service](/docs/running-as-a-service), the unit loads `host.env` for you.
|