GNOME (Mutter)

Configure a host running GNOME. The host drives GNOME's Mutter compositor to create a per-client virtual display over D-Bus (RecordVirtual), zero-copy. This page assumes the host is already installed — see Ubuntu, Fedora, or Arch.

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 the compositor from your live session on every connect, so the starter ~/.config/punktfunk/host.env is one line:

# ~/.config/punktfunk/host.env  (keys are case-sensitive)
PUNKTFUNK_VIDEO_SOURCE=virtual
# GPU zero-copy (dmabuf → CUDA → NVENC) is ON by default; auto-falls back to CPU. Set =0 to force CPU.

Don't set PUNKTFUNK_COMPOSITOR, WAYLAND_DISPLAY, or XDG_CURRENT_DESKTOP here. Pinning the compositor turns auto-detection off — per connect and mid-stream — so the host stops following session switches, and stale session values point it at dead sockets. Forcing a backend is a CI / dedicated-appliance posture, not desktop configuration.

You must be on a Wayland session (not X11), and Mutter must be ≥ 48. See the Configuration reference for every option.

The GL/EGL userspace

On NVIDIA, gnome-shell fails to start — or the host logs "GPU … not supported by EGL" — when the NVIDIA GL/EGL userspace is missing. The base driver package doesn't always pull it in. Install your distro's NVIDIA GL/EGL userspace package — on Ubuntu/Debian it's libnvidia-gl-<version> matching your driver; on Fedora/Arch it ships with the RPM Fusion / repo driver — then confirm the glvnd vendor file exists:

ls /usr/share/glvnd/egl_vendor.d/10_nvidia.json    # must exist

Installing the driver itself is covered on your distro's install page (Ubuntu, Fedora, Arch).

Do not lock the session

A locked GNOME session blocks screen capture — the host fails with "Session creation inhibited". On an always-on or headless host there's no one to unlock it, so disable the lock:

gsettings set org.gnome.desktop.screensaver lock-enabled false
gsettings set org.gnome.desktop.session idle-delay 0

Start the host

With host.env in place, start the host from inside your GNOME session:

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 to arm pairing and connect a client. For an always-on box, see the headless session below.

Display scaling you set while streaming sticks per client: the host remembers each device's scale and reapplies it on reconnect — see Persistent scaling.

Headless session

To run with no monitor and no login, keep a GNOME Wayland session up at all times and start the host without a login. Have GDM auto-login your user:

# /etc/gdm3/custom.conf  (Ubuntu)   ·   /etc/gdm/custom.conf  (Fedora)
[daemon]
AutomaticLoginEnable = true
AutomaticLogin = your-user

Disable the lock (see above), then enable the host user service and let it linger past logout:

systemctl --user enable --now punktfunk-host
sudo loginctl enable-linger "$USER"

Reboot and the host comes up on the auto-login session. Full walkthrough: Running as a Service.

Troubleshooting

More fixes — black screen, discovery, pairing — in Troubleshooting.

Once the host is up, bring the console up and pair — see The Web Console.