enricobuehler
69fcb6e0b1
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>
4.7 KiB
title, description
| title | description |
|---|---|
| Steam / gamescope | Configure a gamescope/Steam host — attach vs managed, session following, and limits. |
gamescope is the compositor behind Steam Gaming Mode — the couch/handheld game UI on Bazzite, SteamOS, or any distro running a gamescope session. The host auto-detects gamescope from your live session, so you rarely need to set anything here. It also follows a Gaming ↔ Desktop switch mid-stream — flip between Gaming Mode and the desktop with Steam's normal UI and the host re-targets whatever's running without a reconnect.
This page covers the gamescope-specific choices. To get a host running on an appliance box, start from the install guide for your OS: Bazzite or SteamOS (Host).
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.
Attach vs managed
There are two mutually-exclusive models for a gamescope box; pick one. The shipped default is attach.
- Attach (
PUNKTFUNK_GAMESCOPE_ATTACH=1, the default) — the box owns its gamescope session and decides Gaming vs Desktop via the normal Steam UI. The host just attaches to whatever's live and never tears it down, so switching Desktop ↔ Game is rock-solid and disconnecting leaves the box where it was. The streamed game-mode resolution is the box's gamescope mode (SCREEN_WIDTH/HEIGHTin/etc/gamescope-session-plus/sessions.d/steam), not the client's. - Managed (
PUNKTFUNK_GAMESCOPE_MANAGED=1, and remove the attach line) — the host tears the box's gamescope down on connect and launches its own at the client's exact resolution and refresh, restoring on idle. Client-mode-following, but it can't coexist with a box-owned game-mode session, and there must be no physical gaming session already running.
Session following
PUNKTFUNK_SESSION_WATCH follows a Gaming ↔ Desktop switch mid-stream — the host rebuilds the
backend in place, with no reconnect. It is on by default on Bazzite/SteamOS; set 0 to disable.
One host service covers both faces of the box: it streams Gaming Mode over gamescope and the desktop
over its own compositor, and re-targets whichever is live on each switch.
Start the host
On an appliance box (Bazzite, SteamOS) the install guide already enables the host service for you. On any other distro running a gamescope session, start it from your session — the default attach model just latches onto whatever gamescope session is live:
systemctl --user enable --now punktfunk-host
Then bring up The Web Console to arm pairing.
gamescope knobs
The gamescope-specific settings in host.env. Leave them unset to auto-detect; set one only to force
a model. See the full Configuration reference for every other knob.
| Setting | Values | Meaning |
|---|---|---|
PUNKTFUNK_GAMESCOPE_ATTACH |
1 |
Attach model: the box owns its gamescope session; the host captures whatever's live and never tears it down. Streamed resolution is the box's gamescope mode. The default. |
PUNKTFUNK_GAMESCOPE_MANAGED |
1 |
Managed model: the host tears the box's gamescope down on connect and launches its own at the client's exact mode, restoring on idle. Doesn't coexist with a box-owned game-mode session. |
PUNKTFUNK_GAMESCOPE_SESSION |
steam |
The host owns a gamescope-session-plus (Steam) session at the client's mode — a headless appliance with no physical session running. |
PUNKTFUNK_GAMESCOPE_NODE |
auto · node id |
Discover and capture a running gamescope's PipeWire node at a fixed mode. Do not combine with SESSION. |
PUNKTFUNK_GAMESCOPE_APP |
command | For an ad-hoc bare-gamescope session, the nested command to run (e.g. vkcube). |
PUNKTFUNK_SESSION_WATCH |
1 · 0 |
Follow a Gaming ↔ Desktop switch mid-stream (rebuild in place, no reconnect). On by default on Bazzite/SteamOS; set 0 to disable. |
Known limits
These apply to the Gaming Mode (gamescope) path only; the desktop path is unaffected.
- gamescope 3.16.22 or newer is required. Older versions can deadlock during capture. Bazzite's and SteamOS'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.
- HDR isn't supported on the gamescope path — gamescope's capture output is 8-bit. SDR streams normally.
To stream the KDE Plasma desktop of a Steam box instead, see KDE Plasma. To bring up the web console and pair a client, see The Web Console.