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>
94 lines
4.5 KiB
Markdown
94 lines
4.5 KiB
Markdown
---
|
|
title: Running as a Service
|
|
description: Start the host at boot — for a desktop you log into, or a fully headless always-on machine.
|
|
---
|
|
|
|
Running `serve` in a terminal is fine for trying punktfunk out. To make a machine an
|
|
always-available host, run it as a service. There are two cases.
|
|
|
|
> The bundled unit `scripts/punktfunk-host.service` runs `serve --gamestream`, so it serves both the
|
|
> native `punktfunk/1` plane and stock [Moonlight](/docs/moonlight) clients. For a **secure native-only
|
|
> host** (no GameStream — its pairing runs over plain HTTP and its legacy encryption is weaker), drop
|
|
> `--gamestream` from the unit's `ExecStart` and use bare `serve`.
|
|
|
|
## A. A desktop you log into
|
|
|
|
If you sit at the machine (or it auto-logs-in to a desktop), run the host as a **systemd user
|
|
service** that starts with your session:
|
|
|
|
```sh
|
|
mkdir -p ~/.config/systemd/user
|
|
cp scripts/punktfunk-host.service ~/.config/systemd/user/
|
|
# Put your host.env in place first — see the setup guide for your desktop.
|
|
systemctl --user daemon-reload
|
|
systemctl --user enable --now punktfunk-host
|
|
```
|
|
|
|
The host now starts whenever you log in. Check it with `systemctl --user status punktfunk-host`.
|
|
|
|
## B. A headless, always-on host
|
|
|
|
To run with **no monitor and no login** — a machine in a closet that's always ready — you need two
|
|
things: a desktop session that comes up at boot, and the host service started without a login.
|
|
|
|
Start by making the host service start at boot even when nobody logs in:
|
|
|
|
```sh
|
|
sudo loginctl enable-linger "$USER"
|
|
```
|
|
|
|
Then bring up a session automatically. How you do that is desktop-specific — auto-login, lock
|
|
disable, and the session unit differ per compositor, so each is documented on its own page:
|
|
|
|
- GNOME: [GNOME → Headless session](/docs/gnome#headless-session).
|
|
- KDE Plasma: [KDE → Headless session](/docs/kde#headless-session).
|
|
- Steam / gamescope: [gamescope](/docs/gamescope) — the host launches its own session per client, so
|
|
there's no separate session unit.
|
|
|
|
Once a session comes up at boot, enable the host user service (section A) and reboot. The host comes up
|
|
on that session.
|
|
|
|
### Headless Bazzite
|
|
|
|
On Bazzite, the host launches its own gamescope/Steam session per client, so you don't need a separate
|
|
session unit — see [Bazzite](/docs/bazzite) and [gamescope](/docs/gamescope).
|
|
|
|
## Windows
|
|
|
|
> punktfunk has first-class **Linux and Windows** hosts. On Windows it ships as a signed installer
|
|
> with an SCM service and a virtual-display driver — including punktfunk's own **indirect display
|
|
> driver** the host pushes frames straight into. The Windows host is newer than the Linux host. (Not
|
|
> to be confused with the Windows *client*, which streams *to* a Windows PC.)
|
|
|
|
On Windows the host runs as a `LocalSystem` service that launches into the interactive session, so it
|
|
captures the secure desktop (UAC / lock screen) and survives reboots with nobody logged in — the same
|
|
model Sunshine/Apollo use. Because it runs at that privilege level, keep it on a trusted network and be
|
|
deliberate about which machine you host on — see [Security & Safe Use](/docs/security).
|
|
|
|
The easy path is the **signed installer**: download `punktfunk-host-setup-<ver>.exe` from the package
|
|
registry ([`punktfunk-host-windows`](https://git.unom.io/unom/-/packages)) and run it. It drops the host
|
|
into `C:\Program Files\punktfunk`, installs the bundled **pf-vdisplay** virtual-display driver, and
|
|
registers + starts the service for you (`/VERYSILENT` for unattended). Upgrades and uninstall are
|
|
handled through Add/Remove Programs.
|
|
|
|
Prefer the CLI? Run `punktfunk-host service install` from an elevated prompt — see
|
|
[Windows Host](/docs/windows-host). For hardware encode you need a GPU — NVIDIA (NVENC), AMD (AMF), or
|
|
Intel (QSV); the host falls back to software H.264 without one.
|
|
|
|
> **Firewall scope.** The installer opens the streaming + console ports on **Private and Domain**
|
|
> networks only — not **Public**. If your LAN is (mis)classified Public, clients won't connect until
|
|
> you set it to Private (Windows Settings → Network), and the host logs a warning when it's on a Public
|
|
> network. For a trusted network Windows insists is Public, tick **"Allow connections on Public
|
|
> networks"** at install (or pass `--allow-public-network` to `service install`). See
|
|
> [Security & Safe Use](/docs/security) for the reasoning.
|
|
|
|
## Verifying
|
|
|
|
After a reboot, from another machine on the network:
|
|
|
|
```sh
|
|
punktfunk-probe --discover # or just look for the host in a native client / Moonlight
|
|
```
|
|
|
|
If the host is listed, it's up. If not, check `journalctl --user -u punktfunk-host` on the host.
|