Omarchy-Stream/docs/ARCHITECTURE.md

Architecture

How the pieces fit together at install time and at stream time. Pair this with TROUBLESHOOTING.md (what went wrong + why) and the top-level README.md (how to use it).

---

Component map

                                ┌─────────────────────────────────────┐
                                │            install.sh                │
                                └──┬──────────────────────────────────┘
                                   │ sources & orchestrates
        ┌──────────┬──────────┬────┼──────────┬──────────┬──────────┐
        ▼          ▼          ▼    ▼          ▼          ▼          ▼
   common.sh   detect.sh preflight packages  permissions config    certs
   (logging,   (GPU,    (env       (yay,    (input grp,  (writes  (1P CA →
    sudo,     hostname, sanity     setcap,   uinput      sunshine. host cert,
    yay)      session)  checks)    encoder)  udev)       conf)   trust store)
                                                          │
                                                          ├─→ headless.sh
                                                          │   (hook +
                                                          │    drop-in install)
                                                          │
                                                          ├─→ firewall.sh
                                                          │   (ufw / firewalld
                                                          │    port opening)
                                                          │
                                                          └─→ service.sh
                                                              (unit detection
                                                               +linger+enable)

At runtime the moving parts are:

   Moonlight client  ───TCP/UDP─→  sunshine (Linux process)
                                        │
                ┌───────── service ─────┤ on connect / disconnect
                ▼                       ▼
         hypridle    Hyprland   global_prep_cmd
         (sleeps)    ◄─────────  hooks  (do/undo)
                                       │
                                       ▼
                               HEADLESS-N output
                              (resized per client)

---

Install-time flow

install.sh is intentionally linear and idempotent. Each step is "check, then act" — re-running is safe.

1. require_* sanity guards: not root, on Arch, yay present.
2. detect_all sets $HOSTNAME_SHORT, $GPU_VENDOR, $SESSION_TYPE for the rest of the run.
3. compute_stream_mode picks mirror or headless:
   • --mirror or --headless wins
   • Otherwise: hostname matches an entry in $HEADLESS_HOSTS (case-insensitive, comma-separated) → headless; everything else → mirror.
4. preflight_all surfaces problems early (Wayland session? GPU driver responsive? nvidia-drm.modeset not explicitly disabled? pipewire-pulse installed? hyprctl+jq+Hyprland reachable if headless?). Mostly warn-only — install proceeds even with warnings.
5. install_sunshine + install_gpu_encoder_packages:
   • Skip if sunshine or sunshine-bin is already installed AND ldd reports no missing libs.
   • Otherwise yay -S $SUNSHINE_PKG (default sunshine-bin). ldd-check; if anything is "not found", remove sunshine-bin+-debug and rebuild from source.
6. Permissions: add user to input group, drop the uinput udev rule if missing, setcap cap_sys_admin+p on the sunshine binary (KMS capture needs this).
7. Headless hooks (only in headless mode): install sunshine-stream-do.sh, sunshine-stream-undo.sh, sunshine-prestart.sh into ~/.local/share/omarchy-moonlight/bin/.
8. write_sunshine_config: generate ~/.config/sunshine/sunshine.conf with a # managed-by: marker. Per-vendor encoder block + capture method per stream mode. Mirror mode writes capture = kms only; headless mode writes capture = wlr, output_name = HEADLESS-1, and a global_prep_cmd JSON referencing the installed hooks.
9. Certs (default on): pull CA from op://Private/Omarchy-Stream Root CA/{cert,key}, mint a host cert with SANs (<host>.lan, LAN IP, localhost, 127.0.0.1), install host cert + key into Sunshine's credentials/, install CA into /etc/ca-certificates/trust-source/anchors/, update-ca-trust extract. Idempotent — skips re-mint if the existing cert is signed by the current CA and has all expected SANs and is >30d from expiry.
10. Firewall: detect ufw / firewalld via systemd unit state. Open Sunshine's TCP (47984/47989/47990/48010) and UDP (47998/47999/48000/48010) ports if either is active.
11. Service: resolve which unit was packaged (sunshine.service or app-dev.lizardbyte.app.Sunshine.service), install the headless prestart drop-in if mode is headless, loginctl enable-linger, enable + restart.
12. verify_install runs the same checks as --doctor: cap_sys_admin set, group resolves, web UI listening on :47990, encoder reachable, hook scripts present, CA in trust store.

