Moonlight / Polaris Troubleshooting

Polaris is the GameStream host on lea (pkgs.polaris-stream from polaris-hdr-linux-patches, user unit polaris.service). It replaces Sunshine/Vibeshine. Paths and unit names below are Polaris-only.

Sanity checks on lea

# Must run inside a kwin-noctalia user session
systemctl --user status polaris
journalctl --user -u polaris -f

# Config (seeded once; web UI may edit later)
ls -la ~/.config/polaris/
# Main settings: ~/.config/polaris/polaris.conf

Web UI: https://<lea-ip>:47990 (HTTPS on GameStream base port + 1 when base is 47989).

Default Headless Stream keys in polaris.conf:

headless_mode = enabled
linux_use_cage_compositor = enabled
linux_prefer_gpu_native_capture = disabled
encoder = nvenc

Black screen in Moonlight

Client codec / quality — try H.264, 1080p30, ~10 Mbps, then raise.
Pairing — unpair and re-pair from the Polaris web UI; manual host IP if mDNS fails.
Network — prefer wired LAN; on lea, UDP segmentation offload on eno2 is disabled for Moonlight (host module). Check client firewall allows outbound GameStream ports.
Unit not running — Polaris is scoped to kwin-noctalia; a pure Plasma login will not start polaris.service.
Encoder — confirm NVENC in the web UI / logs (encoder = nvenc). Software encode is a fallback for testing only.
Dual-GPU capture mismatch — lea’s 9800X3D iGPU (amdgpu / was renderD129) next to the RTX (renderD128) made Polariss headless extcopy open AMD while NVENC ran on NVIDIA → Could not convert image / GL 0x502. lea blacklists amdgpu so only NVIDIA is present; polaris also pins WLR_RENDER_DRM_DEVICE=/dev/dri/renderD128. After a switch, reboot once so amdgpu is gone (ls /dev/dri should show one card + one render node).
Empty labwc (mouse + right-click menu, no Steam) — polaris unit PATH must include steam (and bash). Headless startup is exec steam -gamepadui inside labwc; if steam is missing from PATH the compositor stays empty. Check: systemctl --user show polaris -p Environment includes a path with steam, and pgrep -af steam after launch.
HDR (experimental) — default stream is labwc headless (SDR). Opt-in gamescope path (IceDOS / polaris#152): services.polarisGamescopeSession.enable on lea, idle unit polaris-gamescope-idle.service (force-HDR gamescope flags), helper polaris-gamescope-session, Moonlight apps Steam Bigscreen (HDR follows client/profile) and Steam Bigscreen (forced SDR) (SDR without changing client HDR — e.g. living-room SDR titles). Before those apps: polaris-gamescope-use-portal (portal capture, headless off). Restore: polaris-gamescope-use-labwc. Needs patched gamescope-hdr + xdg-desktop-portal-gamescope + polaris patches 0007/0008 in polaris-hdr-linux-patches (portal SHM→CUDA NV12). True HDR bitstream still needs client HDR + metadata. Not production; patches can break on gamescope bumps.

Pairing

Open https://<lea-ip>:47990 on the host or LAN.
In Moonlight: Add PC → enter lea’s IP if not discovered.
Enter the PIN shown in the Polaris UI.

If the UI is locked out:

polaris --creds new-username new-password
systemctl --user restart polaris

Reset config (last resort)

systemctl --user stop polaris
# Optional: wipe settings (re-seed from Nix tmpfiles on next boot/switch, or copy defaults)
rm -f ~/.config/polaris/polaris.conf ~/.config/polaris/polaris_state.json
# After a rebuild/switch, tmpfiles re-seeds polaris.conf if missing
systemctl --user start polaris

Do not look for ~/.config/sunshine/ or sunshine.service — those are gone.

Ports (firewall)

Declared in modules/nixos/remote-desktop.nix (base 47989 + GameStream offsets):

Direction	Ports (typical)
TCP	47984, 47989, 47990, 48010
UDP	47998–48000 (+ related control)

Remote desktop overview
Module: modules/nixos/remote-desktop.nix
Package: pkgs.polaris-stream (flake input polaris-hdr-linux-patches)