Umbriel

Stream an Umbriel session, the Noctalia project's wlroots compositor. Umbriel creates virtual outputs itself, so it needs no fork or plugin. Install the host first: Arch, Ubuntu or Fedora.

What worksCopy Anchor Link

• Each client gets its own virtual output at its size and refresh rate, with a name starting PF-, created over Umbriel's IPC and removed when the client leaves. A resize mid-stream works.
• The host captures it straight from the compositor into the GPU encoder, with no copy. No chooser appears. A real monitor streams the same way.
• Keyboard and mouse go in through the wlroots virtual pointer and keyboard protocols, so Umbriel's keybinds fire on keys from the client.
• Library launches open on a workspace of the streamed output, and the host switches back when the game ends: see Automation.

InstallCopy Anchor Link

Use an Umbriel built on 2026-09-28 or later: older builds can't create virtual outputs.

The repository lines and keys are in Umbriel's install guide. The host doesn't need xdg-desktop-portal-umbriel.

NoctaliaCopy Anchor Link

Noctalia's bar, and its dock when turned on, appear on the streamed output as on any monitor. To keep the bar on your own monitors only, turn it off by default and back on per monitor, in a .toml file under ~/.config/noctalia/:

[bar.default]
enabled = false

[bar.default.monitor."DP-1"]   # your monitor's connector
enabled = true

Use your bar's name in place of default. To scope the dock, set enabled the same way under [dock] and [dock.monitor."DP-1"]. See Noctalia's bar settings.

host.envCopy Anchor Link

Nothing is required: the host finds Umbriel on every connect, so you don't export UMBRIEL_SOCKET.

Leave PUNKTFUNK_COMPOSITOR unset: a pin turns off detection and session following. It accepts umbriel if you need it. Every other option is in Configuration.

Start the hostCopy Anchor Link

Pick Umbriel in your display manager, or run start-umbriel from a TTY. From inside that session:

systemctl --user enable --now punktfunk-host
journalctl --user -u punktfunk-host -f    # watch it start and print its fingerprint

Open the web console to pair a client. To serve Moonlight too, see What the unit starts. To restart the host with Umbriel, see Restart the host with your desktop.

Headless sessionCopy Anchor Link

Umbriel starts with no monitor plugged in, and virtual outputs should work there; this is not yet run on a box. Autologin into the Umbriel session through your display manager, and enable lingering so the host starts at boot: sudo loginctl enable-linger "$USER".

Known limitsCopy Anchor Link

• Streams need a GPU encoder. The host captures Umbriel only straight from the compositor, never through a screen cast: see below.
• SDR only. HDR on Linux needs gamescope or Hyprland — see HDR.
• No per-device scale: the streamed output is always at scale 1, and Scale its screen at doesn't apply.
• Saving an output change in Umbriel's config turns your monitors back on mid-stream: see below.

TroubleshootingCopy Anchor Link

"find the Umbriel IPC socket (no UMBRIEL_SOCKET, no umbriel-*.sock)"Copy Anchor Link

The host found no running Umbriel for its user: it started outside your Umbriel session, or PUNKTFUNK_COMPOSITOR pins Umbriel while another desktop runs. Start the host from inside the session, as above, and leave the pin unset.

"This Umbriel session can't be captured directly; the stream needs a GPU encoder"Copy Anchor Link

The encoder is pinned to software, or Direct capture is off, and Umbriel has no screen cast to fall back to. Set Encoder to auto and turn Direct capture back on (Configuration). If auto finds no GPU encoder, see GPU and driver.

"The host can't talk to this version of Umbriel"Copy Anchor Link

This Umbriel changed how programs talk to it, and your host doesn't know the new way yet. Update Punktfunk on the host. If no update covers it yet, roll Umbriel back to the last build that streamed.

My monitors came back on after I saved my Umbriel configCopy Anchor Link

A saved change to any [output.*] section makes Umbriel apply its config to every output again, which lights the monitors Turn off switched off. Change output sections while nobody streams; the next stream switches the monitors off again.

More fixes in Troubleshooting.