Bare Openbox rendered only a blank slate root — usable but not the
desktop wanted. Make the X11/NVENC capture path render a full GNOME
session by default, with Openbox available via HEADLESS_DESKTOP=openbox
for minimal/low-power hosts.
- files/headless-desktop-gnome.service: full Ubuntu GNOME session forced
onto the X11 path (XDG_SESSION_TYPE=x11, no dbus-run-session so it
shares the systemd user bus). Renamed the Openbox unit to
headless-desktop-openbox.service.
- lib/headless.sh: HEADLESS_DESKTOP (default gnome) selects the unit
template + the packages to install (gnome-session/gnome-shell vs
openbox/xsetroot).
- install.sh: step message + usage document HEADLESS_DESKTOP.
- status.sh: the :0 desktop check now reports which desktop is running
(reads _NET_WM_NAME off the supporting-wm-check window, e.g.
"GNOME Shell").
- docs: TROUBLESHOOTING §13 + FOLLOWUPS P3 updated for the GNOME default
and the openbox toggle.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
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>
Two new docs filling the gaps in the prior set:
docs/ARCHITECTURE.md
- Component map + runtime flow diagrams (install-time and per-stream).
- Cert pipeline walk-through end-to-end (CA bootstrap, op:// references,
per-host mint, idempotency conditions).
- State directory inventory (where things write at runtime).
- Idempotency contract — explicit rules every script in this repo follows.
- Full file map of the repo.
docs/FOLLOWUPS.md
- Promoted the punch list out of the TROUBLESHOOTING.md trailing section.
- Each item now has: symptom, current workaround, fix sketch (with the
actual code change, not vague intent), and a complexity estimate.
- Tracks: screensaver inhibit, busiest-workspace auto-switch (2-line
patch), 1Password black-rectangle workarounds (untested), host.lan
DNS (out-of-repo), 1P SSH-agent timeout, cert renewal timer, stale
config keys, single-user assumption.
README.md
- New "Documentation" section between Clients and Diagnostics points at
each of the three doc files plus client/README.md, with a one-line
description for each so readers can navigate without spelunking.
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).
