punktfunk/docs-site/content/docs/hyprland.md

title, description

title	description
Hyprland	Configure a punktfunk host on a Hyprland session — headless output via hyprctl, capture via xdg-desktop-portal-hyprland.

Hyprland is a first-class backend. The host adds a per-client headless output at the client's exact mode with hyprctl, captures it through the xdg-desktop-portal-hyprland (xdph) ScreenCast portal (zero-copy dmabuf), and injects input via the wlroots virtual pointer/keyboard protocols — which Hyprland still implements even after dropping wlroots in v0.42.

This is a distinct backend from Sway / wlroots: Hyprland has its own IPC (hyprctl) and its own portal (xdph), so it is auto-detected and driven separately.

This page assumes the package is already installed — see Arch, Ubuntu, or Fedora.

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.

host.env

The host auto-detects a Hyprland session, so you usually need nothing here. To force the backend, set these in ~/.config/punktfunk/host.env:

PUNKTFUNK_COMPOSITOR=hyprland
PUNKTFUNK_INPUT_BACKEND=wlr
PUNKTFUNK_VIDEO_SOURCE=virtual
# GPU zero-copy capture→encode is ON by default; auto-falls back to CPU. Set PUNKTFUNK_ZEROCOPY=0 to force CPU.

See Configuration for the full reference.

How it works

• Video — the host runs hyprctl output create headless PF-1 and applies a monitor rule for the client's exact mode. Outputs are named, so there's no before/after diffing. The rule uses hyprctl keyword monitor … (the hyprlang config manager — the default on every release, 0.55 included) and falls back to the Lua hyprctl eval 'hl.monitor{…}' only if you've opted into the Lua config manager. The host confirms the output actually adopted the mode before streaming.
• Capture — it captures that output through the xdg-desktop-portal-hyprland (xdph) ScreenCast portal. To pick the output without a GUI on a headless host, the host writes a managed ~/.config/hypr/xdph.conf pointing xdph's custom_picker_binary at a small shim that selects the new output automatically — no interactive picker dialog to answer.
• Input — mouse and keyboard are injected via the wlroots virtual pointer and virtual keyboard protocols (Hyprland kept them). Gamepads and audio are compositor-independent.

For how long the virtual output lives, and extend-vs-exclusive topology, see Virtual displays.

Requirements

• A running Hyprland session (the hyprctl/xdph contracts are verified on 0.55.4; older releases share the same hyprctl surface).
• xdg-desktop-portal-hyprland (xdph) installed and running — the host captures through its ScreenCast portal, and steers its custom picker. Without it there is no video.
• The ScreenCast interface routed to xdph — see scripts/headless/portals.conf (a [Hyprland] section pins org.freedesktop.impl.portal.ScreenCast=hyprland).

Troubleshooting: black / no video (headless output at 0×0)

A headless output only gets a framebuffer once the compositor can allocate one. On some GPU/driver combinations (notably NVIDIA, and in nested test setups) that GBM/dmabuf allocation fails and the output stays 0×0 — you'll see GBM: Failed to allocate a GBM buffer: bo null in the Hyprland log (cf. Sunshine #4197). The host detects this and fails the session with a clear error rather than streaming a blank surface. If you hit it, capture the Hyprland log (hyprctl instance dir → hyprland.log) and check your GPU's GBM support; running Hyprland as a real session (not nested) is the supported configuration.

Permission system

Hyprland's permission system (ecosystem.enforce_permissions, 0.49+, off by default) can deny direct screencopy and virtual-input clients — and denial is silent: capture goes to black frames and input is dropped, with no error. If you've enabled it, grant the host explicitly in your Hyprland config:

ecosystem {
    enforce_permissions = true
}

permission = /usr/bin/punktfunk-host, screencopy, allow
permission = /usr/bin/punktfunk-host, virtual-pointer, allow
permission = /usr/bin/punktfunk-host, virtual-keyboard, allow

The host logs a warning at startup when it detects enforcement is on. (Adjust the binary path to where your package installed punktfunk-host.)

Start the host

With the backend selected, start the host from inside your Hyprland session:

systemctl --user enable --now punktfunk-host
journalctl --user -u punktfunk-host -f

Bring up the console and pair

Enable the web console, read its login password, and arm PIN pairing — see The Web Console. Then connect a client.