OPINIONATED OMARCHY
TROUBLESHOOTING CORPUS
790
RECORDS
790
AUDITED
0
UNCHECKED
2388
SOURCES
LIVE
wayland-compat medium occasional DISPUTE

Fix a solid black Sunshine stream on NVIDIA under Hyprland

omarchyarchhyprlandwaylandnvidia
CORRECTED An auditor found the fix wrong or incomplete and rewrote it. · checked against Omarchy omarchy 4.0.4-1 on 2026-10-05
AUDIT NOTE

omacom/omarchy#8998 (open) supports the cause, the three log lines, the AQ_NO_MODIFIERS dead end and the KMS fix. PR #9011 is open and its diff only writes capture = kms. /usr/share/omarchy/bin/omarchy-install-service-sunshine on 4.0.4-1 sets no capture mode, runs systemctl --user enable --now sunshine and appends o.launch_on_start("sunshine"), confirmed locally. Two claims were wrong. First, Omarchy's own sunshine package (omacom/omarchy-pkgs pkgbuilds/sunshine/sunshine.install, every revision since 2026-05-23) runs setcap cap_sys_admin,cap_sys_nice+p in both post_install and post_upgrade, so the capability is already present and is reapplied on every update. The record's setcap cap_sys_admin+p therefore replaces the packaged set and silently drops cap_sys_nice, and its 're-run after every update' advice is wrong. Second, the verify line promised h264_nvenc, but the issue author's own update says the package also needs a CUDA build, omarchy-pkgs#228 (open) says the builder has no CUDA toolkit so the PKGBUILD's _use_cuda=detect compiles without CUDA. KMS capture fixes the black picture, NVENC may still be absent. Fix, cause, verify and danger rewritten. Not exercised: sunshine is not installed here and there is no NVIDIA GPU, and the duplicate-instance behaviour from the two launch paths is inferred from the installer, not observed.

The cause above was rewritten on 2026-10-05 to match this note; the fix was corrected by the audit itself.
RISK

cap_sys_admin is close to full root for that binary, on a program that listens on the network. Omarchy's package already grants it, and KMS capture is what makes use of it. Keep the firewall rules Omarchy's installer scoped to private ranges and Tailscale, and do not expose Sunshine's ports to the internet.

Symptom

Streaming my Omarchy desktop with Sunshine to Moonlight shows a black screen, or black boxes over some windows (1Password's unlock field was the first report). The Sunshine log shows Error: [wlgrab] Could not initialize display with the given hw device type., Error: Couldn't scale frame: Invalid argument and Info: Encoder [nvenc] failed. NVIDIA GPU. AMD and Intel machines stream fine.

Cause

On NVIDIA, Hyprland allocates its output buffers in NVIDIA's tiled block-linear format. Sunshine's default Wayland capture path (wlr, wlr-export-dmabuf / wlr-screencopy) cannot read that layout back, so it falls back to software encoding of a corrupted frame that renders black. NVFBC, NVIDIA's own capture API, does not support Wayland. KMS capture reads the framebuffer from DRM directly and works, but it needs cap_sys_admin on the Sunshine binary. Diagnosed in omacom/omarchy#8998. omarchy-install-service-sunshine on 4.0.4-1 does not set capture = kms, and PR #9011 to do that for NVIDIA is still open. Omarchy's sunshine package already grants the capability itself: its install scriptlet runs setcap cap_sys_admin,cap_sys_nice+p on every install and upgrade. Hardware NVENC is a separate gap: it needs Sunshine built with CUDA, and omacom/omarchy-pkgs#228, which would build the x86_64 package with CUDA, is still open, so the stock Omarchy package may encode in software even once KMS capture works. Forcing AQ_NO_MODIFIERS=1 makes things worse (Fatal: Unable to find display or encoder during startup).

Fix

Check that the Sunshine binary has the capability KMS capture needs. Use readlink -f because setcap does not follow symlinks:


SUN="$(readlink -f "$(command -v sunshine)")"
getcap "$SUN"

**Omarchy 4.** The sunshine package sets this itself on install and on every upgrade, so getcap should print cap_sys_admin,cap_sys_nice=p. Do not run setcap with a shorter list, because it replaces the whole set and drops cap_sys_nice.

**Plain Arch, or getcap printed nothing.** Set the same capabilities the package scriptlet sets:


sudo setcap cap_sys_admin,cap_sys_nice+p "$SUN"

Switch capture to KMS, once:


mkdir -p ~/.config/sunshine
grep -q '^capture' ~/.config/sunshine/sunshine.conf 2>/dev/null || echo 'capture = kms' >> ~/.config/sunshine/sunshine.conf
grep '^capture' ~/.config/sunshine/sunshine.conf

**Omarchy 4.** omarchy-install-service-sunshine both enables the sunshine user service and adds o.launch_on_start("sunshine") to ~/.config/hypr/autostart.lua, so two copies can start at login and the old one can keep the ports and the old config. Keep the service and remove the autostart line, then restart cleanly:


sed -i '/^o.launch_on_start("sunshine")$/d' ~/.config/hypr/autostart.lua
pgrep -a sunshine
pkill -x sunshine
systemctl --user restart sunshine
pgrep -a sunshine     # exactly one process

**Plain Arch.** Restart however you start it, for example systemctl --user restart sunshine.

If getcap comes back empty after a Sunshine update (a self-built or AUR binary whose scriptlet did not run), repeat the setcap line.

The picture should now stream. Hardware NVENC is a separate matter: it needs a Sunshine build with CUDA. On Omarchy that depends on omacom/omarchy-pkgs#228, which is still open, so a software encoder in the log is expected with the stock package.

Verify

journalctl --user -u sunshine -n 50 shows Screencasting with KMS, and Moonlight shows the desktop, not black. Found H.264 encoder: h264_nvenc [nvenc] appears only if your Sunshine build includes CUDA. With the stock Omarchy package a software encoder is expected until omacom/omarchy-pkgs#228 lands.

Sources

sunshine-moonlight-stream-black-nvidia-hyprland