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).
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.
When sunshine-bin trips the ldd check and we switch to the source build,
the prior install left sunshine-bin-debug behind. The source package
includes its own sunshine-debug which collides on
/usr/lib/debug/usr/bin/sunshine.debug, so pacman refuses the install.
Remove both sunshine-bin and sunshine-bin-debug before yay -S sunshine.
uninstall.sh similarly drops all four variants.
Bug: install_sunshine always called yay_install on $SUNSHINE_PKG (default
sunshine-bin) before checking ldd. If the host already had sunshine (source
build) working, the bin install would replace it, trip the ldd check, and
the auto-recovery would rebuild source — a redundant 10-minute compile on
every ./install.sh re-run.
Fix: short-circuit at the top of install_sunshine when either sunshine or
sunshine-bin is already installed AND all its shared libs resolve. The
recovery dance only runs when there's actually something to fix.
Two robustness fixes for failures hit on a real install.
lib/packages.sh
- After installing $SUNSHINE_PKG, run ldd against the binary and check for
"not found" entries. sunshine-bin ships against whichever ICU was current
at AUR-build time; on rolling Arch (jarvis is on ICU 78, package built
against ICU 76) this leaves libicuuc.so.76 unresolved and sunshine exits
127 on every start, eventually tripping the systemd start-limit.
- If sunshine-bin has unresolved deps, remove it and fall back to the
source build (AUR 'sunshine'), then re-verify. If the user explicitly
chose --from-source and it still fails, bail with the ldd diagnostic.
lib/service.sh
- systemctl --user reset-failed before restart, so a previous attempt that
hit start-limit-hit doesn't immediately reject the new start request.
(Re-running install.sh after a broken first attempt was failing because
systemd remembered the prior rate-limit trip.)
Replaces Sunshine's self-signed cert with one minted from a private root CA
whose key material lives in 1Password. Every host running install.sh fetches
the CA via 'op read', mints itself a host cert with SANs for <hostname>.lan
and the current LAN IP, and installs the CA into the system trust store.
Bootstrap (run once, anywhere)
- scripts/cert-bootstrap.sh: generates a 4096-bit RSA root CA (10y validity),
uploads it as a Secure Note titled "Omarchy-Stream Root CA" in the Private
vault with two fields: cert (text) and key (concealed). Refuses to overwrite
an existing item without --force.
Per-host (lib/certs.sh)
- fetch_and_install_certs: reads op://Private/Omarchy-Stream Root CA/{cert,key}
to a tmpfs-staged temp dir (XDG_RUNTIME_DIR), mints a host cert via openssl
with serverAuth + clientAuth EKU, drops cert/key at ~/.config/sunshine/
credentials/{cacert,cakey}.pem, installs the CA at
/etc/ca-certificates/trust-source/anchors/omarchy-stream-ca.pem and runs
update-ca-trust.
- Idempotent: skips re-mint when on-disk cert is signed by the current CA,
has the expected SANs, and isn't within 30 days of expiry. Override with
FORCE_CERTS=1 or --force-certs.
install.sh
- Adds --no-certs, --force-certs flags; sources lib/certs.sh; runs cert step
after permissions/config and before firewall so the service restart at the
end of install picks up the new cert.
client/install-macos.sh
- After installing Moonlight, if `op` is available and signed in, fetches the
CA and adds it as a trusted root to /Library/Keychains/System.keychain via
`security add-trusted-cert -d -r trustRoot`. Skips cleanly when op isn't
ready.
uninstall.sh
- Adds --remove-ca-trust to delete the system trust anchor. By default the
CA is left in place since other tools may rely on it.
verify.sh
- Adds checks for: cert signed by omarchy-stream CA, cert >30 days from
expiry, CA present in system trust store.
Docs
- README "Trusted TLS certs via 1Password" section: bootstrap flow, per-host
flow, client trust matrix (Linux / macOS / iOS / Android / Apple TV),
re-pairing note (first cert install on a host invalidates pinned Moonlight
fingerprints), config env vars.
- client/README gains per-platform CA-trust install steps with concrete
`op read` + platform-specific commands.
Headless mode (new) — for KVM-attached hosts streaming to disconnected clients
- --headless / --mirror flags; default headless on hostname JARVIS, mirror elsewhere
- New lib/headless.sh installs prep-cmd hooks to ~/.local/share/omarchy-moonlight/bin
- bin/sunshine-stream-do.sh creates/resizes a Hyprland HEADLESS-1 output to the
connecting client's resolution and migrates the active workspace onto it
- bin/sunshine-stream-undo.sh tears down the headless output on disconnect and
returns the workspace to a non-headless monitor when one is available
- lib/config.sh writes capture=wlr, output_name=HEADLESS-1, and the JSON
global_prep_cmd entry referencing the installed hook paths
- lib/preflight.sh adds a preflight_headless step that checks hyprctl, jq, and
a running Hyprland session (warn-only, install can proceed)
- lib/verify.sh adds checks for the hook scripts and the wlr/global_prep_cmd
config lines
Mac client
- client/install-macos.sh: Darwin guard, Homebrew presence check, brew cask
install of Moonlight, idempotent
- client/README.md: per-platform install (macOS / Android / iOS / Apple TV /
Linux + Steam Deck) and the five-step first-pair walkthrough
Other
- jq added to the helper install set in lib/packages.sh (hooks parse Hyprland
JSON output)
- README.md rewritten to cover both modes, the new flags, the tuned defaults
per mode + per vendor, the headless internals, and the client pointer
Layers a few things on top of the initial scaffold:
- Default to sunshine-bin (precompiled, ~seconds) instead of building from
source. --from-source restores the old behavior.
- Add lib/preflight.sh: catches the gotchas before any work is done —
Wayland session, NVIDIA driver responsive, nvidia-drm.modeset, amdgpu
loaded, pipewire-pulse present, SSH-without-session warning.
- Add lib/config.sh: writes a tuned ~/.config/sunshine/sunshine.conf with
per-vendor encoder settings (NVENC P1+ll+cbr, VAAPI ultralowlatency,
QuickSync veryfast), KMS capture, pulse audio sink. Uses a
"# managed-by: omarchy-moonlight" marker; removing it hands ownership
back to the user and the installer won't touch the file again.
- Add lib/verify.sh: post-install verification of every step
(cap_sys_admin set, group resolves, udev rule present, /dev/uinput
exists, encoder reachable, service active, :47990 listening). Same
checks are reachable standalone via --doctor.
- Install runtime helpers (pipewire-pulse, vulkan-tools, libva-utils)
alongside Sunshine for diagnostics + audio.
- Uninstall handles both sunshine + sunshine-bin and the -bin moonlight
variant.
- README documents the tuning table, the new flags, and the modeset
troubleshooting path.
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
