enricobuehler
69fcb6e0b1
apple / swift (push) Successful in 1m8s
apple / screenshots (push) Successful in 5m33s
android / android (push) Successful in 4m43s
arch / build-publish (push) Successful in 5m38s
ci / web (push) Successful in 1m3s
ci / docs-site (push) Successful in 1m17s
ci / rust (push) Successful in 4m48s
ci / bench (push) Successful in 5m7s
decky / build-publish (push) Successful in 14s
docker / build-push (--build-arg FEDORA_VERSION=44, ci, ci/fedora-rpm.Dockerfile, punktfunk-fedora44-rpm) (push) Successful in 5s
docker / build-push (., web/Dockerfile, punktfunk-web) (push) Successful in 5s
docker / build-push (ci, ci/fedora-rpm.Dockerfile, punktfunk-fedora-rpm) (push) Successful in 3s
docker / build-push (ci, ci/rust-ci.Dockerfile, punktfunk-rust-ci) (push) Successful in 4s
deb / build-publish (push) Successful in 4m29s
docker / build-push (docs-site, docs-site/Dockerfile, punktfunk-docs) (push) Successful in 1m16s
rpm / build-publish (43, bazzite, punktfunk-fedora-rpm) (push) Successful in 10m24s
docker / deploy-docs (push) Successful in 6s
rpm / build-publish (44, fedora-44, punktfunk-fedora44-rpm) (push) Successful in 10m3s
Split the docs' single distro×desktop axis (ubuntu-gnome / ubuntu-kde / fedora-kde) into two,
which deduplicates the shared mechanics and scales to distros that run several desktops (Arch):
- Install the host — per distro/OS (ubuntu, fedora, arch, bazzite, steamos-host, windows-host):
GPU driver + package + input group, then a canonical "Configure your desktop" funnel.
- Configure your desktop — per compositor (kde, gnome, gamescope, sway): host.env, compositor
quirks, the headless session, and starting the host.
New shared web-console page (enable · login password · arm pairing) removes the console/password
block that was copy-pasted across all seven host pages. Merged ubuntu-gnome + ubuntu-kde into
ubuntu; renamed fedora-kde to fedora; kept bazzite and steamos-host as dedicated appliance guides
(trimmed of duplication). Moved the KWin headless session, the GNOME EGL/lock traps, and the
gamescope attach/managed model out of the distro pages onto their compositor pages.
Fixed while restructuring: distro-specific paths on kde (kde-desktop-setup.sh is Fedora/Bazzite-only;
the .deb ships host.env.kde under /usr/share/punktfunk-host), the interactive "start the host" step
that was lost in the merge, sway over-claiming Hyprland, and a pre-existing broken anchor in
how-it-works.
Removal of the three old pages was captured by the preceding commit 8ebb614 (a concurrent commit
swept up the staged git-rm); the net docs tree is correct. Fumadocs build + internal link/anchor
check green.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
161 lines
7.6 KiB
Markdown
161 lines
7.6 KiB
Markdown
---
|
|
title: Bazzite
|
|
description: Set up a punktfunk host on Bazzite — it follows the box between Steam Gaming Mode (gamescope) and the KDE Plasma desktop automatically.
|
|
---
|
|
|
|
[Bazzite](https://bazzite.gg/) already ships everything a punktfunk host needs — the NVIDIA driver,
|
|
NVENC, PipeWire, **gamescope**, and the **KDE Plasma desktop**. So a Bazzite host is the most
|
|
"appliance-like" setup, and it streams **both** of Bazzite's faces:
|
|
|
|
- **Steam Gaming Mode** (gamescope) — the couch/handheld game UI.
|
|
- **The KDE Plasma desktop** — the full desktop you get from "Switch to Desktop".
|
|
|
|
The host **auto-detects which one is live and follows the box across the switch** — including
|
|
mid-stream. You flip between Gaming Mode and Desktop with Bazzite's normal Steam UI /
|
|
"Switch to Desktop"; the host just re-targets whatever's running and keeps streaming. Nothing in
|
|
`host.env` forces a mode.
|
|
|
|
> Ideal for a dedicated game-streaming box that you also occasionally want as a remote desktop. For a
|
|
> pure desktop machine, install on [Ubuntu](/docs/ubuntu) or [Fedora](/docs/fedora) and configure the
|
|
> [KDE](/docs/kde) or [GNOME](/docs/gnome) desktop directly — simpler.
|
|
|
|
> New here? Read [Security & Safe Use](/docs/security) first — a streaming host is remote control of
|
|
> the machine, so keep it on a trusted LAN or VPN and require pairing.
|
|
|
|
## Install
|
|
|
|
The host installs as a **systemd system extension (sysext)** — no `rpm-ostree` layering. The
|
|
Bazzite docs treat layering as a last resort (layered packages slow every OS update and can block
|
|
upgrades until removed); a sysext never enters an rpm-ostree transaction: it overlays `/usr`
|
|
read-only from `/var/lib/extensions/`, survives OS updates, installs and updates **without a
|
|
reboot**, and is removable in one command. This is the same mechanism the Fedora Atomic
|
|
maintainers ship via the [fedora-sysexts](https://fedora-sysexts.github.io/) project.
|
|
|
|
```sh
|
|
# One-time bootstrap (afterwards the updater is on PATH as `punktfunk-sysext`):
|
|
curl -fsSLO https://git.unom.io/unom/punktfunk/raw/branch/main/packaging/bazzite/punktfunk-sysext.sh
|
|
sudo bash punktfunk-sysext.sh install # add `--channel canary` for rolling builds
|
|
```
|
|
|
|
That downloads the newest image (host + tray + web console, SHA-256-verified over HTTPS from
|
|
punktfunk's package registry), merges it, and applies the udev/sysctl setup on the spot — the
|
|
host is usable immediately, no reboot. From then on:
|
|
|
|
```sh
|
|
sudo punktfunk-sysext update # fetch + merge the newest build
|
|
sudo punktfunk-sysext status # channel, installed vs latest version
|
|
sudo punktfunk-sysext remove # unmerge and delete — the box is back to stock
|
|
```
|
|
|
|
Two things to know:
|
|
|
|
- **After a Bazzite major rebase** (Fedora 43 → 44) the old image **refuses to load** rather than
|
|
run against mismatched system libraries — run `sudo punktfunk-sysext update` once and it fetches
|
|
the image built for the new base.
|
|
- **Already layering punktfunk?** Install the sysext (it shadows the layered copy immediately),
|
|
then drop the layer so it stops slowing your updates:
|
|
`sudo rpm-ostree uninstall punktfunk punktfunk-web && systemctl reboot`.
|
|
|
|
For a fully baked appliance image there's also a **bootc** Containerfile that installs the RPMs
|
|
from the registry at image-build time — see `packaging/bootc/` in the repo. Plain `rpm-ostree`
|
|
layering from the [RPM registry](https://git.unom.io/unom/-/packages) keeps working too (see
|
|
`packaging/bazzite/README.md`), but the sysext is the supported default. Building from source
|
|
also works (Bazzite is Fedora Atomic underneath — same steps as [Fedora](/docs/fedora)).
|
|
|
|
## Allow controller input
|
|
|
|
Gamepad and DualSense input needs your user in the `input` group. On Bazzite, don't use
|
|
`usermod` — the base is immutable and the group is managed by a recipe. Use:
|
|
|
|
```sh
|
|
ujust add-user-to-input-group
|
|
```
|
|
|
|
Then **log out and back in**. (A controller that's "detected but does nothing" is almost always this
|
|
permission, not a client problem.)
|
|
|
|
## Configure
|
|
|
|
The RPM ships a Bazzite-tuned config you can copy as your starting point:
|
|
|
|
```sh
|
|
mkdir -p ~/.config/punktfunk
|
|
cp /usr/share/punktfunk/host.env.bazzite ~/.config/punktfunk/host.env
|
|
```
|
|
|
|
The template is deliberately minimal — it does **not** force a compositor, because the host
|
|
auto-detects Gaming Mode (gamescope) vs Desktop (KWin) on every connect and follows the switch
|
|
mid-stream. The only settings that matter are the session anchors plus zero-copy:
|
|
|
|
```sh
|
|
XDG_RUNTIME_DIR=/run/user/1000
|
|
DBUS_SESSION_BUS_ADDRESS=unix:path=/run/user/1000/bus
|
|
PUNKTFUNK_VIDEO_SOURCE=virtual
|
|
PUNKTFUNK_ZEROCOPY=1 # GPU zero-copy (dmabuf → CUDA → NVENC); auto-falls back to CPU
|
|
PUNKTFUNK_GAMESCOPE_ATTACH=1 # Gaming Mode = attach to the box's own session (see below)
|
|
```
|
|
|
|
### Gaming Mode: attach vs managed
|
|
|
|
For Gaming Mode there are two models (pick one; the shipped default is **attach**):
|
|
|
|
- **Attach** (`PUNKTFUNK_GAMESCOPE_ATTACH=1`, the default) — the **box** owns its gamescope session,
|
|
the host attaches to whatever's live and never tears it down, and the streamed game-mode resolution
|
|
is the box's own gamescope mode. Switching Desktop ↔ Game is rock-solid.
|
|
- **Managed** (`PUNKTFUNK_GAMESCOPE_MANAGED=1`, and remove the attach line) — the host launches its
|
|
**own** gamescope at the *client's* exact resolution and refresh. Client-mode-following, but there
|
|
must be no physical gaming session already running.
|
|
|
|
Full treatment: [Steam / gamescope → Attach vs managed](/docs/gamescope#attach-vs-managed).
|
|
|
|
Mid-stream Gaming ↔ Desktop following (`PUNKTFUNK_SESSION_WATCH`) is **on by default** on
|
|
Bazzite/SteamOS. See [Configuration](/docs/configuration) for the full list of knobs.
|
|
|
|
### Streaming the KDE Plasma desktop
|
|
|
|
The **virtual output** (video) for the Desktop session needs no config — the host package ships an
|
|
`io.unom.Punktfunk.Host.desktop` file whose `X-KDE-Wayland-Interfaces` grants the host KWin's
|
|
restricted screencast protocol on a normal interactive Plasma session (background:
|
|
[KDE Plasma](/docs/kde)). After a **fresh host install, log out and back into the Desktop session
|
|
once** so KWin re-reads that grant.
|
|
|
|
The one thing a normal KDE login lacks is the RemoteDesktop grant for headless **input** injection.
|
|
Seed it once (as the streaming user, no root) so the host auto-approves instead of popping an
|
|
un-answerable dialog:
|
|
|
|
```sh
|
|
bash /usr/share/punktfunk/bazzite/kde-desktop-setup.sh
|
|
```
|
|
|
|
Gaming Mode needs none of this — it auto-attaches.
|
|
|
|
## Run as an always-on host
|
|
|
|
Bazzite hosts are typically headless. Enable the host service and linger so it starts at boot — see
|
|
[Running as a Service](/docs/running-as-a-service). One host service covers both Gaming Mode and the
|
|
Desktop; it follows whichever the box is in.
|
|
|
|
```sh
|
|
systemctl --user enable --now punktfunk-host
|
|
systemctl --user enable --now punktfunk-web # web console: pairing + status
|
|
```
|
|
|
|
Then open [The Web Console](/docs/web-console) for the login password and to
|
|
[arm pairing](/docs/web-console#arm-pairing).
|
|
|
|
## Good to know
|
|
|
|
These apply to the **Gaming Mode (gamescope)** path; the KDE Desktop path is unaffected:
|
|
|
|
- **gamescope 3.16.22 or newer is required.** Older versions can deadlock during capture. Bazzite's
|
|
current gamescope is fine; this only bites if you've pinned an old one.
|
|
- **The mouse cursor isn't included in the captured image** — a gamescope limitation for now. (The
|
|
KDE Desktop path renders the cursor normally.)
|
|
- **HDR isn't supported yet** on the gamescope path — gamescope's capture output is 8-bit. SDR streams
|
|
normally.
|
|
|
|
Canonical list: [gamescope → Known limits](/docs/gamescope#known-limits).
|
|
|
|
Then [connect a client](/docs/clients) — Moonlight works great for couch gaming, and the Apple app for
|
|
Apple TV / iPad.
|