---

Runtime flow — headless mode

Mirror mode is simpler: Sunshine just captures the real DRM output via KMS, hooks aren't involved. Headless mode is where the orchestration lives.

Service start

systemd-user starts sunshine.service
    │
    ├─ ExecStartPre=/bin/sleep 5           (packaged by AUR sunshine, gives the
    │                                        graphical session time to come up)
    │
    ├─ ExecStartPre=-${HOME}/.local/share/omarchy-moonlight/bin/sunshine-prestart.sh
    │   │  (non-fatal: '-' prefix)
    │   │
    │   ├─ recovers $HYPRLAND_INSTANCE_SIGNATURE from $XDG_RUNTIME_DIR/hypr/
    │   │   if it wasn't propagated by systemd-user env
    │   │
    │   ├─ sort -V the existing HEADLESS-* outputs (oldest first)
    │   │
    │   ├─ if zero exist → 'hyprctl output create headless'
    │   ├─ if more than one exists → remove all but the lowest-numbered
    │   │   (Hyprland's HEADLESS-N counter is monotonic; without active
    │   │    dedupe extras accumulate forever)
    │   │
    │   └─ rewrite sunshine.conf's `output_name = ...` line to match the
    │       surviving output's actual name (sed-in-place, idempotent)
    │
    └─ ExecStart=/usr/bin/sunshine
        │
        ├─ reads sunshine.conf (now has correct output_name)
        ├─ enumerates Wayland outputs (finds HEADLESS-N)
        ├─ probes encoders against that output (nvenc / vaapi / etc.)
        └─ binds :47984/:47989/:47990/:48010, advertises via Avahi

Client connect

Moonlight client opens a stream
    │
    ├─ TCP handshake to sunshine on :47989
    │
    ├─ Sunshine spawns global_prep_cmd's `do` script:
    │     env: SUNSHINE_CLIENT_WIDTH, _HEIGHT, _FPS, _HOST_AUDIO, _HDR
    │     cwd: sunshine's working directory
    │
    │   sunshine-stream-do.sh
    │     │
    │     ├─ recover $HYPRLAND_INSTANCE_SIGNATURE (defensive)
    │     ├─ snapshot prior workspace + monitor state to
    │     │   $XDG_RUNTIME_DIR/sunshine-headless/{prev-monitors.json,
    │     │                                       prev-workspace-id,
    │     │                                       headless-name}
    │     ├─ discover the existing HEADLESS-* (no hardcoded name)
    │     │   if none → 'hyprctl output create headless' and wait for it
    │     ├─ 'hyprctl keyword monitor <name>,${W}x${H}@${FPS},auto,1'
    │     ├─ 'hyprctl dispatch moveworkspacetomonitor <prev_ws> <name>'
    │     └─ 'hyprctl dispatch focusmonitor <name>'
    │
    ├─ Sunshine binds encoder to the (now resized) output
    │
    └─ stream begins

Client disconnect

Moonlight tears down the stream
    │
    ├─ Sunshine runs global_prep_cmd's `undo` script:
    │   sunshine-stream-undo.sh
    │     │
    │     ├─ read headless-name from state dir; fall back to discovery
    │     ├─ find a non-headless monitor (if any are connected)
    │     │   └─ 'hyprctl dispatch moveworkspacetomonitor <prev_ws> <real>'
    │     │   └─ 'hyprctl dispatch focusmonitor <real>'
    │     └─ DO NOT remove HEADLESS-N — it stays so Sunshine's next
    │         startup encoder probe still has a surface to bind to.
    │         (Create-then-destroy per session raced with Sunshine's
    │         startup probe and tripped fatal errors.)
    │
    └─ clean state files

