enricobuehlerandClaude Fable 5
dfcc530ee7
Phase 2 of the docs-and-onboarding overhaul (items 1-partial, 2 and 4 of the handoff): install.sh: --uninstall reverses step 1 + step 6 per family (user units off first, only the punktfunk packages actually installed, then the repo; config/groups/firewall stay, as /docs/uninstall states) — smoke-tested as a new installer-smoke step on all three families. The end-of-run check now catches the two NVIDIA silent failures on every family: no driver at all, and a module the kernel refused to load (Secure Boot) via an nvidia-smi probe pointing at the troubleshooting anchor; the Fedora ffmpeg-libs/NVENC warning folds into the same block. check-docs-drift.sh gate 7: the manual 16-file os-release matrix PR #345 was verified with, committed — every family's detection, its install line, its removal line and the four unsupported pointers run through the real script under --dry-run on every push (docs-drift's container gains curl, the script's own prerequisite). Screenshots (RFC: "screenshots over prose"): four console shots captured from the same storybook-fixture pipeline web-screenshots.yml runs — login and the armed Pairing page into quickstart.md, the Approve dialog (access level + expiry + guest fast-path) into pairing.md replacing the prose that described it, live status into web-console.md. Files under docs-site/public/img/, dark-theme, bundled+preloaded by the docs build (verified served). Still missing: a client host-list shot — linux-client-screenshots run 19546 built it, but its artifact isn't API-downloadable; add it when a browser session can fetch the zip. WP5 rider: the release-flow docs-freshness step now includes the website content look-over. NOT flipped: installer stays preview — the handoff gates the default flip on real-box mileage (Bazzite above all), which a Mac can't provide. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
3.7 KiB
title, description
| title | description |
|---|---|
| Pairing & Trust | Admit a new device once — approve it from the web console or type a PIN — and it reconnects on its own from then on. |
Punktfunk has no accounts and no cloud. A new device is let in once, by you, on your network; after that it reconnects automatically on a pinned identity, and the host lists it until you remove it. There are two ways to let a device in.
Approve it from the console (no PIN)
The fastest way: just connect from the new device. The attempt shows up in the web console under Pairing → Waiting for approval, with the device's name and fingerprint. Click Approve — optionally give it a label like "Living Room TV" — and it's paired on the spot; its next connect goes straight through.
Deny only dismisses the request (it can knock again; it isn't a blocklist). Requests expire on their own after 10 minutes.
Pair with a PIN
When you're at the device and the console isn't handy, or for the very first device: in the console open Pairing and click Pair a device. The host shows a 4-digit PIN and counts down a 2-minute window — type the PIN into the client:
- Native apps (Apple, Linux, Windows, Android): select the host, or Pair with PIN… from its menu, and enter it.
- Steam Deck (Decky plugin): pick the host in the Quick Access panel — an unpaired one offers Request access (the console approval above) or Use a PIN instead.
- Moonlight: it runs the other way round — Moonlight shows a PIN, and you type it into the console's Moonlight (GameStream) pairing card. Arming doesn't apply. (Moonlight needs GameStream compat on first.)
If the window lapses, arm it again. A punktfunk:// link can't pair for you — it only starts a
stream on a host this device already trusts.
Choosing access when you admit a device
Approving and deciding what the device may do are one dialog:
The levels are Full control, Controller only and View only (Advanced opens the individual toggles — Access levels); expiry is Never or 1 h / 4 h / 8 h / custom. The defaults are right for your own new laptop; Approve as guest is for a friend's device — Controller only, for 4 hours, then it expires on its own. The same two controls sit on the Pair a device card, and apply to whichever device completes the PIN.
Managing paired devices
The console lists every paired device with its access (and a live countdown for temporary grants). From there you can change the level, extend or cut the expiry, or remove the device — removing revokes it immediately, even mid-session. Re-pairing a removed device is just the PIN ceremony again.
Can't pair at all? Troubleshooting → Pairing is rejected.
How it works, briefly
Each host has a stable identity (a certificate); clients pin its fingerprint, the host stores the
client's. The PIN ceremony is SPAKE2, so someone who doesn't know the PIN gets one online guess and
no offline attack. A host whose fingerprint changes is treated as an impostor — the client forces a
fresh PIN ceremony rather than re-trusting it. Pairing is required by default; the reduced-security
alternatives (serve --open, trust-on-first-use) exist for fully trusted single-user networks and
are covered in Security & Safe Use.
Scripts can pair from a terminal — the punktfunk CLI.