A Moonlight client connecting to the x11-backend host got a black screen
even though pairing, NVENC, and input injection all worked: the headless
Xorg on :0 had no window manager rendering on it, so capture=x11 grabbed
an empty black root window. (The wlr/kms backends don't hit this — their
capture source renders for itself.)
This was a hand-built path with nothing in the repo to reproduce the
desktop piece. Now:
- files/headless-desktop.service: Openbox session on :0, bound to
xorg-headless.service, enabled via default.target for lingering boots,
with a best-effort xsetroot so the desktop is visibly non-black.
- lib/headless.sh: capture_backend_is_x11 + install_headless_desktop
(idempotent; pulls openbox/xsetroot via the distro dispatch).
- install.sh: installs the desktop unit when capture=x11 is detected.
- status.sh: x11 branch now FAILs if no window manager is on :0 instead
of only checking the X server answers — the gap that hid this failure.
- docs: TROUBLESHOOTING §13 black-screen lesson; FOLLOWUPS P3 updated.
Part of the P3 x11-backend work; --backend flag, config.sh x11 variant,
and xorg-headless templates remain outstanding.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Adds a parallel install path for Debian/Ubuntu hosts alongside the existing
Arch/Omarchy/Hyprland one. The Arch path is untouched at runtime; everything
new is gated on $DISTRO and (for headless) $COMPOSITOR.
Highlights:
- lib/distro.sh: detect_distro + pkg_install/pkg_remove/ca_anchor_path/
ca_update_trust dispatch helpers
- lib/packages.sh: Ubuntu sunshine install pulls LizardByte's official .deb
from GitHub releases (override via SUNSHINE_DEB_URL/SUNSHINE_DEB_VERSION);
GPU encoder packages branch per $DISTRO:$GPU_VENDOR
- bin/sunshine-stream-{do,undo,prestart}-sway.sh + files/sway-headless.*:
swaymsg-based headless capture path for hosts without Hyprland. sway runs
under a systemd-user unit that sunshine.service depends on via drop-in.
- lib/preflight.sh: clearer NVIDIA driver guidance on Ubuntu (we don't install
the driver - too many branch/kernel/Secure-Boot variants); sway-aware
headless preflight
- lib/certs.sh + lib/verify.sh + uninstall.sh: distro-aware CA trust anchor
(Arch: /etc/ca-certificates/trust-source/anchors + update-ca-trust;
Debian: /usr/local/share/ca-certificates + update-ca-certificates)
Verified on Ubuntu 24.04: ./install.sh --doctor --headless loads cleanly,
distro/GPU/compositor detection report the right values, all pre-install
failures correspond to the actual missing pieces.
This bundles every fix we made debugging the first real install plus a
comprehensive troubleshooting reference. Working tree is now PII-safe for
public distribution: hostname-based default mode is driven by a HEADLESS_HOSTS
env var instead of a hardcoded literal; docs use placeholders for hostnames
and LAN IPs.
Self-healing headless management
- bin/sunshine-prestart.sh (new): runs as systemd ExecStartPre. Resolves the
Hyprland instance signature from XDG_RUNTIME_DIR/hypr when systemd-user env
didn't propagate it. Reduces to exactly one headless output by keeping the
lowest-numbered HEADLESS-N and removing the rest. Rewrites the managed
sunshine.conf's output_name line to match the surviving name — Hyprland's
HEADLESS-N counter is monotonic and ignores the optional name argument to
'output create headless', so without active sync output_name drifts off
HEADLESS-1 after the first restart cycle.
- bin/sunshine-stream-do.sh: dropped the hardcoded MON=HEADLESS-1. Now
discovers whatever HEADLESS-* exists via jq. Resize and workspace migration
target the actual output.
- bin/sunshine-stream-undo.sh: reads the headless name from a state file the
do-script wrote, with discovery fallback. Stops removing the output between
sessions — the create/destroy race caused fatal startup encoder errors on
the next Sunshine restart.
- files/headless-prestart.conf, files/sunshine.service: ExecStartPre now
points at the new prestart script.
- lib/headless.sh: install_headless_hooks now installs all three scripts.
New install_headless_prestart_dropin resolves the actual systemd unit name
(sunshine.service vs app-dev.lizardbyte.app.Sunshine.service) and lands the
drop-in under <unit>.service.d/.
Firewall detection
- lib/firewall.sh: _ufw_active now uses 'systemctl is-active ufw.service'
instead of 'ufw status'. The latter requires root to read /etc/ufw state,
so the unprivileged probe returned false and we silently skipped opening
Sunshine's ports on hosts where ufw was actively dropping packets.
Service unit fallbacks
- lib/service.sh: ensure_sunshine_unit_present looks for sunshine.service in
every systemd-user path first; falls back to the reverse-DNS AUR-source
unit name; last resort drops a repo-provided fallback unit. systemctl
reset-failed before each restart so a previous start-limit-hit doesn't
immediately reject the new attempt.
Preflight
- lib/preflight.sh: new preflight_headless step that, only when STREAM_MODE
is headless, surfaces missing hyprctl / jq / Hyprland reachability before
install proceeds.
Public-safe defaults
- install.sh: streaming-mode default is now driven by HEADLESS_HOSTS env var
(comma-separated, case-insensitive). Unset by default — every host gets
mirror mode unless its hostname is listed or --headless is passed
explicitly. Past versions hardcoded a specific hostname.
- README.md: replaced JARVIS-specific examples with HEADLESS_HOSTS prose.
Docs
- docs/TROUBLESHOOTING.md (new): comprehensive failure-mode reference. Every
issue hit during the first end-to-end install, in order, with symptom →
cause → fix → permanent prevention. Plus a "Custom keybinding to escape
Moonlight" section and an outstanding-followups punch list (1Password
black-rectangle workarounds, hypridle inhibit during stream, busiest-
workspace auto-switch, jarvis.lan DNS, 1Password SSH agent timeouts).
Two streams of fixes shipped together.
Headless persistence (root cause of "Fatal: Unable to find display or
encoder during startup")
- bin/sunshine-stream-undo.sh: stop removing HEADLESS-1 on disconnect.
Create-on-connect / destroy-on-disconnect raced with Sunshine's startup
encoder probe and made every restart fail with a fatal-but-misleading
warning. The output now lives across stream sessions; sunshine-stream-
do.sh just resizes it per client.
- files/headless-prestart.conf: systemd-user drop-in that runs
'hyprctl output create headless' (non-fatal) before Sunshine starts, so
HEADLESS-1 exists before the encoder probe.
- lib/headless.sh: install_headless_prestart_dropin resolves the actual
unit name (sunshine.service or app-dev.lizardbyte.app.Sunshine.service)
and lands the drop-in under ~/.config/systemd/user/<unit>.d/.
- lib/service.sh: enable_sunshine_service calls install_headless_prestart_
dropin when STREAM_MODE=headless. Placed after ensure_sunshine_unit_
present so the unit name is settled when the drop-in is written.
- install.sh: comment noting the drop-in install is deferred to the
service-enable step.
Web UI lockdown + tunnel-friendly certs
- lib/config.sh: emits origin_web_ui_allowed = pc. Sunshine rejects web UI
requests from anywhere other than localhost regardless of bind address.
Streaming/pairing (47989) stays LAN-accessible. Inline comment documents
the SSH tunnel recipe.
- lib/certs.sh: add DNS:localhost and IP:127.0.0.1 to host cert SANs so
the tunneled https://localhost:47990 URL doesn't trigger a hostname
mismatch. Idempotency check now requires those SANs too.
Misc.
- files/sunshine.service: fallback unit also gains the prestart ExecStartPre.
- lib/service.sh: ensure_sunshine_unit_present aliases the reverse-DNS
Sunshine unit as sunshine.service when sunshine-bin's short-name unit
isn't installed.
Sets up bidirectional game streaming across Omarchy/Hyprland/Wayland
machines (NVIDIA desktop and AMD Framework laptop), with the Macbook
as an additional Moonlight client.
The same install.sh runs on either machine; GPU vendor is detected at
runtime and the appropriate hardware-encode packages are installed.
Includes:
- KMS capture setup (cap_sys_admin on sunshine, input group, uinput udev rule)
- ufw / firewalld port opening when a firewall is active
- systemd --user service + loginctl enable-linger for always-on hosting
- uninstall.sh with --purge for user data removal
- Flags to install host-only or client-only