---

Headless capture backends: wlr vs X11/NVENC

The installer's headless mode assumes wlr (capture = wlr) on Hyprland — that's the runtime flow diagrammed above. There is a second headless backend, used on hosts that don't run Hyprland (e.g. Ubuntu) or that want a guaranteed NVIDIA GL context for NVENC: X11 capture of a headless Xorg.

	wlr path (installer default)	X11/NVENC path (manual)
Compositor	Hyprland (or sway-headless on a server)	headless Xorg on :0
sunshine.conf	capture = wlr, output_name = HEADLESS-N	capture = x11, output_name = 0
Display unit	the Hyprland/sway session	xorg-headless.service (user unit)
Per-client resize	yes — global_prep_cmd do/undo hooks	no — Xorg has a fixed MetaModes resolution
How the display is faked	wlroots headless output	NVIDIA ConnectedMonitor + ModeValidation (TwinView)
Service env drop-in	inherits Wayland env	pins DISPLAY=:0, XDG_SESSION_TYPE=x11

The X11/NVENC path is the systemd-service form of the upstream "Remote SSH Headless Setup" guide. It trades per-client resolution adaptation (the wlr path's main feature) for a simpler, compositor-free capture that the NVIDIA driver accelerates directly. Input injection is identical for both — input group + 60-sunshine.rules on /dev/uinput.

Both backends share the same boot caveat: on a headless host the Sunshine unit must be wired into default.target, not graphical-session.target, or it never auto-starts. See TROUBLESHOOTING.md §12–13 for the drop-ins and the alias-merge gotcha that lets a stale wlr drop-in poison the X11 environment.

---

Cert pipeline

A separate one-time bootstrap creates the CA in 1Password. Every host then mints itself from that CA.

One-time bootstrap (run on any single machine)

scripts/cert-bootstrap.sh
    │
    ├─ require op CLI signed in
    ├─ openssl genrsa 4096 → CA private key (in tmpfs)
    ├─ openssl req -new -x509 -days 3650 → CA cert (signed by itself)
    ├─ 'op item create --category "Secure Note" --vault Private
    │       --title "Omarchy-Stream Root CA"
    │       cert[text]=<ca-cert.pem>
    │       key[concealed]=<ca-key.pem>'
    └─ print op://Private/Omarchy-Stream Root CA/{cert,key} references

Per-host (built into install.sh)

fetch_and_install_certs                  (lib/certs.sh)
    │
    ├─ op_require_signin (op whoami)
    ├─ stage CA in tmpfs ($XDG_RUNTIME_DIR/omarchy-certs.XXXX)
    │   │
    │   ├─ 'op read op://Private/Omarchy-Stream Root CA/cert' → ca-cert.pem
    │   └─ 'op read op://Private/Omarchy-Stream Root CA/key'  → ca-key.pem
    │
    ├─ install CA into /etc/ca-certificates/trust-source/anchors/
    │   omarchy-stream-ca.pem; update-ca-trust extract
    │
    ├─ idempotency: existing host cert signed by current CA AND has all
    │   expected SANs AND >30d from expiry → skip mint, exit
    │
    └─ openssl x509 -req                  → host cert (RSA 2048, 365 days)
            -extensions v3_req
            SANs:
              DNS = <hostname>.lan
              DNS = localhost
              IP  = <LAN-IP>
              IP  = 127.0.0.1
            EKU = serverAuth, clientAuth
        │
        ├─ install -m 0644 → ~/.config/sunshine/credentials/cacert.pem
        └─ install -m 0600 → ~/.config/sunshine/credentials/cakey.pem

After the cert is replaced, all previously-paired Moonlight clients see a fingerprint mismatch and must re-pair once. Subsequent installs preserve the cert as long as the CA + SAN set hasn't changed.

---

State directories

Everything the system writes lives in well-known paths so it can be inspected or cleaned without code archaeology.

Path	Owner	Contents
~/.config/sunshine/	sunshine	runtime config + state (user-managed)
~/.config/sunshine/sunshine.conf	this installer (when marker present)	tuned config; managed-by marker on line 1
~/.config/sunshine/credentials/	this installer (cert step)	cacert.pem (host cert) + cakey.pem (private key)
~/.local/share/omarchy-moonlight/bin/	this installer	prep-cmd hook scripts in stable location
~/.config/systemd/user/<unit>.service.d/	this installer	headless prestart drop-in
$XDG_RUNTIME_DIR/sunshine-headless/	sunshine-stream-do.sh at runtime	per-stream state, cleared on reboot
/etc/ca-certificates/trust-source/anchors/	this installer (cert step)	the omarchy-stream Root CA, picked up by update-ca-trust

---

Idempotency contract

Every script in this repo is designed to be re-run safely. The patterns:

• pkg_installed X || yay_install X — only install missing packages.
• "Managed-by marker" on generated config files — only rewrite the file if we wrote it last time (marker present) OR no file exists. User edits that remove the marker are durable.
• Cert minting skips when the on-disk cert matches CA + SANs + expiry.
• setcap is a no-op if the cap is already set.
• loginctl enable-linger is a no-op if linger is already on.
• systemctl --user enable doesn't fail on an already-enabled unit.
• hyprctl output create headless runs only when no headless output exists (the prestart script counts first).
• The prestart script removes extras to converge on exactly one — this is the only "destructive" idempotency action, and it preserves the lowest-numbered output (most likely to have workspaces bound to it).

A ./install.sh re-run with no changes to environment should report a long list of "Already installed" / "already present" lines and end with a clean verify.

---

File map

omarchy-moonlight/
├── install.sh                       Orchestrator
├── uninstall.sh                     Reverse install (preserves user data by default)
├── status.sh                        Runtime health check (what's running + g2g verdict)
├── README.md                        User-facing install + usage
├── scripts/
│   └── cert-bootstrap.sh            One-time CA generation + 1P upload
├── bin/                             Repo source for runtime scripts
│   ├── sunshine-prestart.sh         ExecStartPre: dedupe headless + sync conf
│   ├── sunshine-stream-do.sh        prep-cmd `do`: resize + workspace migrate
│   └── sunshine-stream-undo.sh      prep-cmd `undo`: workspace return
├── lib/                             Installer library (sourced by install.sh)
│   ├── common.sh                    Logging, sudo helpers, idempotency primitives
│   ├── detect.sh                    GPU vendor, session type, hostname
│   ├── preflight.sh                 Pre-install sanity checks
│   ├── packages.sh                  yay -S + auto-fall-back from bin to source
│   ├── permissions.sh               input group, uinput udev, cap_sys_admin
│   ├── config.sh                    Generates sunshine.conf
│   ├── certs.sh                     1P-backed CA, host cert minting, trust install
│   ├── headless.sh                  Installs hook scripts + prestart drop-in
│   ├── firewall.sh                  ufw / firewalld port opening
│   ├── service.sh                   Unit detection, fallback, linger, enable
│   └── verify.sh                    Post-install checks (also reused by --doctor)
├── files/                           Static files installed by lib functions
│   ├── headless-prestart.conf       systemd drop-in template
│   └── sunshine.service             Fallback unit if no AUR variant ships one
├── client/                          Moonlight client side
│   ├── install-macos.sh             brew install + add CA to System keychain
│   └── README.md                    Per-platform install + first-pair flow
└── docs/
    ├── ARCHITECTURE.md              this file
    ├── TROUBLESHOOTING.md           failure modes hit during install, with fixes
    └── FOLLOWUPS.md                 outstanding work / known limitations