enricobuehlerandClaude Opus 5
d383161723
ci / rust (push) Failing after 2m31s
ci / docs-site (push) Successful in 1m22s
ci / web (push) Successful in 1m48s
docker / builders (--build-arg FEDORA_VERSION=44, ci/fedora-rpm.Dockerfile, punktfunk-fedora44-rpm, -f44) (push) Successful in 1m1s
ci / rust-arm64 (push) Successful in 2m2s
docker / builders (ci/android-ci.Dockerfile, punktfunk-android-ci) (push) Successful in 11s
docker / builders (ci/arch-ci.Dockerfile, punktfunk-arch-ci) (push) Successful in 9s
docker / builders (ci/fedora-rpm.Dockerfile, punktfunk-fedora-rpm) (push) Successful in 9s
docker / builders (ci/rust-ci-noble.Dockerfile, punktfunk-rust-ci-noble) (push) Successful in 9s
docker / builders (ci/rust-ci.Dockerfile, punktfunk-rust-ci) (push) Successful in 9s
docker / builders-arm64cross (push) Successful in 20s
docker / apps (., web/Dockerfile, punktfunk-web) (push) Canceled after 36s
docker / apps (docs-site, docs-site/Dockerfile, punktfunk-docs) (push) Canceled after 36s
docker / deploy-docs (push) Canceled after 0s
~1150 feat/fix commits landed since v0.19 and the docs drifted badly. This is a full sweep of every page against the code as shipped: ~280 verified corrections, nine new pages, and one deletion. The worst of what was wrong: the quickstart's five-minute path could not work (`serve` never started the web console, so step 3 had no PIN to read); every packaged Linux host runs `serve --gamestream` while security.md told readers to leave GameStream off; HDR was documented as Windows-only; `PUNKTFUNK_SECURE_DDA` was documented as a working knob that nothing reads; `PUNKTFUNK_INPUT_BACKEND` listed a `uinput` value that does not exist and named libei for KDE instead of kwin; README linked three pages deleted on 2026-07-05; and the rpm-ostree update command pointed at a script no package installs. Completeness: about half of what shipped since v0.19 had no page at all. New: support-matrix (what works where, from 217 verified capability cells), input (mouse/touch/pen — and the in-stream chords, so the docs finally say how to get your mouse back), client-settings, profiles-and-links, game-library, clipboard, wake-on-lan, hdr, uninstall. Updating existed but had zero inbound links. status.md is gone: its facts moved into the support matrix, its shell stays as a redirect so the public URL does not 404. roadmap.md is themes now, not a feature checklist — checkboxes are what rotted. Debian is no longer claimed. The .deb's Depends resolve against Ubuntu images, nothing in CI builds or tests Debian, and Debian 12 is below the glibc 2.39 floor. The `debian` in the repo URL is the package format. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
140 lines
6.8 KiB
Markdown
140 lines
6.8 KiB
Markdown
---
|
|
title: Quick Start
|
|
description: From nothing to streaming — set up a host and connect your first client.
|
|
---
|
|
|
|
This is the shortest path to a working stream. Each step links to the details.
|
|
|
|
> A streaming host is remote control of the machine, so it's built for **trusted local networks** — keep
|
|
> it on your LAN or a VPN and don't expose it to the internet. Two minutes on
|
|
> [Security & Safe Use](/docs/security) before you start is worth it.
|
|
|
|
## 1. Set up the host
|
|
|
|
On your gaming machine (NVIDIA, AMD, or Intel GPU), follow the install guide for your system:
|
|
|
|
- [Ubuntu](/docs/ubuntu)
|
|
- [Fedora](/docs/fedora)
|
|
- [Arch](/docs/arch)
|
|
- [Bazzite](/docs/bazzite)
|
|
- [SteamOS](/docs/steamos-host)
|
|
- [Windows host](/docs/windows-host)
|
|
|
|
Each one covers the GPU driver, the dependencies, and how to install and run the host. After
|
|
installing, configure for your desktop ([KDE](/docs/kde) / [GNOME](/docs/gnome) /
|
|
[gamescope](/docs/gamescope) / [Hyprland](/docs/hyprland) / [Sway](/docs/sway)). Check the
|
|
[Requirements](/docs/requirements) first if you're not sure your machine is a fit.
|
|
|
|
## 2. Start the host
|
|
|
|
**On Windows there's nothing to start.** The installer registered and started the `PunktfunkHost`
|
|
service, so the host is already running and comes back on every boot. Confirm it:
|
|
|
|
```powershell
|
|
Get-Service PunktfunkHost
|
|
```
|
|
|
|
Don't run `punktfunk-host serve` on top of it — a second host process refuses to touch the
|
|
virtual-display driver and collides with the service on its ports. Details:
|
|
[Running as a Service → Windows](/docs/running-as-a-service#windows).
|
|
|
|
**On Linux you don't run the host by hand either.** Every Linux package ships a systemd **user** unit.
|
|
That unit reads `~/.config/punktfunk/host.env` and won't start until the file exists, so put it in
|
|
place first — your distro and desktop pages (step 1) have the template to copy and what to put in it.
|
|
Then enable the unit once, from a terminal **inside your desktop session**, and it comes back at
|
|
every login:
|
|
|
|
```sh
|
|
systemctl --user enable --now punktfunk-host
|
|
journalctl --user -u punktfunk-host -f # watch it come up and print its identity fingerprint
|
|
```
|
|
|
|
Once up, the host advertises itself on your local network, so clients find it by name. It works out
|
|
where your compositor is by itself, so there is nothing to export.
|
|
|
|
That unit runs `serve --gamestream`: the native `punktfunk/1` plane **plus** the
|
|
GameStream/Moonlight-compatible planes, so stock [Moonlight](/docs/moonlight) clients work too. Those
|
|
extra planes pair over plain HTTP and belong on a trusted LAN only — for a native-only host, see
|
|
[What the unit starts](/docs/running-as-a-service#what-the-unit-starts).
|
|
|
|
If the host runs a firewall (Fedora enables firewalld, CachyOS enables ufw), open its ports — the
|
|
firewall step in your distro guide has the exact commands, for **both** `punktfunk-native` and
|
|
`punktfunk-gamestream`, because the packaged unit serves both planes.
|
|
|
|
On **SteamOS** even that is done for you — the install script wrote its own `punktfunk-host` user
|
|
service and started it (GameStream on by default there too; pass `--no-gamestream` to the install
|
|
script for a native-only host). Check it with `systemctl --user status punktfunk-host`.
|
|
|
|
## 3. Open the web console
|
|
|
|
The console is a **separate** process from the host, and you need it in the next step — arming PIN
|
|
pairing is done there.
|
|
|
|
- **Windows:** the installer already set it up and starts it at boot. Open
|
|
`https://<host-ip>:47992`. The login password is the one the installer showed you on its final
|
|
page; it's stored in `%ProgramData%\punktfunk\web-password`.
|
|
- **Linux:** on Ubuntu, Fedora and Bazzite the `punktfunk-web` package comes in with the host
|
|
but isn't enabled for you. On Arch it's an optional dependency, so install it first
|
|
(`sudo pacman -Syu punktfunk-web` — a full `-Syu`, never a bare `-S`). Either way, start it as
|
|
your desktop user, then open `https://<host-ip>:47992`:
|
|
|
|
```sh
|
|
systemctl --user enable --now punktfunk-web
|
|
sed -n 's/^PUNKTFUNK_UI_PASSWORD=//p' ~/.config/punktfunk/web-password
|
|
```
|
|
|
|
The second command prints the login password generated on first start.
|
|
- **SteamOS:** the install script already started the console and printed its URL when it finished.
|
|
It generated the login password into `~/.config/punktfunk/web.env`.
|
|
|
|
The certificate is the host's own self-signed one, so your browser warns once — trust it and
|
|
continue. Full details: [The Web Console](/docs/web-console).
|
|
|
|
## 4. Connect and pair a client
|
|
|
|
On the device you want to stream to, use a [native Punktfunk client](/docs/clients) for the lowest
|
|
latency, or any Moonlight client:
|
|
|
|
- **Native client (Apple, Linux, Windows, Android):** install it first —
|
|
[Install a Client](/docs/install-client) has the download for every device (Steam Deck: the
|
|
[Decky plugin](/docs/steam-deck)). Then open the Punktfunk app — your host appears in the list of
|
|
hosts found on your network. Select it, and when prompted, **pair**.
|
|
- **Anything with Moonlight:** add the host (it should be discovered automatically), then pair.
|
|
|
|
To pair, the host needs to show a PIN. [Arm pairing](/docs/web-console#arm-pairing) from the web
|
|
console you opened in step 3 — the host displays a 4-digit PIN, you type it into the client, and they
|
|
trust each other from then on. Pairing is required by default. Full details:
|
|
[Pairing & Trust](/docs/pairing).
|
|
|
|
## 5. Stream
|
|
|
|
Once paired, select the host and start streaming. The host creates a virtual display at your device's
|
|
resolution and refresh, and the picture comes up. Mouse, keyboard, and controllers flow back to the
|
|
host.
|
|
|
|
Worth knowing before you need it: on the desktop clients the stream *takes* your mouse and keyboard
|
|
when it starts, and again whenever you click into it. **Ctrl+Alt+Shift+Q** (**⌃⌥⇧Q** on macOS) hands
|
|
them back. The other in-stream shortcuts, and the mouse, touch and pen modes, are on
|
|
[Mouse, touch and pen](/docs/input).
|
|
|
|
## Now that it works
|
|
|
|
Punktfunk does more than mirror a screen:
|
|
|
|
- Browse the host's installed games and launch one straight into the stream —
|
|
[Game library](/docs/game-library).
|
|
- Save named stream settings, bind them to a host, and start a session from a shortcut or a script —
|
|
[Profiles and links](/docs/profiles-and-links).
|
|
- Copy on one machine and paste on the other — [Shared clipboard](/docs/clipboard).
|
|
- Connect to a host that's asleep — [Wake-on-LAN](/docs/wake-on-lan).
|
|
- Get a 10-bit HDR picture where the whole chain allows it — [HDR](/docs/hdr).
|
|
|
|
## Keep it running
|
|
|
|
- Tune the picture — resolution, refresh, bitrate, codec and HDR are all
|
|
[client settings](/docs/client-settings); the host's own knobs are in
|
|
[Configuration](/docs/configuration).
|
|
- Make it always-on — no login, no monitor: [Running as a Service](/docs/running-as-a-service).
|
|
- Keep it current with [Updating](/docs/updating); changed your mind? [Uninstall](/docs/uninstall).
|
|
- Hit a snag? See [Troubleshooting](/docs/troubleshooting).
|