enricobuehlerandClaude Opus 5
365caa23be
A user could not get the VirtualHere plugin to use their VirtualHere client and asked, reasonably, where the logs were. There was no good answer, and the reason they were stuck turned out to be ours. **The runner could not see /tmp.** `punktfunk-scripting.service` set PrivateTmp=yes, which hands the unit a private tmpfs. But integrating with things already running on the box is the entire job of a plugin, and on Linux those talk over /tmp: VirtualHere's client IPC is the FIFO pair /tmp/vhclient + /tmp/vhclient_response, X11 is /tmp/.X11-unix. So the plugin launched the vendor binary happily and could then never reach the daemon behind it — while the same command worked perfectly in the operator's own shell, because that shell has the real /tmp. No config change could fix it, which is exactly the loop the report described. PrivateTmp is now off, with /tmp added to ReadWritePaths (which ProtectSystem=strict would otherwise make read-only). **Plugin logs now land in the console.** Plugins are not host child processes — the runner is a separate bun process that import()s each plugin in-process — so nothing they print passed through the host's tracing, and the console's Logs page could not show a single plugin line. The fallback was journalctl on Linux; on Windows the runner's scheduled task writes no log file at all, so a failing plugin was diagnosable only by stopping the task and re-running the runner by hand. Both mean shell access on the host box, which is what the console exists to avoid — and it left the one question a stuck user asks with no answer. So the runner now tees its output to POST /api/v1/plugins/logs, and those lines join the host's own ring under one cursor, targeted plugin:<name>. The console grows a Host/Plugins switch beside the level filter; an empty Plugins view says the thing that is actually usually wrong (the runner isn't running) rather than "adjust the filter". The shipper keeps stdout authoritative — journald and foreground output are unchanged whatever the host is doing — and is built so that logging can never hurt the thing being logged: it never throws into a caller, holds a bounded queue that drops oldest and then says how many, backs off when the host is away (a restart is normal), and re-sends a batch the host failed to take. Lines logged while a POST is in flight are kept, which cost one round to get right: the first version held its recursion guard across the await and silently dropped exactly the lines a busy plugin produces. Runner lines that report a failure (a refused unit file, a crashed plugin, a give-up) now go out at warn/error instead of all arriving as INFO, so the console's level filter means something for them. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
6.2 KiB
title, description
| title | description |
|---|---|
| The Web Console | Enable the Punktfunk browser console, read or change its login password, arm PIN pairing, and what every page in it does. |
The web console is the browser UI for a Punktfunk host — live status, pairing, display policy, the
game library, logs, plugins and host updates. It ships as the punktfunk-web systemd user unit
on Linux and runs under the Punktfunk Host service on Windows, and serves on https://<host-ip>:47992
(HTTPS with the host's own self-signed identity cert — your browser warns once; trust it and
continue). It's the surface you expose on the LAN to administer the host; the host's own management
API (47990) keeps every admin action loopback-only and off-loopback serves only read-only status +
game-library browsing to paired clients.
New here? Read Security & Safe Use first — a streaming host is remote control of the machine, so keep it on a trusted LAN or VPN and require pairing.
Enable the console
-
Linux packages (apt / RPM / Bazzite): on Ubuntu the host package is
punktfunk-hostand on Fedora/Bazzite it'spunktfunk; either way it recommendspunktfunk-web, so your package manager pulls the console in with the host (the Bazzite sysext image already contains it). Enable and start it as your desktop user, then open the URL:systemctl --user enable --now punktfunk-web # then browse to https://<host-ip>:47992 -
Arch / CachyOS (pacman): the console is an optional package here, and pacman never installs optional dependencies — so install it yourself from the same repo the host came from (see Arch Linux), then enable it exactly as above. Take it as a full
-Syu, never a barepacman -S, so you don't end up on a partial upgrade:sudo pacman -Syu punktfunk-web systemctl --user enable --now punktfunk-web -
Windows host: the installer sets up the console and its runtime; the Punktfunk Host service runs it and automatically brings it back if it ever stops. There is nothing to enable — open
https://<this-PC>:47992. -
SteamOS host: the install script builds and starts the console as a user service for you. It prints the URL when it finishes.
Login password
The console is password-protected. Where that password lives and how you change it depends on the host platform.
Linux packages (apt / RPM / Bazzite). On first start punktfunk-web-init generates a random
password and saves it to ~/.config/punktfunk/web-password (as PUNKTFUNK_UI_PASSWORD=…). Read it
back from the init service's journal or straight from the file:
journalctl --user -u punktfunk-web-init | sed -n 's/.*password generated: //p'
sed -n 's/^PUNKTFUNK_UI_PASSWORD=//p' ~/.config/punktfunk/web-password
To set your own, edit that file (PUNKTFUNK_UI_PASSWORD=<your-password>) and restart the console:
systemctl --user restart punktfunk-web.
SteamOS host. Same idea, but the install script writes the generated password to
~/.config/punktfunk/web.env and prints it at the end of the install run:
sed -n 's/^PUNKTFUNK_UI_PASSWORD=//p' ~/.config/punktfunk/web.env
Edit that file and systemctl --user restart punktfunk-web to change it.
Windows host. You choose the password during install — a secure random default is pre-filled and
shown again on the installer's final page. It's stored in %ProgramData%\punktfunk\web-password (as
PUNKTFUNK_UI_PASSWORD=…), readable only by Administrators and SYSTEM. To change it, edit the file
and restart the Punktfunk Host service (which runs the console) in an elevated PowerShell:
notepad "$env:ProgramData\punktfunk\web-password" # set PUNKTFUNK_UI_PASSWORD=<your-password>
punktfunk-host service restart
Forgot it? See Forgot your Password?.
Arm pairing
The host requires PIN pairing by default (secure on a LAN). To connect the first time, open the console, log in, then open Pairing in the sidebar and click Pair a device. The host shows a one-time 4-digit PIN — enter it on your client to pair. If the device already tried to connect it appears under Waiting for approval instead; approving it pairs it immediately, no PIN needed. See Pairing & Trust for the full trust model and how to approve or remove devices later.
What's in it
Nine destinations in the sidebar (a More tab on a phone holds the last five):
- Dashboard — live status: whether video and audio are streaming, the active sessions with their codec, resolution, frame rate and bitrate, which games are running, and how many clients are paired. Buttons here stop a session or ask the encoder for a fresh keyframe.
- Host — this host's identity (hostname, OS, local IP, version, unique id), the codecs it advertises, its ports, the Updates card (see Updating the Host), the GPUs card — Automatic, or prefer one GPU for capture and encode, applied to the next session — and the compositor backends it found.
- Virtual displays — the policy for the display each session gets, and the Streamed screen picker. See Virtual displays.
- Library — the games every client sees: turn a launcher source on or off, add or edit a custom title with its own art and launch command. See Your game library.
- Performance — arm a capture, run a session, stop it, and read the recording back as per-stage latency, throughput and health graphs.
- Logs — the host's recent log stream and your plugins': follow it live, filter by level or
producer, search it, and download or share it for a bug report. Plugin lines are tagged
plugin:<name>and the Host / Plugins switch isolates either side. - Pairing — arm a PIN, approve or deny devices waiting for approval, and unpair a device. A second PIN box for Moonlight/GameStream clients appears only when this host runs the GameStream plane.
- Plugins — the plugin store's Browse, Installed and Sources tabs plus the plugin runner switch; an installed plugin with a UI gets its own entry below. See Plugins.
- Settings — the console's language, and Sign out.