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>
114 lines
4.7 KiB
Markdown
114 lines
4.7 KiB
Markdown
---
|
|
title: KDE Plasma (KWin)
|
|
description: Configure a punktfunk host for KDE — host.env, quirks, and a headless KWin session.
|
|
---
|
|
|
|
Configure a punktfunk host on **KDE Plasma**. The host uses KDE's KWin compositor to create a
|
|
per-client virtual display, captured zero-copy on NVIDIA. This page assumes the package is already
|
|
installed — see [Ubuntu](/docs/ubuntu), [Fedora](/docs/fedora), [Arch](/docs/arch), or the
|
|
[Bazzite](/docs/bazzite) appliance.
|
|
|
|
> 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.
|
|
|
|
## host.env
|
|
|
|
A KDE starter `~/.config/punktfunk/host.env`:
|
|
|
|
```ini
|
|
WAYLAND_DISPLAY=wayland-0
|
|
XDG_CURRENT_DESKTOP=KDE
|
|
PUNKTFUNK_COMPOSITOR=kwin
|
|
PUNKTFUNK_VIDEO_SOURCE=virtual
|
|
PUNKTFUNK_ZEROCOPY=1
|
|
PUNKTFUNK_INPUT_BACKEND=libei
|
|
```
|
|
|
|
The host auto-detects the running compositor on every connect, so most of this is optional — the
|
|
values above are just what it resolves to on a KWin session. See the
|
|
[Configuration reference](/docs/configuration) for every option.
|
|
|
|
## Use a Wayland session
|
|
|
|
KDE must run on **Wayland**, not X11 — pick the Wayland session from the picker on the login screen.
|
|
The virtual-display path is Wayland-only and will not come up under X11.
|
|
|
|
KWin must be **6.5.6 or newer** (virtual outputs land there). Check with:
|
|
|
|
```sh
|
|
kwin_wayland --version
|
|
```
|
|
|
|
## Streaming the interactive desktop
|
|
|
|
To stream a logged-in Plasma desktop (rather than a headless session, below), KWin has to hand the
|
|
host its restricted screencast protocol. The host package ships an `io.unom.Punktfunk.Host.desktop`
|
|
file whose `X-KDE-Wayland-Interfaces` grants exactly that on a normal interactive session
|
|
(least-privilege, the same mechanism krfb/krdp use). After a **fresh install, log out and back into
|
|
the Desktop session once** so KWin re-reads the grant.
|
|
|
|
A normal KDE login still lacks the RemoteDesktop grant that **input** injection needs — without it the
|
|
host pops an "Allow remote control?" dialog no headless box can answer. **Fedora and Bazzite** ship a
|
|
one-shot helper that seeds it (run once as the streaming user, no root):
|
|
|
|
```sh
|
|
bash /usr/share/punktfunk/bazzite/kde-desktop-setup.sh # Fedora / Bazzite
|
|
```
|
|
|
|
The `.deb` and Arch packages don't include that wrapper. Seed the grant by hand instead — copy the
|
|
shipped `kde-authorized` file into the portal store (the share dir is `/usr/share/punktfunk-host` on
|
|
Debian/Ubuntu, `/usr/share/punktfunk` on Arch), then log out and back in:
|
|
|
|
```sh
|
|
mkdir -p ~/.local/share/flatpak/db
|
|
cp /usr/share/punktfunk*/headless/kde-authorized ~/.local/share/flatpak/db/kde-authorized
|
|
```
|
|
|
|
A login-less appliance skips all of this — its headless session (below) needs none of these grants.
|
|
|
|
## Start the host
|
|
|
|
With `host.env` in place, start the host from **inside your Plasma session**:
|
|
|
|
```sh
|
|
systemctl --user enable --now punktfunk-host
|
|
journalctl --user -u punktfunk-host -f # watch it come up and print its identity fingerprint
|
|
```
|
|
|
|
Then bring up [The Web Console](/docs/web-console) to arm pairing and connect a
|
|
[client](/docs/clients). To start at boot — including fully headless — see the
|
|
[headless session](#headless-session) below or [Running as a Service](/docs/running-as-a-service).
|
|
|
|
## Persistent per-client scaling
|
|
|
|
KWin round-trips per-client display scale: it names each session's virtual output per client, so a
|
|
scale you set for one client (150 %, 125 %, …) is reapplied on that client's next connect. See
|
|
[Virtual displays](/docs/virtual-displays).
|
|
|
|
## Headless session
|
|
|
|
For a login-less appliance — a box that streams at boot with no graphical login — the host brings up a
|
|
**dedicated headless KWin session** rather than relying on an interactive one. It runs its own
|
|
`kwin --virtual` session (shipped as the `punktfunk-kde-session.service` unit) with permission checks
|
|
relaxed, so it needs none of the interactive grants above.
|
|
|
|
```sh
|
|
mkdir -p ~/.config/punktfunk
|
|
cp /usr/share/punktfunk/host.env.kde ~/.config/punktfunk/host.env # Debian/Ubuntu: /usr/share/punktfunk-host/host.env.kde
|
|
|
|
systemctl --user daemon-reload
|
|
systemctl --user enable --now punktfunk-kde-session punktfunk-host
|
|
sudo loginctl enable-linger "$USER"
|
|
```
|
|
|
|
The session unit brings up headless KWin; the host unit follows it and starts listening. See
|
|
[Running as a Service](/docs/running-as-a-service) for the full headless setup.
|
|
|
|
## Troubleshooting
|
|
|
|
- **KWin too old:** virtual outputs need KWin **≥ 6.5.6**. Check with `kwin_wayland --version`.
|
|
- **Black screen / no picture:** confirm you're on a Wayland session (not X11) and the NVIDIA GL
|
|
userspace is installed. More in [Troubleshooting](/docs/troubleshooting).
|
|
|
|
To bring the console up and pair, see [The Web Console](/docs/web-console).
|