punktfunk/docs-site/content/docs/ubuntu-kde.md

title, description

title	description
Ubuntu — KDE Plasma	Set up a punktfunk host on Ubuntu with KDE Plasma (KWin).

Set up a punktfunk host on Ubuntu running KDE Plasma. The host uses KDE's KWin compositor to create a per-client virtual display. Needs KWin 6.5.6 or newer.

New to this? Skim Requirements first, and read Security & Safe Use — a streaming host is remote control of the machine, so keep it on a trusted LAN or VPN and require pairing.

1. NVIDIA driver

Identical to the GNOME guide — follow step 1 of Ubuntu — GNOME: install the NVIDIA driver and the libnvidia-gl-<version> userspace, enable nvidia-drm modeset=1, reboot, and verify with nvidia-smi.

2. Install the host (apt)

The host is published as a .deb to the public Gitea apt registry — install and update with plain apt. Trust the repo's signing key, add the repo, and install:

sudo install -d -m 0755 /etc/apt/keyrings
curl -fsSL https://git.unom.io/api/packages/unom/debian/repository.key \
  | sudo tee /etc/apt/keyrings/punktfunk.asc >/dev/null

echo "deb [signed-by=/etc/apt/keyrings/punktfunk.asc] https://git.unom.io/api/packages/unom/debian stable main" \
  | sudo tee /etc/apt/sources.list.d/punktfunk.list

sudo apt update
sudo apt install punktfunk-host

This also pulls the web console (punktfunk-web) via Recommends (the pairing/status UI). The desktop client — punktfunk-client, for the machine you stream to — is a separate package, not needed on a host. The NVIDIA driver stays out of band (step 1). Updates later are just sudo apt update && sudo apt upgrade.

3. Configure

The package ships the systemd user unit, the udev rule, and the sysctl tuning. As the desktop user, grant gamepad access and write the KDE config:

sudo usermod -aG input "$USER"     # /dev/uinput for virtual gamepads (re-login to apply)
mkdir -p ~/.config/punktfunk
cat > ~/.config/punktfunk/host.env <<'ENV'
WAYLAND_DISPLAY=wayland-0
XDG_CURRENT_DESKTOP=KDE
PUNKTFUNK_COMPOSITOR=kwin
PUNKTFUNK_VIDEO_SOURCE=virtual
PUNKTFUNK_ZEROCOPY=1
PUNKTFUNK_INPUT_BACKEND=libei
ENV

Make sure you're on a KDE Wayland session (not X11) — the picker on the login screen. The virtual-display path is Wayland-only. See the Configuration reference for every option.

4. Run

Start the host as a user service from inside your Plasma session:

systemctl --user enable --now punktfunk-host
journalctl --user -u punktfunk-host -f      # watch it come up + print its fingerprint

The host listens on UDP 9777 (native punktfunk/1) plus the GameStream ports and advertises over mDNS. It requires PIN pairing by default — arm pairing from the web console and pair once from your client.

Web console

systemctl --user enable --now punktfunk-web
# read the auto-generated login password, then open http://<host-ip>:47992
journalctl --user -u punktfunk-web-init | sed -n 's/.*password generated: //p'

Console login password

The console is password-protected. On first start punktfunk-web-init generates a random login password and saves it to ~/.config/punktfunk/web-password (as PUNKTFUNK_UI_PASSWORD=…). Read it back at any time — 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 password, edit that file (PUNKTFUNK_UI_PASSWORD=<your-password>) and restart the console: systemctl --user restart punktfunk-web. Forgot it? This is the recovery path linked from the console login screen — see Forgot your Password?.

To run it at boot — including fully headless, with KWin brought up automatically and no login — see Running as a Service; the headless appliance is built around KDE.

Troubleshooting

• KWin too old: virtual outputs need KWin ≥ 6.5.6. Check with kwin_wayland --version.
• No picture / capture fails: confirm you're on a Wayland session and the NVIDIA GL userspace is installed (libnvidia-gl-<version>). More in Troubleshooting.

Appendix — build from source

If the apt registry has no build for your release, compile the host yourself (no clean updates / no packaged units). Install the build toolchain and runtime libraries — the same apt line as the GNOME build-from-source appendix — then:

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
git clone https://git.unom.io/unom/punktfunk.git && cd punktfunk
cargo build --release -p punktfunk-host

Write ~/.config/punktfunk/host.env as in step 3, then run it inside your Plasma session:

cargo run --release -p punktfunk-host -- serve --gamestream

(The native plane is always on; --gamestream adds the Moonlight-compat surface this guide's GameStream ports refer to — trusted LAN only. Drop it for a secure native-only host.)