status.sh: don't misreport an unreachable user bus as a missing unit

Running status.sh in the first seconds after a reboot (before /run/user/$UID exists / the lingering user manager is reachable), or as the wrong user without a session bus, made every `systemctl --user` call fail with "Failed to connect to bus". The Service check read that the same as "unit doesn't exist" and printed a scary "no sunshine user unit found" for a perfectly healthy, auto-starting install. Probe the user manager once up front; if the bus is unreachable, say so explicitly (and point at 'ss -tulnp | grep 47990' to verify Sunshine independently) instead of cascading into false negatives. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Default the x11 headless desktop to GNOME (Openbox still opt-in)
2026-06-03 00:04:50 +00:00 · 2026-06-02 23:56:17 +00:00 · 2026-06-02 23:43:00 +00:00 · 2026-06-02 22:57:03 +00:00 · 2026-05-23 01:17:42 +00:00
25 changed files with 1726 additions and 135 deletions
--- a/README.md
+++ b/README.md
@@ -200,13 +200,22 @@ The host-side installer handles Linux clients via `moonlight-qt`. For everything
 ## Diagnostics

 ```bash
-./install.sh --doctor                                 # run all checks
+./status.sh                                           # runtime health check — is it g2g right now?
+./install.sh --doctor                                 # install-time correctness checks
 systemctl --user status sunshine
 journalctl --user -u sunshine -f
 getcap "$(readlink -f "$(command -v sunshine)")"      # should include cap_sys_admin
 id -nG | tr ' ' '\n' | grep -x input                  # confirm group membership
 ```

+`status.sh` walks what's actually *running* — service state, boot wiring,
+display backend (auto-detects x11 / wlr / kms from your `sunshine.conf`),
+encoder, ports, web UI, `/dev/uinput`, and pairing — then prints either
+**g2g** or a concrete TODO list of what needs work (exit 1 if anything's
+broken). Run it as the Sunshine user, or as root (`sudo ./status.sh`, which
+auto-detects the user). `--doctor` is the install-time complement: it checks
+the install is *correct*; `status.sh` checks the host is *up*.
+
 Useful Sunshine ports (auto-opened if a firewall is active):

 - TCP: `47984 47989 47990 48010`
--- a/bin/sunshine-prestart-sway.sh
+++ b/bin/sunshine-prestart-sway.sh
@@ -0,0 +1,76 @@
+#!/usr/bin/env bash
+# Sway analog of sunshine-prestart.sh. Runs as ExecStartPre for sunshine.service
+# on Ubuntu/Debian installs that use the Sway-headless path.
+#
+# Two jobs:
+#   1. Confirm sway is reachable; create HEADLESS-1 if it doesn't exist yet.
+#   2. Sync sunshine.conf's `output_name` to whatever the headless output is
+#      currently named (`create_output` may auto-assign HEADLESS-2, -3, etc.
+#      after a session restart).
+
+set -uo pipefail
+
+log() { printf '[sunshine-prestart-sway] %s\n' "$*" >&2; }
+
+CONF="$HOME/.config/sunshine/sunshine.conf"
+
+if [[ -z "${SWAYSOCK:-}" ]]; then
+  for sock in "${XDG_RUNTIME_DIR:-/run/user/$(id -u)}"/sway-ipc.*.sock; do
+    [[ -S "$sock" ]] || continue
+    export SWAYSOCK="$sock"
+    break
+  done
+fi
+if [[ -z "${SWAYSOCK:-}" ]]; then
+  log "sway not running; nothing to prepare."
+  exit 0
+fi
+
+if ! command -v swaymsg >/dev/null 2>&1 || ! command -v jq >/dev/null 2>&1; then
+  log "swaymsg/jq missing; skipping prestart."
+  exit 0
+fi
+
+# Reduce to exactly one HEADLESS-* output.
+mapfile -t headless_outputs < <(swaymsg -t get_outputs -r 2>/dev/null \
+  | jq -r '.[].name | select(startswith("HEADLESS-"))' \
+  | sort -V)
+existing="${headless_outputs[0]:-}"
+
+if [[ -z "$existing" ]]; then
+  log "No headless output present; creating one"
+  swaymsg create_output HEADLESS-1 >/dev/null 2>&1 || swaymsg create_output >/dev/null 2>&1 || true
+  for _ in 1 2 3 4 5; do
+    existing="$(swaymsg -t get_outputs -r 2>/dev/null \
+      | jq -r '.[].name | select(startswith("HEADLESS-"))' \
+      | sort -V | head -1)"
+    [[ -n "$existing" ]] && break
+    sleep 0.1
+  done
+elif [[ ${#headless_outputs[@]} -gt 1 ]]; then
+  # Keep the first, log the rest. Removing outputs in sway during prestart can
+  # cascade workspace re-assignment, so we err on the side of leaving them.
+  log "Found ${#headless_outputs[@]} headless outputs; using $existing (extras left in place)"
+fi
+
+if [[ -z "$existing" ]]; then
+  log "Failed to obtain a headless output; Sunshine will start without one."
+  exit 0
+fi
+log "Headless output present: $existing"
+
+# Sync sunshine.conf's output_name. Only touch the file if it's our managed
+# variant (has the management marker) AND the line has actually drifted.
+if [[ -f "$CONF" ]] && grep -qF '# managed-by: omarchy-moonlight' "$CONF"; then
+  current="$(awk '/^output_name = / {print $3; exit}' "$CONF" 2>/dev/null || true)"
+  if [[ "$current" != "$existing" ]]; then
+    log "Updating sunshine.conf output_name: ${current:-(unset)} -> $existing"
+    if grep -q '^output_name = ' "$CONF"; then
+      sed -i "s|^output_name = .*|output_name = $existing|" "$CONF"
+    else
+      printf '\noutput_name = %s\n' "$existing" >> "$CONF"
+    fi
+  fi
+fi
+
+exit 0
--- a/bin/sunshine-stream-do-sway.sh
+++ b/bin/sunshine-stream-do-sway.sh
@@ -0,0 +1,112 @@
+#!/usr/bin/env bash
+# Sunshine global_prep_cmd `do` hook for the Sway-based headless capture path
+# (Debian/Ubuntu installs where Hyprland isn't available).
+#
+# On client connect:
+#   - Ensures a HEADLESS-1 output exists on the running sway session
+#   - Resizes it to the client's negotiated mode (WxH@FPS)
+#   - Snapshots state for the undo hook
+#
+# Sunshine env vars set on connect:
+#   SUNSHINE_CLIENT_WIDTH, SUNSHINE_CLIENT_HEIGHT, SUNSHINE_CLIENT_FPS
+#
+# This script intentionally mirrors the Hyprland do-hook's shape so debugging
+# transfers across the two paths.
+
+set -uo pipefail
+
+WIDTH="${SUNSHINE_CLIENT_WIDTH:-1920}"
+HEIGHT="${SUNSHINE_CLIENT_HEIGHT:-1080}"
+FPS="${SUNSHINE_CLIENT_FPS:-60}"
+HEADLESS_NAME="${OMARCHY_VIRTUAL_OUTPUT:-HEADLESS-1}"
+STATE_DIR="${XDG_RUNTIME_DIR:-/tmp}/sunshine-headless"
+mkdir -p "$STATE_DIR"
+
+HOOK_LOG="$STATE_DIR/hook.log"
+: > "$HOOK_LOG"
+log() {
+  local msg
+  msg="$(date +%H:%M:%S.%3N) [sunshine-do-sway] $*"
+  printf '%s\n' "$msg" >&2
+  printf '%s\n' "$msg" >> "$HOOK_LOG"
+}
+log "do-hook start: client=${WIDTH}x${HEIGHT}@${FPS} target=${HEADLESS_NAME}"
+
+if ! command -v swaymsg >/dev/null 2>&1; then
+  log "swaymsg not found; nothing to configure."
+  exit 0
+fi
+
+# Recover SWAYSOCK if the unit env didn't propagate it. sway writes the socket
+# path into a predictable /run/user/$UID location, but the env var is the
+# clean handle.
+if [[ -z "${SWAYSOCK:-}" ]]; then
+  for sock in "${XDG_RUNTIME_DIR:-/run/user/$(id -u)}"/sway-ipc.*.sock; do
+    [[ -S "$sock" ]] || continue
+    export SWAYSOCK="$sock"
+    log "Discovered SWAYSOCK=$SWAYSOCK"
+    break
+  done
+  if [[ -z "${SWAYSOCK:-}" ]]; then
+    log "sway not running (no IPC socket found); nothing to configure."
+    exit 0
+  fi
+fi
+
+# True if an output named $HEADLESS_NAME currently exists on the session.
+_headless_present() {
+  swaymsg -t get_outputs -r 2>/dev/null \
+    | jq -e --arg n "$HEADLESS_NAME" '.[] | select(.name == $n)' >/dev/null
+}
+
+# Create the headless output if missing. Sway's `create_output` accepts an
+# optional name; without one it auto-assigns HEADLESS-N like Hyprland does.
+if ! _headless_present; then
+  log "Creating headless output $HEADLESS_NAME"
+  if ! swaymsg create_output "$HEADLESS_NAME" >/dev/null 2>&1; then
+    # Older sway versions ignore the name argument; fall back and rename via
+    # output detection after the fact.
+    swaymsg create_output >/dev/null 2>&1 || true
+  fi
+  # Poll briefly for the output to appear.
+  for _ in 1 2 3 4 5; do
+    _headless_present && break
+    sleep 0.1
+  done
+  if ! _headless_present; then
+    # Last-ditch: take the highest-numbered HEADLESS-* that exists and treat
+    # it as ours. Update HEADLESS_NAME in-memory so the resize below targets it.
+    found="$(swaymsg -t get_outputs -r 2>/dev/null \
+      | jq -r '[.[].name | select(startswith("HEADLESS-"))] | sort_by(.) | last // empty')"
+    if [[ -n "$found" ]]; then
+      HEADLESS_NAME="$found"
+      log "Adopted existing headless output: $HEADLESS_NAME"
+    else
+      log "Failed to create a headless output; stream will rely on whatever Sunshine selects."
+      exit 0
+    fi
+  fi
+fi
+
+# Snapshot state so undo can put things back. We don't move workspaces around
+# on a headless-only box (there is no other monitor), but we still record what
+# was active in case the user runs sway with a real display attached.
+swaymsg -t get_outputs -r > "$STATE_DIR/prev-outputs.json" 2>/dev/null || true
+echo "$HEADLESS_NAME" > "$STATE_DIR/headless-name"
+
+# Resize the headless output. Sway accepts mode strings as "WIDTHxHEIGHT@FPSHz".
+log "Sizing $HEADLESS_NAME → ${WIDTH}x${HEIGHT}@${FPS}Hz"
+if ! swaymsg output "$HEADLESS_NAME" mode "${WIDTH}x${HEIGHT}@${FPS}Hz" >/dev/null 2>&1; then
+  log "Mode set with refresh rate failed; retrying without refresh"
+  swaymsg output "$HEADLESS_NAME" mode "${WIDTH}x${HEIGHT}" >/dev/null 2>&1 || \
+    log "Mode set failed; sway will keep the previous mode."
+fi
+
+# Focus the headless output so window placement lands there.
+swaymsg focus output "$HEADLESS_NAME" >/dev/null 2>&1 || true
+
+post="$(swaymsg -t get_outputs -r 2>/dev/null \
+  | jq -r '.[] | "\(.name) \(.current_mode.width)x\(.current_mode.height)@\(.current_mode.refresh) focused=\(.focused)"' \
+  | tr '\n' ';' || true)"
+log "post-state outputs: $post"
+log "Stream ready: ${WIDTH}x${HEIGHT}@${FPS} on $HEADLESS_NAME"
--- a/bin/sunshine-stream-undo-sway.sh
+++ b/bin/sunshine-stream-undo-sway.sh
@@ -0,0 +1,50 @@
+#!/usr/bin/env bash
+# Sunshine global_prep_cmd `undo` hook for the Sway-based headless path.
+# Cheaper than the Hyprland undo: there's no workspace shuffling to reverse on
+# a true headless box. We just keep the headless output alive for the next
+# connect (creating one is ~free, removing it forces sway to renegotiate
+# focused output every cycle).
+
+set -uo pipefail
+
+HEADLESS_NAME="${OMARCHY_VIRTUAL_OUTPUT:-HEADLESS-1}"
+STATE_DIR="${XDG_RUNTIME_DIR:-/tmp}/sunshine-headless"
+HOOK_LOG="$STATE_DIR/hook.log"
+log() {
+  local msg
+  msg="$(date +%H:%M:%S.%3N) [sunshine-undo-sway] $*"
+  printf '%s\n' "$msg" >&2
+  printf '%s\n' "$msg" >> "$HOOK_LOG" 2>/dev/null || true
+}
+log "undo-hook start"
+
+if ! command -v swaymsg >/dev/null 2>&1; then
+  log "swaymsg not found; nothing to undo."
+  exit 0
+fi
+
+if [[ -z "${SWAYSOCK:-}" ]]; then
+  for sock in "${XDG_RUNTIME_DIR:-/run/user/$(id -u)}"/sway-ipc.*.sock; do
+    [[ -S "$sock" ]] || continue
+    export SWAYSOCK="$sock"
+    break
+  done
+  if [[ -z "${SWAYSOCK:-}" ]]; then
+    log "sway not running; nothing to undo."
+    exit 0
+  fi
+fi
+
+# Remember the headless name across the connect cycle if we adopted a
+# different output name in the do-hook.
+if [[ -f "$STATE_DIR/headless-name" ]]; then
+  HEADLESS_NAME="$(cat "$STATE_DIR/headless-name" 2>/dev/null || echo "$HEADLESS_NAME")"
+fi
+
+# On a server with no real outputs, removing HEADLESS-1 leaves sway with zero
+# outputs and any future create_output starts numbering at -2, -3, etc.
+# Cheaper to keep it alive.
+log "Keeping $HEADLESS_NAME alive for the next stream"
+
+rm -f "$STATE_DIR/prev-outputs.json" "$STATE_DIR/headless-name"
+log "Stream teardown complete"
--- a/docs/ARCHITECTURE.md
+++ b/docs/ARCHITECTURE.md
@@ -162,6 +162,35 @@ Moonlight tears down the stream

 ---

+## 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
@@ -265,6 +294,7 @@ verify.
 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
--- a/docs/FOLLOWUPS.md
+++ b/docs/FOLLOWUPS.md
@@ -220,6 +220,49 @@ that prefix. Substantial work; not justified without a real second user.

 ---

+## P3 — Installer support for the X11/NVENC (non-Hyprland) headless path
+
+**Symptom**: `install.sh` only knows the Arch + Hyprland + wlr world. At least
+one real deployment is an **Ubuntu host running the X11/NVENC path** (headless
+Xorg on `:0`, `capture = x11`, NVIDIA TwinView virtual display) — set up
+entirely by hand. None of it is reproducible from the repo: not the
+`xorg-headless.service` unit, not the X11 `sunshine.conf`, not the
+`DISPLAY=:0` service drop-in, not the `default.target` boot wiring (see
+TROUBLESHOOTING.md §12–13).
+
+**Current workaround**: configure those hosts manually using the recipes now
+documented in ARCHITECTURE.md ("Headless capture backends") and
+TROUBLESHOOTING.md §13.
+
+**Fix sketch**:
+
+- A `--backend x11|wlr` flag (or auto-detect: Hyprland reachable → wlr,
+  NVIDIA + no Wayland compositor → x11).
+- `lib/config.sh`: emit the X11 conf variant when backend is x11.
+- Ship an `xorg-headless.service` + `xorg-headless.conf` template (the
+  `ConnectedMonitor`/`ModeValidation` block is GPU-output-specific — needs
+  `xrandr` detection or a prompt).
+- `lib/service.sh`: install the `default.target` boot drop-in for headless
+  hosts regardless of backend, and the `DISPLAY=:0` env drop-in for x11.
+- Debian/Ubuntu package install path (`apt` + the `.deb`), since `yay`/AUR
+  don't exist there. This is a larger lift than the flag itself.
+
+**Done so far**: the *desktop* piece of the x11 backend is now reproducible.
+`install.sh` detects `capture = x11` (via `capture_backend_is_x11`) and installs
+ enables `headless-desktop.service` so the headless Xorg has a desktop to
+render — without it, capture is a black screen. Desktop is selectable via
+`HEADLESS_DESKTOP`: `gnome` (default — full Ubuntu GNOME session, X11 path) or
+`openbox` (lightweight bare WM); each ships as its own unit template
+(`files/headless-desktop-{gnome,openbox}.service`). `status.sh` gained a matching
+check (FAIL if no desktop on `:0`, and reports which one). Still outstanding:
+the `--backend x11|wlr` flag/auto-detect, the `config.sh` x11 conf variant, and
+shipping the `xorg-headless.service` + `xorg-headless.conf` templates.
+
+**Complexity**: medium-high. The capture-backend split is moderate; full
+Debian packaging support is the bulk of the work.
+
+---
+
 ## Not on the list (intentionally)

 - **TLS for the stream itself.** Sunshine and Moonlight handle this with
--- a/docs/TROUBLESHOOTING.md
+++ b/docs/TROUBLESHOOTING.md
@@ -364,6 +364,150 @@ IP.2 = 127.0.0.1
 And the idempotency check in `fetch_and_install_certs` requires those SANs
 — existing hosts re-mint on next install.

+### 12. Headless host: service never auto-starts after boot (`graphical-session.target` never activates)
+
+**Symptom**
+
+Sunshine works right after install, and works again if you `systemctl --user
+start` it by hand, but never comes up on its own after a reboot. `systemctl
+--user status` shows the unit `enabled` yet `inactive (dead)` — *not* failed,
+just never started. Ports 47984/47989/47990 aren't listening and nothing is
+in the journal because the unit was never invoked.
+
+**Cause**
+
+The packaged unit (`sunshine.service`, or `app-dev.lizardbyte.app.Sunshine.service`)
+is wired `WantedBy=graphical-session.target` and `After=graphical-session.target`.
+On a desktop, logging in activates `graphical-session.target`, which pulls
+Sunshine up. A **headless host has no graphical login session**, so
+`graphical-session.target` never activates — even with `loginctl enable-linger`
+on and a headless display server (Xorg/sway) already running. The installer's
+one-time `systemctl --user start` is why it appears to work at install time;
+the wiring just never fires again at boot.
+
+This bites any headless deployment (KVM box, server with a dummy/virtual
+display, the X11/NVENC path in §13). It does *not* bite a laptop/desktop that
+actually logs into Hyprland.
+
+**Fix**
+
+Add a drop-in that wires the unit into a target the lingering user-manager
+actually reaches (`default.target`) and orders it after whatever provides the
+display:
+
+```bash
+# adjust the unit name to whichever one is installed (see issue #3)
+UNIT=app-dev.lizardbyte.app.Sunshine.service
+mkdir -p ~/.config/systemd/user/$UNIT.d
+cat > ~/.config/systemd/user/$UNIT.d/headless-boot.conf <<'EOF'
+[Unit]
+# Order after the headless display unit (xorg-headless.service for the X11
+# path, sway-headless.service for the wlr path).
+Requires=xorg-headless.service
+After=xorg-headless.service
+
+[Install]
+# graphical-session.target never activates on a headless host; default.target
+# is reached by the lingering user manager, so this is what makes boot work.
+WantedBy=default.target
+EOF
+systemctl --user daemon-reload
+systemctl --user reenable $UNIT     # recreates default.target.wants symlink
+systemctl --user restart $UNIT
+```
+
+Confirm the load-bearing symlink exists:
+`ls ~/.config/systemd/user/default.target.wants/ | grep -i sunshine`. The real
+proof is a reboot — `enabled` alone isn't enough on a headless box.
+
+> Note: dependency keys (`Requires=`, `After=`) belong in the `[Unit]` section.
+> A drop-in that puts them in `[Service]` is silently ignored — systemd logs
+> `Unknown key name 'Requires' in section 'Service', ignoring` in
+> `systemctl status`, and the ordering never takes effect.
+
+### 13. X11/NVENC headless path (Ubuntu / non-Hyprland hosts)
+
+**Symptom / context**
+
+This repo's headless mode assumes Hyprland + `capture = wlr`. On a host that
+isn't running Hyprland (e.g. an Ubuntu box, or one where you want NVIDIA NVENC
+with a guaranteed GL context), the wlr path has nothing to capture and every
+encoder probe fails at startup (same red banner as issue #4).
+
+**The X11/NVENC alternative (as deployed on at least one host)**
+
+Instead of a wlroots compositor, run a **headless Xorg on `:0`** and have
+Sunshine grab the X root window. This is the systemd-service equivalent of the
+upstream "Remote SSH Headless Setup" guide's TwinView trick — NVIDIA Xorg is
+told a monitor is connected so it produces a hardware-accelerated virtual
+display.
+
+- A `xorg-headless.service` (user unit) runs
+  `Xorg :0 -config xorg-headless.conf …` with an NVIDIA `ConnectedMonitor` +
+  `ModeValidation` block (see the upstream guide). It's the headless display
+  the Sunshine unit orders against in issue #12.
+- `~/.config/sunshine/sunshine.conf` uses `capture = x11`, `output_name = 0`,
+  `encoder = nvenc`. (Hand-edited — delete the `# managed-by:` marker line so
+  the Arch installer leaves it alone.)
+- A service drop-in pins the X11 environment so Sunshine doesn't auto-probe
+  Wayland:
+  ```ini
+  [Service]
+  Environment=
+  Environment=DISPLAY=:0
+  Environment=XDG_SESSION_TYPE=x11
+  UnsetEnvironment=WAYLAND_DISPLAY XDG_SESSION_TYPE
+  ```
+- Input injection works the normal way — user in the `input` group +
+  `60-sunshine.rules` udev rule on `/dev/uinput`. The upstream guide's
+  `chown`-via-passwordless-sudo `/dev/uinput` workaround is **not needed**;
+  it only applies when you SSH in without group membership.
+
+**Gotcha: leftover wlr drop-ins poison the X11 env.** If a host was first set
+up for the wlr path and later migrated to X11, a stale
+`sunshine.service.d/sway-headless.conf` drop-in can linger. Because
+`sunshine.service` is an *alias* of `app-dev.lizardbyte.app.Sunshine.service`,
+systemd merges drop-ins from **both** name directories, so that leftover keeps
+injecting `XDG_SESSION_TYPE=wayland`, `WAYLAND_DISPLAY=wayland-1`, and a hard
+`Requires=sway-headless.service` (a dead unit). It "works" only because
+`capture = x11` is explicit in the conf, but at boot it tries to pull in the
+dead sway unit. Delete the stale drop-in and verify the effective env:
+
+```bash
+systemctl --user show $UNIT -p Environment -p Requires -p After
+# should show DISPLAY=:0 + XDG_SESSION_TYPE=x11, xorg-headless.service, no wayland/sway
+```
+
+**Gotcha: black screen in Moonlight even though everything "works".** Pairing
+succeeds, NVENC loads, mouse/keyboard input reaches the host — but the client
+sees only black. Cause: the headless Xorg on `:0` is up, but **nothing is
+rendering on it**. Unlike the wlr path (where the compositor *is* the desktop),
+a bare Xorg server draws nothing on its own, so `capture = x11` grabs an empty
+black root window. Confirm with:
+
+```bash
+DISPLAY=:0 xlsclients                              # only 'sunshine' = no WM/desktop
+DISPLAY=:0 xprop -root _NET_SUPPORTING_WM_CHECK    # 'not found' = no window manager
+```
+
+Fix: run a desktop on `:0`. The installer ships a `headless-desktop.service`
+for exactly this and enables it whenever it detects `capture = x11`. It defaults
+to a full **GNOME** session (`gnome-session --session=ubuntu`, forced to the X11
+path); set `HEADLESS_DESKTOP=openbox` for a lightweight bare WM instead (lower
+overhead, but no panel/launcher — right-click menu only). The unit forces
+`XDG_SESSION_TYPE=x11` and does **not** wrap GNOME in `dbus-run-session` — GNOME
+must share the systemd *user* bus the service already inherits.
+
+```bash
+systemctl --user enable --now headless-desktop.service
+DISPLAY=:0 xprop -root _NET_SUPPORTING_WM_CHECK    # now reports a 'window id'
+# read the running desktop's name off that window:
+DISPLAY=:0 xprop -id <id> _NET_WM_NAME             # e.g. "GNOME Shell"
+```
+
+`status.sh` checks for this directly: with `capture = x11` it now FAILs if no
+window manager is present on `:0`, instead of only verifying the X server answers.
+
 ---

 ## Custom keybinding to escape Moonlight (Mac)
--- a/files/headless-desktop-gnome.service
+++ b/files/headless-desktop-gnome.service
@@ -0,0 +1,30 @@
+[Unit]
+Description=GNOME session on the headless Xorg (gives Sunshine something to capture)
+# Without a desktop running on :0, Sunshine's x11 capture grabs an empty black
+# X root window — pairing, NVENC, and input all work but the client sees only
+# black. This runs a full GNOME session on :0 so the stream shows a real
+# desktop. Only relevant to the X11/NVENC capture backend (capture = x11); the
+# wlr backend's compositor renders for itself.
+Requires=xorg-headless.service
+After=xorg-headless.service
+PartOf=graphical-session.target
+
+[Service]
+Type=simple
+# Force the X11 session path (not Wayland) onto the existing headless Xorg.
+# No dbus-run-session wrapper: GNOME integrates with the systemd *user* bus,
+# which this service already inherits — a fresh bus would break that.
+Environment=DISPLAY=:0
+Environment=XDG_SESSION_TYPE=x11
+Environment=XDG_CURRENT_DESKTOP=ubuntu:GNOME
+Environment=GNOME_SHELL_SESSION_MODE=ubuntu
+# Wait for the X server to accept connections before launching the session.
+ExecStartPre=/bin/sh -c 'for i in $(seq 1 20); do xset -display :0 -q >/dev/null 2>&1 && exit 0; sleep 0.5; done; exit 1'
+ExecStart=/usr/bin/gnome-session --session=ubuntu
+Restart=on-failure
+RestartSec=2s
+
+[Install]
+# Lingering user manager reaches default.target without a graphical login,
+# matching the headless-boot drop-in pattern used for Sunshine.
+WantedBy=default.target
--- a/files/headless-desktop-openbox.service
+++ b/files/headless-desktop-openbox.service
@@ -0,0 +1,27 @@
+[Unit]
+Description=Openbox session on the headless Xorg (gives Sunshine something to capture)
+# Without a window manager/desktop running on :0, Sunshine's x11 capture grabs
+# an empty black X root window — pairing, NVENC, and input all work but the
+# client sees only black. This unit renders a session onto :0 so the stream
+# shows an actual desktop. Only relevant to the X11/NVENC capture backend
+# (capture = x11); the wlr backend's compositor renders for itself.
+Requires=xorg-headless.service
+After=xorg-headless.service
+PartOf=graphical-session.target
+
+[Service]
+Type=simple
+Environment=DISPLAY=:0
+# Wait for the X server to accept connections before launching the WM.
+ExecStartPre=/bin/sh -c 'for i in $(seq 1 20); do xset -display :0 -q >/dev/null 2>&1 && exit 0; sleep 0.5; done; exit 1'
+ExecStart=/usr/bin/openbox-session
+# Paint a solid root so a connecting client sees an obvious (non-black) desktop.
+# Leading '-' = best-effort; a missing xsetroot must not fail the unit.
+ExecStartPost=-/usr/bin/xsetroot -display :0 -solid "#2e3440"
+Restart=on-failure
+RestartSec=2s
+
+[Install]
+# Lingering user manager reaches default.target without a graphical login,
+# matching the headless-boot drop-in pattern used for Sunshine.
+WantedBy=default.target
--- a/files/sway-headless.config
+++ b/files/sway-headless.config
@@ -0,0 +1,30 @@
+# Minimal sway config for a headless Sunshine host. Installed by
+# omarchy-moonlight as ~/.config/sway/config-headless. Loaded by the
+# sway-headless.service systemd-user unit on Debian/Ubuntu installs.
+#
+# Goals:
+#   - Boot sway with a single headless output named HEADLESS-1 so Sunshine's
+#     wlr capture has a stable target.
+#   - No keybindings, no bars, no animations. There's no human at the console.
+#   - The sunshine-stream-do-sway.sh hook adjusts HEADLESS-1's mode per client
+#     connect; this config is just the boot-time baseline.
+
+# Create the headless output at startup. Sway accepts `output HEADLESS-1
+# enable` only after the output exists, so we issue create_output here.
+exec swaymsg create_output HEADLESS-1
+
+# Default mode — overridden per-connect by the do-hook.
+output HEADLESS-1 mode 1920x1080@60Hz
+output HEADLESS-1 background #1a1a1a solid_color
+
+# No idle locking on a headless box; no XWayland (would just waste DRM resources).
+xwayland disable
+
+# Don't enable animations / focus-follow / etc — there's no user input here.
+focus_follows_mouse no
+default_border none
+default_floating_border none
+
+# A minimal placeholder so sway has something to display. The actual stream
+# content lives in whatever app the user launches via sunshine commands.
+exec --no-startup-id true
--- a/files/sway-headless.service
+++ b/files/sway-headless.service
@@ -0,0 +1,37 @@
+[Unit]
+Description=Headless Sway compositor for Sunshine wlr capture
+# Don't auto-restart on `systemctl --user stop` — but bring sway back if it
+# actually crashes mid-stream.
+After=graphical-session-pre.target
+PartOf=graphical-session.target
+
+[Service]
+Type=simple
+
+# Tell wlroots to use the headless backend (no DRM master needed) and skip
+# libinput device probing — there are no input devices on a real headless box.
+#
+# GLES2 renderer: the Vulkan backend strictly requires
+# VK_EXT_external_memory_dma_buf, which the proprietary NVIDIA driver
+# doesn't expose on every build (esp. data-center / -server branches). GLES2
+# is universally available and Sunshine's capture path uses its own dma-buf
+# flow, so we don't lose hardware acceleration.
+Environment=WLR_BACKENDS=headless
+Environment=WLR_LIBINPUT_NO_DEVICES=1
+# Pixman (software) renderer. The GLES2 path needs a GBM-allocated framebuffer,
+# which fails on the proprietary NVIDIA driver: its GBM bridge doesn't permit
+# unprivileged CREATE_DUMB even on render nodes (Mesa drivers do). The trade-
+# off: Sunshine's wlr-screencopy then takes the shm path and uses libx264
+# software encoding. For NVENC on NVIDIA cloud GPUs, sunshine should be
+# pointed at a virtual KMS connector (vkms or Xorg+Dummy) instead of wlroots.
+Environment=WLR_RENDERER=pixman
+Environment=XDG_SESSION_TYPE=wayland
+
+ExecStart=/usr/bin/sway --config %h/.config/sway/config-headless --unsupported-gpu
+
+Restart=on-failure
+RestartSec=2s
+TimeoutStopSec=5s
+
+[Install]
+WantedBy=default.target
--- a/install.sh
+++ b/install.sh
@@ -8,6 +8,8 @@ set -euo pipefail
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 # shellcheck source=lib/common.sh
 source "$SCRIPT_DIR/lib/common.sh"
+# shellcheck source=lib/distro.sh
+source "$SCRIPT_DIR/lib/distro.sh"
 # shellcheck source=lib/detect.sh
 source "$SCRIPT_DIR/lib/detect.sh"
 # shellcheck source=lib/preflight.sh
@@ -57,6 +59,9 @@ Environment overrides:
  HEADLESS_HOSTS     Comma-separated hostnames that default to headless mode.
                     Unset by default; anything not listed defaults to mirror.
                     Override per-invocation with --headless or --mirror.
+  HEADLESS_DESKTOP   Desktop to render on the headless Xorg :0 for the X11/NVENC
+                     capture path (capture = x11): 'gnome' (default) or 'openbox'
+                     (lightweight, for minimal hosts). Ignored on wlr/kms.
 EOF
 }

@@ -142,14 +147,14 @@ setup_install_log() {
 main() {
  setup_install_log
  require_not_root
-  require_arch
-  require_yay
+  require_supported_distro

  step "Detecting system"
  detect_all
  compute_stream_mode
  export STREAM_MODE
-  info "Host: $HOSTNAME_SHORT   GPU: $GPU_VENDOR   Session: $SESSION_TYPE"
+  info "Distro: $DISTRO ($DISTRO_ID ${DISTRO_VERSION:-})   Host: $HOSTNAME_SHORT"
+  info "GPU: $GPU_VENDOR   Session: $SESSION_TYPE   Compositor: $COMPOSITOR"
  info "Mode: $STREAM_MODE"

  if [[ $DOCTOR_ONLY -eq 1 ]]; then
@@ -160,6 +165,17 @@ main() {
  step "Preflight checks"
  preflight_all

+  # On headless mode, make sure we have a compositor we can drive. On Arch
+  # this is typically Hyprland (already on Omarchy); on Ubuntu we install Sway
+  # and switch COMPOSITOR before installing hooks.
+  if [[ "$STREAM_MODE" == "headless" && "$COMPOSITOR" == "none" ]]; then
+    step "Installing headless compositor"
+    install_headless_compositor
+    COMPOSITOR="$(detect_compositor)"
+    export COMPOSITOR
+    info "Compositor (after install): $COMPOSITOR"
+  fi
+
  if [[ $INSTALL_SUNSHINE -eq 1 ]]; then
    step "Installing Sunshine and GPU encoder support"
    install_sunshine
@@ -174,6 +190,16 @@ main() {
      step "Installing headless prep-cmd hooks"
      install_headless_hooks
    fi
+
+    # X11/NVENC headless backend (capture = x11): the headless Xorg on :0 has
+    # no compositor of its own, so it needs a window manager rendering on it or
+    # Sunshine captures a black screen. Detected from the existing sunshine.conf
+    # (this backend is hand-configured; see FOLLOWUPS.md P3). Harmless no-op on
+    # the wlr/kms backends, whose capture source renders for itself.
+    if capture_backend_is_x11; then
+      step "Installing headless desktop (${HEADLESS_DESKTOP:-gnome} on :0 for the X11 capture path)"
+      install_headless_desktop
+    fi
    # NOTE: the headless prestart drop-in needs the sunshine unit to already
    # exist; install it after service-unit detection in enable_sunshine_service.

--- a/lib/certs.sh
+++ b/lib/certs.sh
@@ -21,14 +21,21 @@
 SUNSHINE_CRED_DIR="$HOME/.config/sunshine/credentials"
 SUNSHINE_CERT="$SUNSHINE_CRED_DIR/cacert.pem"
 SUNSHINE_KEY="$SUNSHINE_CRED_DIR/cakey.pem"
-SYSTEM_TRUST_ANCHOR="/etc/ca-certificates/trust-source/anchors/omarchy-stream-ca.pem"
+# Resolved per-distro via lib/distro.sh:
+#   Arch:   /etc/ca-certificates/trust-source/anchors/omarchy-stream-ca.pem
+#   Debian: /usr/local/share/ca-certificates/omarchy-stream-ca.crt
+# Read it via ca_anchor_path; do not hard-code here.

 # --- 1Password helpers ----------------------------------------------------

 op_require_signin() {
  if ! command -v op >/dev/null 2>&1; then
    err "1Password CLI ('op') not found on PATH."
-    err "Install it: yay -S 1password-cli"
+    case "$DISTRO" in
+      arch)   err "Install it: yay -S 1password-cli" ;;
+      debian) err "Install it: https://developer.1password.com/docs/cli/get-started/  (apt repo or .deb)" ;;
+      *)      err "Install the 1Password CLI from https://developer.1password.com/docs/cli/get-started/" ;;
+    esac
    return 1
  fi
  if ! op whoami >/dev/null 2>&1; then
@@ -124,16 +131,25 @@ EOF

 install_ca_to_system_trust() {
  local ca_pem="$1"
-  # Idempotent: compare sha256 first to avoid pointless update-ca-trust runs.
-  if [[ -f "$SYSTEM_TRUST_ANCHOR" ]] \
-     && cmp -s "$ca_pem" "$SYSTEM_TRUST_ANCHOR"; then
+  local anchor
+  anchor="$(ca_anchor_path)"
+  if [[ -z "$anchor" ]]; then
+    warn "Don't know how to install CA on distro '$DISTRO' — skipping system trust step."
+    return 0
+  fi
+  # Idempotent: compare sha256 first to avoid pointless update-ca-* runs.
+  if [[ -f "$anchor" ]] && cmp -s "$ca_pem" "$anchor"; then
    ok "CA already in system trust store"
    return 0
  fi
-  info "Installing CA into $SYSTEM_TRUST_ANCHOR"
-  as_root install -m 0644 "$ca_pem" "$SYSTEM_TRUST_ANCHOR"
-  as_root update-ca-trust extract >/dev/null
-  ok "System trust store refreshed (update-ca-trust)"
+  # Debian's update-ca-certificates only picks up files under
+  # /usr/local/share/ca-certificates/ that end in .crt. The path returned by
+  # ca_anchor_path already accounts for that.
+  info "Installing CA into $anchor"
+  as_root mkdir -p "$(dirname "$anchor")"
+  as_root install -m 0644 "$ca_pem" "$anchor"
+  ca_update_trust
+  ok "System trust store refreshed"
 }

 # --- Top-level orchestration ---------------------------------------------
--- a/lib/common.sh
+++ b/lib/common.sh
@@ -29,34 +29,26 @@ require_not_root() {
  fi
 }

-require_arch() {
-  if [[ ! -f /etc/arch-release ]] && ! grep -q '^ID=arch' /etc/os-release 2>/dev/null; then
-    err "This script targets Arch Linux (Omarchy). /etc/arch-release not found."
-    exit 1
-  fi
-}
-
-require_yay() {
-  if ! command -v yay >/dev/null 2>&1; then
-    err "yay is required to install AUR packages. Install yay first."
-    exit 1
-  fi
-}
-
-# True if package is installed (pacman -Qi).
-pkg_installed() { pacman -Qi "$1" >/dev/null 2>&1; }
-
-# Install one or more packages via yay if any are missing.
+# Package management (pkg_installed, pkg_install, etc.) and distro detection
+# live in lib/distro.sh. Source it after this file.
+#
+# yay_install is kept as an alias for code paths that explicitly want AUR
+# packages even on a distro-agnostic call site (rare). On non-Arch distros it
+# falls back to pkg_install.
 yay_install() {
-  local missing=()
-  local p
-  for p in "$@"; do
-    pkg_installed "$p" || missing+=("$p")
-  done
-  if [[ ${#missing[@]} -eq 0 ]]; then
-    ok "Already installed: $*"
-    return 0
+  if [[ "${DISTRO:-}" == "arch" ]] && command -v yay >/dev/null 2>&1; then
+    local missing=()
+    local p
+    for p in "$@"; do
+      pkg_installed "$p" || missing+=("$p")
+    done
+    if [[ ${#missing[@]} -eq 0 ]]; then
+      ok "Already installed: $*"
+      return 0
+    fi
+    info "Installing (AUR): ${missing[*]}"
+    yay -S --needed --noconfirm "${missing[@]}"
+  else
+    pkg_install "$@"
  fi
-  info "Installing: ${missing[*]}"
-  yay -S --needed --noconfirm "${missing[@]}"
 }
--- a/lib/config.sh
+++ b/lib/config.sh
@@ -70,10 +70,10 @@ $encoder_block
 min_threads = 4

 # Audio sink is intentionally left unset so Sunshine auto-detects the default
-# PulseAudio/PipeWire sink and creates its virtual `sink-sunshine-stereo`.
+# PulseAudio/PipeWire sink and creates its virtual 'sink-sunshine-stereo'.
 # Hard-coding audio_sink = pulse here breaks capture: Sunshine treats it as a
 # literal sink name, can't resolve its monitor source, and pa_simple_new()
-# fails with "Invalid argument" → no audio in the stream.
+# fails with "Invalid argument" -> no audio in the stream.

 # Keyboard / mouse / gamepad pass-through via /dev/uinput.
 # (Requires user to be in the 'input' group; install.sh handles this.)
--- a/lib/detect.sh
+++ b/lib/detect.sh
@@ -1,25 +1,47 @@
 #!/usr/bin/env bash
-# Detect GPU vendor, session type, hostname.
+# Detect GPU vendor, session type, hostname, compositor.

 detect_gpu_vendor() {
  local vga
  vga="$(lspci -nn 2>/dev/null | grep -iE 'vga|3d|display' || true)"
-  if grep -qi 'nvidia' <<<"$vga"; then
+  # Prefer the first discrete/dedicated entry — VM hosts often expose a
+  # placeholder BOCHS/QEMU VGA device before the real GPU.
+  local nvidia_line amd_line intel_line
+  nvidia_line="$(grep -i 'nvidia' <<<"$vga" | head -n1)"
+  amd_line="$(grep -iE 'amd|advanced micro devices|ati' <<<"$vga" | head -n1)"
+  intel_line="$(grep -i 'intel' <<<"$vga" | head -n1)"
+  if [[ -n "$nvidia_line" ]]; then
    echo "nvidia"
-  elif grep -qiE 'amd|advanced micro devices|ati' <<<"$vga"; then
+  elif [[ -n "$amd_line" ]]; then
    echo "amd"
-  elif grep -qi 'intel' <<<"$vga"; then
+  elif [[ -n "$intel_line" ]]; then
    echo "intel"
  else
    echo "unknown"
  fi
 }

+# Decide which wlroots-based compositor to drive for headless capture.
+# Returns one of:
+#   hyprland   - hyprctl available (preferred when present, matches existing hooks)
+#   sway       - sway/swaymsg available
+#   none       - neither installed yet (install_headless_compositor will fix this)
+detect_compositor() {
+  if command -v hyprctl >/dev/null 2>&1; then
+    echo "hyprland"
+  elif command -v swaymsg >/dev/null 2>&1 || command -v sway >/dev/null 2>&1; then
+    echo "sway"
+  else
+    echo "none"
+  fi
+}
+
 detect_all() {
  HOSTNAME_SHORT="$(hostname -s 2>/dev/null || hostname)"
  GPU_VENDOR="$(detect_gpu_vendor)"
  SESSION_TYPE="${XDG_SESSION_TYPE:-unknown}"
-  export HOSTNAME_SHORT GPU_VENDOR SESSION_TYPE
+  COMPOSITOR="$(detect_compositor)"
+  export HOSTNAME_SHORT GPU_VENDOR SESSION_TYPE COMPOSITOR

  if [[ "$SESSION_TYPE" != "wayland" ]]; then
    warn "Session type is '$SESSION_TYPE' (not wayland). KMS capture still works at the TTY/DRM level, but Hyprland-specific paths assume Wayland."
--- a/lib/distro.sh
+++ b/lib/distro.sh
@@ -0,0 +1,174 @@
+#!/usr/bin/env bash
+# Distro detection + small dispatch layer so the rest of the installer can
+# stay distro-agnostic. Two backends supported today: Arch (Omarchy) and
+# Debian/Ubuntu.
+#
+# Sourced once at the top of install.sh / uninstall.sh. detect_distro must
+# run before any of the dispatch helpers; require_supported_distro calls it
+# for you.
+
+# Populated by detect_distro:
+#   DISTRO          - "arch" | "debian" (ubuntu folds into debian)
+#   DISTRO_ID       - raw ID from /etc/os-release (e.g. "ubuntu", "arch")
+#   DISTRO_VERSION  - VERSION_ID from /etc/os-release (e.g. "24.04"), empty on Arch
+detect_distro() {
+  if [[ -n "${DISTRO:-}" ]]; then
+    return 0
+  fi
+
+  local id="" id_like="" version_id=""
+  if [[ -r /etc/os-release ]]; then
+    # shellcheck disable=SC1091
+    . /etc/os-release
+    id="${ID:-}"
+    id_like="${ID_LIKE:-}"
+    version_id="${VERSION_ID:-}"
+  fi
+
+  DISTRO_ID="$id"
+  DISTRO_VERSION="$version_id"
+
+  case "$id" in
+    arch|manjaro|endeavouros|omarchy)
+      DISTRO="arch"
+      ;;
+    ubuntu|debian|pop|linuxmint)
+      DISTRO="debian"
+      ;;
+    *)
+      # Fall back to ID_LIKE.
+      if [[ " $id_like " == *" arch "* ]]; then
+        DISTRO="arch"
+      elif [[ " $id_like " == *" debian "* || " $id_like " == *" ubuntu "* ]]; then
+        DISTRO="debian"
+      elif [[ -f /etc/arch-release ]]; then
+        DISTRO="arch"
+      elif command -v apt-get >/dev/null 2>&1; then
+        DISTRO="debian"
+      elif command -v pacman >/dev/null 2>&1; then
+        DISTRO="arch"
+      else
+        DISTRO="unknown"
+      fi
+      ;;
+  esac
+  export DISTRO DISTRO_ID DISTRO_VERSION
+}
+
+require_supported_distro() {
+  detect_distro
+  case "$DISTRO" in
+    arch)
+      if ! command -v yay >/dev/null 2>&1; then
+        err "yay is required to install AUR packages on Arch. Install yay first."
+        exit 1
+      fi
+      ;;
+    debian)
+      if ! command -v apt-get >/dev/null 2>&1; then
+        err "apt-get not found — Debian/Ubuntu install path requires it."
+        exit 1
+      fi
+      ;;
+    *)
+      err "Unsupported distro (ID='${DISTRO_ID:-unknown}'). Supported: Arch family, Debian/Ubuntu family."
+      exit 1
+      ;;
+  esac
+}
+
+# ---------------------------------------------------------------------------
+# Package query / install dispatch.
+
+# True if package is installed.
+pkg_installed() {
+  case "$DISTRO" in
+    arch)   pacman -Qi "$1" >/dev/null 2>&1 ;;
+    debian) dpkg-query -W -f='${Status}' "$1" 2>/dev/null | grep -q '^install ok installed$' ;;
+    *)      return 1 ;;
+  esac
+}
+
+# Install one or more packages. Idempotent: only installs missing ones.
+# On Arch, uses yay; on Debian/Ubuntu, uses apt-get. The Arch-only yay_install
+# function below is kept as an alias for code that explicitly wants AUR.
+pkg_install() {
+  local missing=()
+  local p
+  for p in "$@"; do
+    pkg_installed "$p" || missing+=("$p")
+  done
+  if [[ ${#missing[@]} -eq 0 ]]; then
+    ok "Already installed: $*"
+    return 0
+  fi
+  info "Installing: ${missing[*]}"
+  case "$DISTRO" in
+    arch)
+      yay -S --needed --noconfirm "${missing[@]}"
+      ;;
+    debian)
+      _apt_ensure_updated
+      as_root env DEBIAN_FRONTEND=noninteractive apt-get install -y --no-install-recommends "${missing[@]}"
+      ;;
+    *)
+      err "Don't know how to install packages on distro '$DISTRO'"
+      return 1
+      ;;
+  esac
+}
+
+# Cache `apt-get update` for this script run; running it on every pkg_install
+# call would be slow and noisy.
+_APT_UPDATED=0
+_apt_ensure_updated() {
+  [[ "$_APT_UPDATED" -eq 1 ]] && return 0
+  info "Refreshing apt package lists"
+  as_root env DEBIAN_FRONTEND=noninteractive apt-get update -y >/dev/null
+  _APT_UPDATED=1
+}
+
+# Install a local .deb file. Resolves its dependencies via apt.
+deb_install_local() {
+  local deb_path="$1"
+  [[ -f "$deb_path" ]] || { err "deb not found: $deb_path"; return 1; }
+  _apt_ensure_updated
+  info "Installing $(basename "$deb_path") via apt-get"
+  as_root env DEBIAN_FRONTEND=noninteractive apt-get install -y --no-install-recommends "$deb_path"
+}
+
+# Remove a package if installed. Quiet no-op if absent.
+pkg_remove() {
+  local p
+  for p in "$@"; do
+    pkg_installed "$p" || continue
+    case "$DISTRO" in
+      arch)   as_root pacman -Rns --noconfirm "$p" ;;
+      debian) as_root env DEBIAN_FRONTEND=noninteractive apt-get purge -y "$p" ;;
+    esac
+  done
+}
+
+# ---------------------------------------------------------------------------
+# CA trust-store dispatch.
+#
+# Arch:     /etc/ca-certificates/trust-source/anchors/<name>.pem  + update-ca-trust
+# Debian:   /usr/local/share/ca-certificates/<name>.crt           + update-ca-certificates
+
+# Path where we'll drop our CA anchor for this distro. Stable across runs.
+ca_anchor_path() {
+  case "$DISTRO" in
+    arch)   echo "/etc/ca-certificates/trust-source/anchors/omarchy-stream-ca.pem" ;;
+    debian) echo "/usr/local/share/ca-certificates/omarchy-stream-ca.crt" ;;
+    *)      echo "" ;;
+  esac
+}
+
+# Refresh the system trust store after writing a new anchor.
+ca_update_trust() {
+  case "$DISTRO" in
+    arch)   as_root update-ca-trust extract >/dev/null ;;
+    debian) as_root update-ca-certificates >/dev/null ;;
+    *)      warn "Unknown distro — CA trust update skipped"; return 1 ;;
+  esac
+}
--- a/lib/headless.sh
+++ b/lib/headless.sh
@@ -3,27 +3,129 @@
 # location and ensure they're executable. The actual sunshine.conf entries
 # (capture=wlr, output_name=HEADLESS-1, global_prep_cmd=[...]) are written
 # by lib/config.sh.
+#
+# Two compositor backends supported:
+#   - hyprland (default on Omarchy/Arch): bin/sunshine-stream-{do,undo}.sh
+#   - sway     (default on Debian/Ubuntu): bin/sunshine-stream-{do,undo}-sway.sh
+# detect_compositor (lib/detect.sh) decides which to install. The script names
+# at the install target are *always* sunshine-stream-do.sh / -undo.sh, so the
+# rest of the installer (config.sh, verify.sh) doesn't have to branch.

 HEADLESS_BIN_DIR="$HOME/.local/share/omarchy-moonlight/bin"

 DO_SCRIPT="$HEADLESS_BIN_DIR/sunshine-stream-do.sh"
 UNDO_SCRIPT="$HEADLESS_BIN_DIR/sunshine-stream-undo.sh"
-export DO_SCRIPT UNDO_SCRIPT
+PRESTART_SCRIPT="$HEADLESS_BIN_DIR/sunshine-prestart.sh"
+export DO_SCRIPT UNDO_SCRIPT PRESTART_SCRIPT
+
+# Resolve which hook source files to install based on the detected compositor.
+_headless_hook_sources() {
+  case "${COMPOSITOR:-hyprland}" in
+    sway)
+      echo "$SCRIPT_DIR/bin/sunshine-stream-do-sway.sh"
+      echo "$SCRIPT_DIR/bin/sunshine-stream-undo-sway.sh"
+      echo "$SCRIPT_DIR/bin/sunshine-prestart-sway.sh"
+      ;;
+    hyprland|*)
+      echo "$SCRIPT_DIR/bin/sunshine-stream-do.sh"
+      echo "$SCRIPT_DIR/bin/sunshine-stream-undo.sh"
+      echo "$SCRIPT_DIR/bin/sunshine-prestart.sh"
+      ;;
+  esac
+}
+
+# The X11/NVENC headless backend (capture = x11, headless Xorg on :0) isn't
+# selected by --headless/--mirror — those pick the *Wayland* capture method.
+# It's identified by an existing `capture = x11` in sunshine.conf, the
+# hand-built path documented in FOLLOWUPS.md P3. When that backend is in play,
+# the headless Xorg needs a window manager rendering on :0 or Sunshine
+# captures a black screen.
+capture_backend_is_x11() {
+  local conf="$HOME/.config/sunshine/sunshine.conf"
+  [[ -f "$conf" ]] || return 1
+  grep -qE '^[[:space:]]*capture[[:space:]]*=[[:space:]]*x11' "$conf"
+}
+
+HEADLESS_DESKTOP_UNIT="headless-desktop.service"
+
+# Which desktop to render on the headless Xorg :0. Default is a full GNOME
+# session (the familiar Ubuntu desktop). Set HEADLESS_DESKTOP=openbox for a
+# lightweight bare WM instead — lower overhead, better for a truly minimal or
+# low-power host, but no panel/launcher out of the box (right-click menu only).
+: "${HEADLESS_DESKTOP:=gnome}"
+
+# Install the packages the chosen desktop needs. Idempotent — pkg_install
+# skips what's already present.
+ensure_headless_desktop_packages() {
+  case "$HEADLESS_DESKTOP" in
+    gnome)
+      case "$DISTRO" in
+        debian) pkg_install gnome-session gnome-shell ubuntu-session ;;
+        arch)   pkg_install gnome-shell gnome-session ;;
+      esac
+      ;;
+    openbox)
+      command -v openbox-session >/dev/null 2>&1 || pkg_install openbox
+      # xsetroot paints a solid root so the bare desktop is visibly non-black.
+      if ! command -v xsetroot >/dev/null 2>&1; then
+        case "$DISTRO" in
+          debian) pkg_install x11-xserver-utils ;;
+          arch)   pkg_install xorg-xsetroot ;;
+        esac
+      fi
+      ;;
+    *)
+      err "Unknown HEADLESS_DESKTOP='$HEADLESS_DESKTOP' (expected: gnome | openbox)"
+      return 1
+      ;;
+  esac
+}
+
+# Install + enable a desktop session that renders onto the headless Xorg
+# display (:0), so the X11/NVENC capture path shows a real desktop instead of a
+# black root window. Picks the GNOME or Openbox unit template per
+# $HEADLESS_DESKTOP. Idempotent: safe to re-run. Bound to xorg-headless.service
+# and to default.target (the lingering-user manager reaches it without a login).
+install_headless_desktop() {
+  local src="$SCRIPT_DIR/files/headless-desktop-${HEADLESS_DESKTOP}.service"
+  if [[ ! -f "$src" ]]; then
+    err "Desktop unit source missing: $src (HEADLESS_DESKTOP=$HEADLESS_DESKTOP)"
+    return 1
+  fi
+
+  ensure_headless_desktop_packages || return 1
+
+  local unit_dir="$HOME/.config/systemd/user"
+  mkdir -p "$unit_dir"
+  install -m 0644 "$src" "$unit_dir/$HEADLESS_DESKTOP_UNIT"
+  systemctl --user daemon-reload
+
+  # enable --now starts it immediately when a user manager is live; on a fresh
+  # headless box with no session yet, fall back to enable-only so it comes up
+  # on next boot via default.target.
+  if systemctl --user enable --now "$HEADLESS_DESKTOP_UNIT" >/dev/null 2>&1; then
+    ok "Enabled $HEADLESS_DESKTOP_UNIT ($HEADLESS_DESKTOP session on :0)"
+  else
+    systemctl --user enable "$HEADLESS_DESKTOP_UNIT" >/dev/null 2>&1 || true
+    warn "Installed $HEADLESS_DESKTOP_UNIT but couldn't start it now — it will start on next login/boot."
+  fi
+}

 install_headless_hooks() {
-  # Install hook scripts to ~/.local/share so they don't disappear if the
-  # repo gets moved or deleted. Sunshine's config will reference these stable paths.
  mkdir -p "$HEADLESS_BIN_DIR"
-  install -m 0755 "$SCRIPT_DIR/bin/sunshine-stream-do.sh"   "$DO_SCRIPT"
-  install -m 0755 "$SCRIPT_DIR/bin/sunshine-stream-undo.sh" "$UNDO_SCRIPT"
-  install -m 0755 "$SCRIPT_DIR/bin/sunshine-prestart.sh"    "$HEADLESS_BIN_DIR/sunshine-prestart.sh"
-  ok "Installed prep-cmd + prestart hooks to $HEADLESS_BIN_DIR"
+  mapfile -t srcs < <(_headless_hook_sources)
+  local do_src="${srcs[0]}" undo_src="${srcs[1]}" pre_src="${srcs[2]}"
+
+  install -m 0755 "$do_src"   "$DO_SCRIPT"
+  install -m 0755 "$undo_src" "$UNDO_SCRIPT"
+  install -m 0755 "$pre_src"  "$PRESTART_SCRIPT"
+  ok "Installed prep-cmd + prestart hooks ($COMPOSITOR) to $HEADLESS_BIN_DIR"
 }

 # Install a systemd-user drop-in that pre-creates HEADLESS-1 before Sunshine
-# starts, so the encoder probe at startup sees a valid Wayland output. Without
-# this, Sunshine reports a fatal "Unable to find display or encoder during
-# startup" on every restart, even though streaming works once a client connects.
+# starts. Without this, Sunshine reports a fatal "Unable to find display or
+# encoder during startup" on every restart, even though streaming works once
+# a client connects.
 install_headless_prestart_dropin() {
  local dropin_src="$SCRIPT_DIR/files/headless-prestart.conf"
  if [[ ! -f "$dropin_src" ]]; then
@@ -31,8 +133,9 @@ install_headless_prestart_dropin() {
    return 1
  fi

-  # Resolve the actual unit name. Prefer sunshine.service when present (alias
-  # or sunshine-bin); fall back to the AUR source pkg's reverse-DNS name.
+  # Resolve the actual unit name. Prefer sunshine.service when present (alias,
+  # sunshine-bin, or the .deb on Ubuntu); fall back to the AUR source pkg's
+  # reverse-DNS name.
  local unit=""
  for u in sunshine.service app-dev.lizardbyte.app.Sunshine.service; do
    if systemctl --user list-unit-files "$u" >/dev/null 2>&1 \
--- a/lib/packages.sh
+++ b/lib/packages.sh
@@ -1,5 +1,8 @@
 #!/usr/bin/env bash
 # Install Sunshine, Moonlight, and GPU-specific hardware-encode dependencies.
+# Branches by $DISTRO (set by lib/distro.sh).
+
+# --- Arch defaults --------------------------------------------------------

 # Default to the precompiled AUR build for a fast install (~seconds instead of
 # the ~10 minute source compile). Override with SUNSHINE_PKG=sunshine to build
@@ -7,7 +10,24 @@
 : "${SUNSHINE_PKG:=sunshine-bin}"
 : "${MOONLIGHT_PKG:=moonlight-qt}"

+# --- Debian/Ubuntu defaults ----------------------------------------------
+
+# LizardByte ships official .deb builds per Ubuntu release on GitHub.
+# Resolved at runtime by _ubuntu_sunshine_deb_url to match this host.
+: "${SUNSHINE_DEB_URL:=}"
+: "${SUNSHINE_DEB_VERSION:=latest}"
+
 install_sunshine() {
+  case "$DISTRO" in
+    arch)   _install_sunshine_arch ;;
+    debian) _install_sunshine_debian ;;
+    *)      err "install_sunshine: unsupported distro '$DISTRO'"; return 1 ;;
+  esac
+}
+
+# --- Arch implementation -------------------------------------------------
+
+_install_sunshine_arch() {
  # Ensure runtime deps useful for capture/diagnostics across vendors.
  yay_install pipewire-pulse vulkan-tools libva-utils jq

@@ -59,6 +79,71 @@ install_sunshine() {
  fi
 }

+# --- Debian/Ubuntu implementation ----------------------------------------
+
+# LizardByte's sunshine .deb assets are named per Ubuntu codename / version,
+# e.g. sunshine-ubuntu-24.04-amd64.deb. Resolve the right one for this host.
+_ubuntu_sunshine_deb_filename() {
+  local arch
+  arch="$(dpkg --print-architecture 2>/dev/null || echo amd64)"
+  local v="${DISTRO_VERSION:-24.04}"
+  echo "sunshine-ubuntu-${v}-${arch}.deb"
+}
+
+# Resolve the download URL. If SUNSHINE_DEB_URL is set, honor it (escape hatch
+# for offline mirrors / version pinning). Otherwise build a GitHub Releases
+# URL — 'latest' uses the redirecting /latest/download/ alias.
+_ubuntu_sunshine_deb_url() {
+  if [[ -n "$SUNSHINE_DEB_URL" ]]; then
+    echo "$SUNSHINE_DEB_URL"
+    return 0
+  fi
+  local file
+  file="$(_ubuntu_sunshine_deb_filename)"
+  if [[ "$SUNSHINE_DEB_VERSION" == "latest" ]]; then
+    echo "https://github.com/LizardByte/Sunshine/releases/latest/download/${file}"
+  else
+    echo "https://github.com/LizardByte/Sunshine/releases/download/${SUNSHINE_DEB_VERSION}/${file}"
+  fi
+}
+
+_install_sunshine_debian() {
+  # Universal runtime deps. vainfo is what Ubuntu calls libva-utils on Arch.
+  # pipewire-pulse is the Ubuntu 24.04+ default audio path; on older releases
+  # `pulseaudio-utils` works too — we don't force the codename split since
+  # sunshine just needs *a* PulseAudio API endpoint.
+  pkg_install jq vulkan-tools vainfo curl ca-certificates
+
+  if pkg_installed sunshine; then
+    ok "sunshine already installed (dpkg)"
+    return 0
+  fi
+
+  local url
+  url="$(_ubuntu_sunshine_deb_url)"
+  local tmpdir deb_path
+  tmpdir="$(mktemp -d /tmp/omarchy-sunshine.XXXXXX)"
+  # shellcheck disable=SC2064
+  trap "rm -rf '$tmpdir'" RETURN
+  deb_path="$tmpdir/$(_ubuntu_sunshine_deb_filename)"
+
+  info "Downloading Sunshine .deb: $url"
+  if ! curl -fL --retry 3 -o "$deb_path" "$url"; then
+    err "Failed to download $url"
+    err "If your Ubuntu version doesn't have a prebuilt .deb, set SUNSHINE_DEB_URL"
+    err "or SUNSHINE_DEB_VERSION (e.g. SUNSHINE_DEB_VERSION=v2025.118.84544 ./install.sh)."
+    return 1
+  fi
+
+  deb_install_local "$deb_path"
+
+  if ! command -v sunshine >/dev/null 2>&1; then
+    err "sunshine command not on PATH after install — package layout unexpected."
+    return 1
+  fi
+  ok "Installed sunshine from $(basename "$deb_path")"
+}
+
 # True if every shared library sunshine links against resolves on this system.
 sunshine_runtime_deps_ok() {
  local bin
@@ -68,17 +153,40 @@ sunshine_runtime_deps_ok() {
 }

 install_moonlight() {
-  yay_install "$MOONLIGHT_PKG"
+  case "$DISTRO" in
+    arch)
+      yay_install "$MOONLIGHT_PKG"
+      ;;
+    debian)
+      # moonlight-qt is published as a PPA + flatpak. On a typical Ubuntu host
+      # the flatpak is the lowest-friction install path; falling back to apt
+      # requires adding the cloudsmith PPA. For a headless server (the primary
+      # Ubuntu target here) the client side is almost never wanted — so this
+      # is best-effort.
+      if pkg_installed moonlight-qt; then
+        ok "moonlight-qt already installed"
+        return 0
+      fi
+      if command -v flatpak >/dev/null 2>&1; then
+        info "Installing moonlight-qt via flatpak"
+        as_root flatpak install -y flathub com.moonlight_stream.Moonlight || {
+          warn "flatpak install of Moonlight failed — install it manually if needed."
+        }
+      else
+        warn "moonlight-qt: no apt package in Ubuntu's default repos and no flatpak available."
+        warn "    Install flatpak first, or grab the .deb from https://github.com/moonlight-stream/moonlight-qt/releases"
+        warn "    Skipping — headless hosts rarely need the client anyway."
+      fi
+      ;;
+  esac
 }

 install_gpu_encoder_packages() {
-  case "$GPU_VENDOR" in
-    nvidia)
-      # NVENC works through the proprietary driver. libva-nvidia-driver lets some
-      # apps use VAAPI on NVIDIA; not strictly required for Sunshine NVENC but useful.
+  case "$DISTRO:$GPU_VENDOR" in
+    arch:nvidia)
      yay_install nvidia-utils libva-nvidia-driver
      ;;
-    amd)
+    arch:amd)
      # VAAPI (mesa) + Vulkan for AMD hardware encode paths.
      # libva-mesa-driver is now provided by mesa (merged upstream); mesa-vdpau
      # was removed from official repos. Naming them here makes yay fall back to
@@ -86,11 +194,68 @@ install_gpu_encoder_packages() {
      # `provides=(libva-mesa-driver mesa-vdpau)`.
      yay_install mesa vulkan-radeon
      ;;
-    intel)
+    arch:intel)
      yay_install intel-media-driver vulkan-intel
      ;;
+    debian:nvidia)
+      # Ubuntu's nvidia-driver-NNN(-server) metapackage pulls in the matching
+      # libnvidia-encode-NNN(-server) as a dependency, so NVENC is normally
+      # already present. Only intervene if it's missing — and derive the right
+      # package name from the loaded driver's major version instead of
+      # guessing.
+      if dpkg-query -W -f='${Status}\n' 'libnvidia-encode-*' 2>/dev/null \
+         | grep -q '^install ok installed$'; then
+        ok "NVENC runtime library already installed via the driver metapackage"
+      else
+        local drv_major drv_full
+        drv_full="$(nvidia-smi --query-gpu=driver_version --format=csv,noheader,nounits 2>/dev/null | head -n1)"
+        drv_major="${drv_full%%.*}"
+        if [[ -z "$drv_major" ]]; then
+          warn "Could not detect NVIDIA driver version; NVENC may be missing."
+        else
+          # Try -server first (cloud GPUs usually run server branches), then the
+          # consumer branch. Stop at the first one apt knows about.
+          local picked=""
+          for cand in "libnvidia-encode-${drv_major}-server" "libnvidia-encode-${drv_major}"; do
+            if apt-cache show "$cand" >/dev/null 2>&1; then
+              picked="$cand"; break
+            fi
+          done
+          if [[ -n "$picked" ]]; then
+            pkg_install "$picked"
+          else
+            warn "No libnvidia-encode-${drv_major}* package in apt — install it manually if NVENC fails."
+          fi
+        fi
+      fi
+      ;;
+    debian:amd)
+      pkg_install mesa-va-drivers mesa-vulkan-drivers vainfo
+      ;;
+    debian:intel)
+      pkg_install intel-media-va-driver-non-free mesa-vulkan-drivers
+      ;;
    *)
-      info "Unknown GPU vendor; skipping vendor-specific encoder packages."
+      info "Unknown distro/GPU combination ($DISTRO:$GPU_VENDOR); skipping vendor-specific encoder packages."
+      ;;
+  esac
+}
+
+# Install a wlroots-based compositor for headless capture on systems without
+# Hyprland. Currently means: Sway on Debian/Ubuntu. On Arch the existing
+# Hyprland flow is the canonical path; we only fall back to Sway if Hyprland
+# isn't installed (rare on Omarchy).
+install_headless_compositor() {
+  case "$DISTRO" in
+    debian)
+      pkg_install sway wlr-randr
+      ;;
+    arch)
+      # Hyprland is presumed installed on Omarchy. Only act if it's missing.
+      if ! command -v hyprctl >/dev/null 2>&1; then
+        warn "hyprctl not found on Arch — falling back to Sway for headless capture."
+        yay_install sway wlr-randr
+      fi
      ;;
  esac
 }
--- a/lib/permissions.sh
+++ b/lib/permissions.sh
@@ -8,13 +8,33 @@ UINPUT_RULE_PATH="/etc/udev/rules.d/60-uinput.rules"
 UINPUT_RULE_CONTENT='KERNEL=="uinput", SUBSYSTEM=="misc", OPTIONS+="static_node=uinput", TAG+="uaccess", OWNER="root", GROUP="input", MODE="0660"'

 ensure_input_group() {
-  if id -nG "$USER" | tr ' ' '\n' | grep -qx input; then
-    ok "User '$USER' already in 'input' group"
+  _ensure_user_in_group input
+  # On Debian/Ubuntu, /dev/dri/renderD* nodes are mode 0660 owned by
+  # root:render, and /dev/dri/card* are root:video. Sway's wlroots renderer
+  # needs the render node (Vulkan/GLES FD); KMS capture needs the card node.
+  # Arch typically grants both via udev tag=uaccess for the logged-in seat,
+  # so we only add explicit memberships on Debian.
+  if [[ "${DISTRO:-}" == "debian" ]]; then
+    _ensure_user_in_group render
+    _ensure_user_in_group video
+  fi
+}
+
+# Internal: add $USER to a group if it exists and they're not already in it.
+_ensure_user_in_group() {
+  local g="$1"
+  if ! getent group "$g" >/dev/null 2>&1; then
+    info "Group '$g' does not exist on this system — skipping."
    return 0
  fi
-  info "Adding '$USER' to 'input' group"
-  as_root usermod -aG input "$USER"
-  warn "You must log out and back in (or run 'newgrp input') for this to take effect."
+  if id -nG "$USER" | tr ' ' '\n' | grep -qx "$g"; then
+    ok "User '$USER' already in '$g' group"
+    return 0
+  fi
+  info "Adding '$USER' to '$g' group"
+  as_root usermod -aG "$g" "$USER"
+  warn "Group '$g' change takes effect on next login (or 'newgrp $g'). For systemd-user"
+  warn "services, you must fully log out and back in so the user manager restarts."
 }

 ensure_uinput_udev_rule() {
--- a/lib/preflight.sh
+++ b/lib/preflight.sh
@@ -35,7 +35,22 @@ preflight_gpu() {
  case "$GPU_VENDOR" in
    nvidia)
      if ! command -v nvidia-smi >/dev/null 2>&1; then
-        warn "nvidia-smi not found yet — nvidia-utils will be installed shortly."
+        case "$DISTRO" in
+          arch)
+            warn "nvidia-smi not found yet — nvidia-utils will be installed shortly."
+            ;;
+          debian)
+            # On Ubuntu the NVIDIA driver install isn't our job; we don't pull
+            # in nvidia-driver-* because the right version depends on the
+            # kernel / Secure Boot / cloud-vendor combo. Tell the user.
+            err "nvidia-smi not found and no NVIDIA kernel module loaded."
+            err "Install the driver before re-running this installer. Common paths on Ubuntu:"
+            err "    sudo ubuntu-drivers install   # picks the recommended branch"
+            err "    sudo apt install nvidia-driver-550-server   # explicit pin"
+            err "Then reboot (or modprobe nvidia) so 'nvidia-smi -L' returns the GPU."
+            exit 1
+            ;;
+        esac
        return 0
      fi
      if ! nvidia-smi -L >/dev/null 2>&1; then
@@ -53,7 +68,7 @@ preflight_gpu() {
      fi
      ;;
    intel)
-      ok "Intel GPU — will install intel-media-driver"
+      ok "Intel GPU — encoder packages will be installed in the packages step."
      ;;
  esac
 }
@@ -100,30 +115,41 @@ preflight_audio() {

 preflight_headless() {
  # Only relevant in headless mode. Checks are non-fatal: install can proceed
-  # even if Hyprland isn't reachable right now (hooks just won't function until
-  # the user logs into Hyprland on the host).
+  # even if the compositor isn't reachable right now (hooks just won't
+  # function until it is).
  [[ "${STREAM_MODE:-}" == "headless" ]] || return 0

-  if command -v hyprctl >/dev/null 2>&1; then
-    ok "hyprctl on PATH"
-  else
-    warn "hyprctl not found. Headless prep-cmd hooks will fail until Hyprland is installed and reachable."
-  fi
+  case "${COMPOSITOR:-none}" in
+    hyprland)
+      ok "hyprctl on PATH"
+      if [[ -n "${HYPRLAND_INSTANCE_SIGNATURE:-}" ]]; then
+        ok "Hyprland instance signature present in environment"
+      else
+        local rt="${XDG_RUNTIME_DIR:-/run/user/$(id -u)}"
+        if compgen -G "$rt/hypr/*/" >/dev/null 2>&1; then
+          ok "Hyprland runtime directory found under $rt/hypr/"
+        else
+          warn "Hyprland not currently running. Install will proceed; hooks engage on next Hyprland login."
+        fi
+      fi
+      ;;
+    sway)
+      ok "swaymsg/sway on PATH"
+      local rt="${XDG_RUNTIME_DIR:-/run/user/$(id -u)}"
+      if compgen -G "$rt/sway-ipc.*.sock" >/dev/null 2>&1; then
+        ok "Sway IPC socket present under $rt"
+      else
+        info "Sway not running yet — install will start sway-headless.service before sunshine."
+      fi
+      ;;
+    none|*)
+      warn "No wlroots compositor detected. Install will attempt to install one (Sway on Debian/Ubuntu)."
+      ;;
+  esac

  if pkg_installed jq; then
    ok "jq installed (prep-cmd hooks have their parser)"
  else
    info "jq not installed yet — will be installed in the packages step."
  fi
-
-  if [[ -n "${HYPRLAND_INSTANCE_SIGNATURE:-}" ]]; then
-    ok "Hyprland instance signature present in environment"
-  else
-    local rt="${XDG_RUNTIME_DIR:-/run/user/$(id -u)}"
-    if compgen -G "$rt/hypr/*/" >/dev/null 2>&1; then
-      ok "Hyprland runtime directory found under $rt/hypr/"
-    else
-      warn "Hyprland does not appear to be running. Install will proceed; hooks will only work once you log into Hyprland on the host."
-    fi
-  fi
 }
--- a/lib/service.sh
+++ b/lib/service.sh
@@ -1,34 +1,61 @@
 #!/usr/bin/env bash
 # Enable Sunshine as a systemd --user service and turn on lingering so it
-# runs at boot without a graphical login.
+# runs at boot without a graphical login. On Ubuntu installs that use the
+# Sway-headless capture path, also installs + enables sway-headless.service
+# and wires sunshine.service to depend on it.

+# Resolves the actual unit file to operate on. Exports:
+#   SUNSHINE_ENABLE_NAME - the name to pass to `systemctl --user enable`. May
+#                          be sunshine.service or app-dev.lizardbyte....service
+#                          depending on how the package shipped the unit.
+#   SUNSHINE_SERVICE     - the short name we use everywhere else (start, restart,
+#                          status, drop-ins). Always sunshine.service — systemd
+#                          resolves it via Alias= or our installed unit.
 ensure_sunshine_unit_present() {
-  # Case 1: a sunshine.service unit already exists in any path systemd-user
-  # scans. sunshine-bin ships /usr/lib/systemd/user/sunshine.service directly.
+  SUNSHINE_SERVICE="sunshine.service"
+
+  # Clean up a broken symlink from older runs that pointed sunshine.service
+  # at the FQDN unit. The upstream .deb already declares Alias=sunshine.service
+  # in [Install], so the symlink we used to create conflicts with systemd's
+  # enable path ("Refusing to operate on alias name").
+  local user_unit="$HOME/.config/systemd/user/sunshine.service"
+  if [[ -L "$user_unit" ]] && readlink "$user_unit" 2>/dev/null \
+     | grep -q 'app-dev.lizardbyte.app.Sunshine.service$'; then
+    info "Removing stale alias symlink at $user_unit (upstream unit declares Alias=)"
+    rm -f "$user_unit"
+  fi
+
+  # Case 1: a real sunshine.service unit ships in a system path (sunshine-bin
+  # on Arch drops it at /usr/lib/systemd/user/).
  for p in \
+    /lib/systemd/user/sunshine.service \
    /usr/lib/systemd/user/sunshine.service \
    /etc/systemd/user/sunshine.service \
-    "$HOME/.config/systemd/user/sunshine.service" \
    "$HOME/.local/share/systemd/user/sunshine.service"
  do
-    [[ -e "$p" ]] && return 0
+    if [[ -f "$p" && ! -L "$p" ]]; then
+      SUNSHINE_ENABLE_NAME="sunshine.service"
+      export SUNSHINE_ENABLE_NAME SUNSHINE_SERVICE
+      return 0
+    fi
  done

-  # Case 2: the AUR source 'sunshine' package ships the unit under a
-  # Flatpak-style reverse-DNS name. Symlink it as sunshine.service so the rest
-  # of our tooling can keep using the short name.
+  # Case 2: the LizardByte .deb (Ubuntu) and the AUR source package ship the
+  # unit under a reverse-DNS FQDN with Alias=sunshine.service in [Install].
+  # Do NOT symlink — `systemctl --user enable` on the FQDN name creates the
+  # alias symlink itself in ~/.config/systemd/user/.
  local fqdn_unit=""
  for p in \
    /usr/lib/systemd/user/app-dev.lizardbyte.app.Sunshine.service \
+    /lib/systemd/user/app-dev.lizardbyte.app.Sunshine.service \
    /etc/systemd/user/app-dev.lizardbyte.app.Sunshine.service
  do
    [[ -f "$p" ]] && { fqdn_unit="$p"; break; }
  done
  if [[ -n "$fqdn_unit" ]]; then
-    info "Found packaged unit at $fqdn_unit"
-    info "Aliasing it as sunshine.service in $HOME/.config/systemd/user/"
-    mkdir -p "$HOME/.config/systemd/user"
-    ln -sf "$fqdn_unit" "$HOME/.config/systemd/user/sunshine.service"
+    info "Found packaged unit at $fqdn_unit (enables via alias)"
+    SUNSHINE_ENABLE_NAME="app-dev.lizardbyte.app.Sunshine.service"
+    export SUNSHINE_ENABLE_NAME SUNSHINE_SERVICE
    return 0
  fi

@@ -42,15 +69,68 @@ ensure_sunshine_unit_present() {
  mkdir -p "$HOME/.config/systemd/user"
  install -m 0644 "$fallback" "$HOME/.config/systemd/user/sunshine.service"
  ok "Installed $HOME/.config/systemd/user/sunshine.service"
+  SUNSHINE_ENABLE_NAME="sunshine.service"
+  export SUNSHINE_ENABLE_NAME SUNSHINE_SERVICE
+}
+
+# Install and enable the headless sway compositor unit + config (Debian/Ubuntu
+# headless path only). sunshine.service gets a drop-in making it depend on
+# sway-headless.service so the wlr capture has something to talk to.
+ensure_sway_headless_unit() {
+  [[ "$DISTRO" == "debian" ]] || return 0
+  [[ "${STREAM_MODE:-}" == "headless" ]] || return 0
+  [[ "${COMPOSITOR:-}" == "sway" ]] || return 0
+
+  local cfg_src="$SCRIPT_DIR/files/sway-headless.config"
+  local svc_src="$SCRIPT_DIR/files/sway-headless.service"
+  if [[ ! -f "$cfg_src" || ! -f "$svc_src" ]]; then
+    err "Missing sway-headless source files in $SCRIPT_DIR/files/"
+    return 1
+  fi
+
+  mkdir -p "$HOME/.config/sway" "$HOME/.config/systemd/user"
+  install -m 0644 "$cfg_src" "$HOME/.config/sway/config-headless"
+  install -m 0644 "$svc_src" "$HOME/.config/systemd/user/sway-headless.service"
+
+  # Wire sunshine.service to wait for sway-headless.service. Done via a
+  # drop-in so we don't overwrite the upstream unit shipped by the .deb.
+  local sun_dropin_dir="$HOME/.config/systemd/user/sunshine.service.d"
+  mkdir -p "$sun_dropin_dir"
+  cat >"$sun_dropin_dir/sway-headless.conf" <<'EOF'
+# Installed by omarchy-moonlight. Sunshine's wlr capture needs a running
+# wlroots compositor; sway-headless provides one on headless servers.
+[Unit]
+After=sway-headless.service
+Requires=sway-headless.service
+
+[Service]
+# Inherit the sway IPC socket location so hooks can talk to swaymsg.
+Environment=XDG_SESSION_TYPE=wayland
+Environment=WAYLAND_DISPLAY=wayland-1
+EOF
+
+  systemctl --user daemon-reload
+  systemctl --user enable sway-headless.service >/dev/null
+  if ! systemctl --user is-active --quiet sway-headless.service; then
+    info "Starting sway-headless.service"
+    systemctl --user restart sway-headless.service || {
+      err "sway-headless.service failed to start. Inspect: journalctl --user -u sway-headless"
+      return 1
+    }
+    # Give sway a beat to create its IPC socket.
+    sleep 1
+  fi
+  ok "sway-headless.service active"
 }

 enable_sunshine_service() {
-  # The AUR 'sunshine' (source) package doesn't always ship a systemd user unit
-  # at the standard /usr/lib/systemd/user/sunshine.service path. If systemd
-  # can't find one, drop our own copy into ~/.config/systemd/user/.
  ensure_sunshine_unit_present
  systemctl --user daemon-reload

+  # If we're on the Debian+Sway headless path, install the sway-headless unit
+  # before sunshine so the dependency chain is satisfied when we start it.
+  ensure_sway_headless_unit
+
  # In headless mode, install a drop-in that pre-creates HEADLESS-1 before
  # Sunshine starts. Done here because the drop-in target name depends on
  # which unit ensure_sunshine_unit_present resolved.
@@ -58,8 +138,8 @@ enable_sunshine_service() {
    install_headless_prestart_dropin
  fi

-  if ! systemctl --user list-unit-files sunshine.service >/dev/null 2>&1; then
-    err "sunshine.service still not found after fallback. Inspect: find /usr ~/.config -name sunshine.service"
+  if ! systemctl --user list-unit-files "$SUNSHINE_ENABLE_NAME" >/dev/null 2>&1; then
+    err "$SUNSHINE_ENABLE_NAME not found after fallback. Inspect: find /usr /lib ~/.config -name '*[Ss]unshine*'"
    return 1
  fi

@@ -70,15 +150,14 @@ enable_sunshine_service() {
    ok "User lingering already enabled"
  fi

-  info "Enabling sunshine.service (user)"
-  systemctl --user enable sunshine.service >/dev/null
+  info "Enabling ${SUNSHINE_ENABLE_NAME} (user)"
+  systemctl --user enable "$SUNSHINE_ENABLE_NAME" >/dev/null

  # Clear any prior start-limit state from a failed run so this attempt isn't
  # immediately rejected with "Start request repeated too quickly."
  systemctl --user reset-failed sunshine.service 2>/dev/null || true

  info "Starting sunshine.service (user)"
-  # Restart so a re-run picks up new config / new caps. Tolerate first-launch races.
  systemctl --user restart sunshine.service || systemctl --user start sunshine.service || {
    err "Failed to start sunshine.service. Check: journalctl --user -u sunshine"
    return 1
--- a/lib/verify.sh
+++ b/lib/verify.sh
@@ -119,8 +119,10 @@ verify_install() {
    info "Sunshine cert not present yet (will be generated on first start)"
  fi

-  if [[ -f /etc/ca-certificates/trust-source/anchors/omarchy-stream-ca.pem ]]; then
-    ok "omarchy-stream CA installed in system trust store"
+  local _anchor
+  _anchor="$(ca_anchor_path 2>/dev/null || true)"
+  if [[ -n "$_anchor" && -f "$_anchor" ]]; then
+    ok "omarchy-stream CA installed in system trust store ($_anchor)"
  else
    info "omarchy-stream CA not in system trust store (only matters if --no-certs was used)"
  fi
--- a/status.sh
+++ b/status.sh
@@ -0,0 +1,354 @@
+#!/usr/bin/env bash
+# status.sh — runtime health check for an omarchy-moonlight Sunshine host.
+#
+# Walks the live system (service, display backend, ports, encoder, input,
+# pairing) and prints PASS / WARN / FAIL for each, then a verdict: either
+# "good to go" or a concrete TODO list of what needs work.
+#
+# Runtime-focused on purpose — complements `install.sh --doctor` (which checks
+# install-time correctness). Safe to run repeatedly; reads only, changes nothing.
+#
+# Usage:
+#   ./status.sh                 # check the invoking user's Sunshine
+#   sudo ./status.sh            # root: auto-detects the Sunshine user
+#   SUNSHINE_USER=alice ./status.sh
+#
+# Exit code: 0 if no FAILs, 1 if any FAIL.
+
+set -uo pipefail
+
+# ---- presentation -----------------------------------------------------------
+if [[ -t 1 ]]; then
+  R=$'\e[31m'; G=$'\e[32m'; Y=$'\e[33m'; B=$'\e[1m'; D=$'\e[2m'; N=$'\e[0m'
+else
+  R=''; G=''; Y=''; B=''; D=''; N=''
+fi
+oks=0; warns=0; fails=0
+declare -a TODO=()
+pass(){ printf "  ${G}✓${N} %s\n" "$1"; oks=$((oks+1)); }
+warn(){ printf "  ${Y}!${N} %s\n" "$1"; warns=$((warns+1)); [[ -n ${2:-} ]] && TODO+=("${Y}warn${N}  $2"); }
+fail(){ printf "  ${R}✗${N} %s\n" "$1"; fails=$((fails+1)); [[ -n ${2:-} ]] && TODO+=("${R}FAIL${N}  $2"); }
+note(){ printf "  ${D}·${N} %s\n" "$1"; }
+section(){ printf "\n${B}▸ %s${N}\n" "$1"; }
+
+# ---- resolve the Sunshine user / runtime context ----------------------------
+if [[ -n ${SUNSHINE_USER:-} ]]; then
+  SUSER=$SUNSHINE_USER
+elif [[ $EUID -ne 0 ]]; then
+  SUSER=$(id -un)
+else
+  SUSER=$(ls -1 /var/lib/systemd/linger/ 2>/dev/null | head -1)
+  if [[ -z $SUSER ]]; then
+    for d in /home/*; do
+      [[ -e "$d/.config/sunshine/sunshine.conf" ]] && { SUSER=$(basename "$d"); break; }
+    done
+  fi
+fi
+if [[ -z ${SUSER:-} ]] || ! id "$SUSER" >/dev/null 2>&1; then
+  echo "Could not determine the Sunshine user. Set SUNSHINE_USER=<name> and re-run." >&2
+  exit 1
+fi
+UID_N=$(id -u "$SUSER")
+RUNTIME="/run/user/$UID_N"
+HOME_DIR=$(getent passwd "$SUSER" | cut -d: -f6)
+CONF_DIR="$HOME_DIR/.config/sunshine"
+CONF="$CONF_DIR/sunshine.conf"
+LOG="$CONF_DIR/sunshine.log"
+SYSD_USER="$HOME_DIR/.config/systemd/user"
+
+# systemctl --user, transparently as the Sunshine user when run as root
+uctl(){
+  if [[ $EUID -eq 0 && "$SUSER" != "$(id -un)" ]]; then
+    sudo -u "$SUSER" XDG_RUNTIME_DIR="$RUNTIME" systemctl --user "$@"
+  else
+    XDG_RUNTIME_DIR="${XDG_RUNTIME_DIR:-$RUNTIME}" systemctl --user "$@"
+  fi
+}
+# read a bare value from sunshine.conf (last wins; '=' separated; trimmed)
+conf_val(){ grep -E "^[[:space:]]*$1[[:space:]]*=" "$CONF" 2>/dev/null | tail -1 | cut -d= -f2- | xargs; }
+
+printf "${B}omarchy-moonlight status${N}  —  user=${SUSER}  host=$(hostname)\n"
+
+# ---- 1. binary --------------------------------------------------------------
+section "Sunshine binary"
+if command -v sunshine >/dev/null 2>&1; then
+  ver=$(sunshine --version 2>/dev/null | grep -i 'version' | head -1 | sed 's/.*version:/version/I' | xargs)
+  pass "sunshine present ($(command -v sunshine))${ver:+ — $ver}"
+else
+  fail "sunshine binary not found" "Install Sunshine (./install.sh, or apt/yay per distro)."
+fi
+if command -v flatpak >/dev/null 2>&1 && flatpak list 2>/dev/null | grep -qi 'lizardbyte.app.Sunshine' \
+   && command -v sunshine >/dev/null 2>&1; then
+  warn "both a native sunshine AND the Sunshine flatpak are installed (redundant, confusing app-id)" \
+       "Remove whichever you don't use: 'flatpak uninstall dev.lizardbyte.app.Sunshine'."
+fi
+
+# ---- 2. service unit + state ------------------------------------------------
+section "Service"
+# Can we even reach the user's systemd manager? Every uctl call below depends on
+# it. If the bus is unreachable, a healthy install looks identical to a missing
+# one (`cat`/`is-active`/`is-enabled` all just fail) — the classic false alarm
+# from running status.sh in the first seconds after reboot (before /run/user/$UID
+# exists) or as the wrong user / without a session bus. Distinguish the two.
+if ! uctl list-units --type=service >/dev/null 2>&1; then
+  fail "can't reach ${SUSER}'s user systemd manager (bus unavailable) — unit checks below are blind, NOT proof the service is missing" \
+       "Run as $SUSER in a normal session (or 'sudo ./status.sh' once boot finishes). Right after reboot, /run/user/$UID_N may not exist yet — retry in a few seconds. Verify Sunshine independently: 'ss -tulnp | grep 47990'."
+  UNIT=""
+else
+UNIT=""
+for u in sunshine.service app-dev.lizardbyte.app.Sunshine.service; do
+  if uctl cat "$u" >/dev/null 2>&1; then UNIT=$u; break; fi
+done
+if [[ -z $UNIT ]]; then
+  fail "no sunshine user unit found (sunshine.service / app-dev.lizardbyte.app.Sunshine.service)" \
+       "Install/enable a unit — see lib/service.sh or files/sunshine.service."
+else
+  # Resolve the canonical unit name. 'sunshine.service' is often an alias of
+  # app-dev.lizardbyte.app.Sunshine.service; the .wants/ symlinks use whichever
+  # name is canonical, so check both.
+  CANON=$(uctl show "$UNIT" -p Id --value 2>/dev/null); [[ -z $CANON ]] && CANON=$UNIT
+  if [[ $CANON != "$UNIT" ]]; then note "unit: $UNIT → $CANON"; else note "unit: $UNIT"; fi
+  if uctl is-active --quiet "$UNIT"; then
+    pass "service is active (running)"
+  else
+    state=$(uctl is-active "$UNIT" 2>/dev/null)
+    fail "service is $state, not running" \
+         "Start it: systemctl --user start $UNIT ; inspect: journalctl --user -u $UNIT -n 50"
+  fi
+
+  # boot wiring — the classic headless trap (TROUBLESHOOTING §12)
+  enabled=$(uctl is-enabled "$UNIT" 2>/dev/null)
+  gs=$(uctl is-active graphical-session.target 2>/dev/null)
+  want_default=no; want_graphical=no
+  for nm in "$UNIT" "$CANON"; do
+    [[ -e "$SYSD_USER/default.target.wants/$nm" ]] && want_default=yes
+    [[ -e "$SYSD_USER/graphical-session.target.wants/$nm" ]] && want_graphical=yes
+    # system-level packaged wants count too
+    [[ -e "/usr/lib/systemd/user/default.target.wants/$nm" ]] && want_default=yes
+  done
+
+  if [[ $enabled != enabled && $enabled != alias && $enabled != static ]]; then
+    fail "service not enabled (enabled=$enabled) — won't start on boot" \
+         "systemctl --user enable $UNIT"
+  elif [[ $want_default == yes ]]; then
+    pass "wired into default.target — auto-starts on a headless/lingering host"
+  elif [[ $want_graphical == yes && $gs == active ]]; then
+    pass "wired into graphical-session.target (active) — desktop session keeps it up"
+  elif [[ $want_graphical == yes && $gs != active ]]; then
+    fail "only wired into graphical-session.target, which is INACTIVE on this headless host — service won't auto-start on boot" \
+         "Add a drop-in with [Install] WantedBy=default.target, then 'systemctl --user reenable $UNIT'. See TROUBLESHOOTING.md §12."
+  else
+    warn "enabled but no target.wants symlink found — boot behavior unclear" \
+         "Verify: ls $SYSD_USER/*.target.wants/ | grep -i sunshine"
+  fi
+
+  # lingering
+  linger=$(loginctl show-user "$SUSER" -p Linger --value 2>/dev/null)
+  if [[ $linger == yes ]]; then
+    pass "user lingering enabled (survives logout)"
+  else
+    warn "user lingering is off — user services stop at logout / won't run before login" \
+         "sudo loginctl enable-linger $SUSER"
+  fi
+
+  # misplaced drop-in keys (Requires/After in [Service]) — systemd warns about these
+  if uctl status "$UNIT" 2>&1 | grep -q 'Unknown key name'; then
+    warn "a drop-in has keys in the wrong section (systemd is ignoring them)" \
+         "Run 'systemctl --user status $UNIT' — move Requires=/After= into [Unit]. See TROUBLESHOOTING.md §12."
+  fi
+fi
+fi  # end user-manager-reachable guard
+
+# ---- 3. config + capture backend --------------------------------------------
+section "Config & capture backend"
+if [[ -s $CONF ]]; then
+  pass "sunshine.conf present and non-empty"
+elif [[ -f $CONF ]]; then
+  fail "sunshine.conf exists but is EMPTY — Sunshine will run with defaults (no encoder/capture tuning)" \
+       "Regenerate it (./install.sh) or restore your hand-edited config."
+else
+  fail "sunshine.conf missing ($CONF)" "Run ./install.sh to generate it."
+fi
+CAP=$(conf_val capture); ENC=$(conf_val encoder); OUT=$(conf_val output_name)
+note "capture=${CAP:-<unset>}  encoder=${ENC:-<auto>}  output_name=${OUT:-<unset>}"
+
+# ---- 4. display backend (depends on capture) --------------------------------
+section "Display backend"
+case "${CAP:-}" in
+  x11)
+    if uctl is-active --quiet xorg-headless.service 2>/dev/null; then
+      pass "xorg-headless.service active"
+    elif pgrep -af 'Xorg.*:0' >/dev/null 2>&1; then
+      warn "an Xorg :0 is running but not via xorg-headless.service" \
+           "Fine if intentional; otherwise enable xorg-headless.service so it starts on boot."
+    else
+      fail "capture=x11 but no Xorg :0 / xorg-headless.service running — nothing to capture" \
+           "Start the headless X server (systemctl --user start xorg-headless.service). See TROUBLESHOOTING.md §13."
+    fi
+    # is DISPLAY :0 actually answering?
+    if command -v xset >/dev/null 2>&1; then
+      if (if [[ $EUID -eq 0 && "$SUSER" != "$(id -un)" ]]; then sudo -u "$SUSER" DISPLAY=:0 xset -q; else DISPLAY=:0 xset -q; fi) >/dev/null 2>&1; then
+        pass "X display :0 reachable"
+      else
+        fail "DISPLAY=:0 not reachable (X server not answering)" "Check xorg-headless.service logs."
+      fi
+    fi
+    # Is a window manager actually rendering on :0? X can be up and reachable
+    # yet have no WM/desktop drawing anything — Sunshine then captures an empty
+    # black root window (pairing/NVENC/input all work; client sees only black).
+    if command -v xprop >/dev/null 2>&1; then
+      _xp(){ if [[ $EUID -eq 0 && "$SUSER" != "$(id -un)" ]]; then sudo -u "$SUSER" DISPLAY=:0 xprop "$@"; else DISPLAY=:0 xprop "$@"; fi; }
+      wm_win=$(_xp -root _NET_SUPPORTING_WM_CHECK 2>/dev/null | grep -o '0x[0-9a-f]*' | head -1)
+      if [[ -n $wm_win ]]; then
+        # Read the WM's advertised name (e.g. "GNOME Shell", "Openbox") so the
+        # report says which desktop is actually rendering, not just that one is.
+        wm_name=$(_xp -id "$wm_win" _NET_WM_NAME 2>/dev/null | sed -n 's/.*= "\(.*\)"/\1/p')
+        pass "a desktop is running on :0${wm_name:+ (${wm_name})} — something to capture"
+      else
+        fail "no window manager on :0 — capture will be a black screen" \
+             "Start a desktop on the headless Xorg: 'systemctl --user enable --now headless-desktop.service' (install.sh installs it for the x11 backend; HEADLESS_DESKTOP=gnome|openbox). See TROUBLESHOOTING.md §13."
+      fi
+    else
+      note "xprop not installed — skipping desktop-on-:0 check (install x11-utils to enable it)"
+    fi
+    # wlr env leaking into an x11 unit (stale sway drop-in — TROUBLESHOOTING §13)
+    if [[ -n $UNIT ]]; then
+      env_dump=$(uctl show "$UNIT" -p Environment 2>/dev/null)
+      if grep -qiE 'WAYLAND_DISPLAY|XDG_SESSION_TYPE=wayland' <<<"$env_dump"; then
+        warn "Wayland env is leaking into the x11 unit (likely a stale sway-headless.conf drop-in)" \
+             "Remove the leftover wlr drop-in; confirm with 'systemctl --user show $UNIT -p Environment'. See TROUBLESHOOTING.md §13."
+      fi
+    fi
+    ;;
+  wlr)
+    if pgrep -x Hyprland >/dev/null 2>&1 || pgrep -x sway >/dev/null 2>&1 \
+       || uctl is-active --quiet sway-headless.service 2>/dev/null; then
+      pass "a wlroots compositor (Hyprland/sway) is running"
+    else
+      fail "capture=wlr but no Hyprland/sway compositor running — encoder probe will fail" \
+           "Start the compositor (or sway-headless.service on a server). See TROUBLESHOOTING.md §4."
+    fi
+    if command -v hyprctl >/dev/null 2>&1; then
+      mons=$( (if [[ $EUID -eq 0 && "$SUSER" != "$(id -un)" ]]; then sudo -u "$SUSER" XDG_RUNTIME_DIR="$RUNTIME" hyprctl monitors all -j; else hyprctl monitors all -j; fi) 2>/dev/null)
+      if grep -q 'HEADLESS' <<<"$mons"; then
+        pass "a HEADLESS output exists"
+      else
+        warn "no HEADLESS output present yet (created per-connection by the prep-cmd hook)" \
+             "Normal between streams; sunshine-prestart.sh creates one before the encoder probe."
+      fi
+    fi
+    ;;
+  kms)
+    if command -v ls >/dev/null && ls /sys/class/drm/card*/card*-*/status >/dev/null 2>&1 \
+       && grep -ql '^connected' /sys/class/drm/card*/card*-*/status 2>/dev/null; then
+      pass "a connected DRM output is present (KMS capture has something to grab)"
+    else
+      warn "capture=kms but no connected display detected — needs a real monitor or dummy plug" \
+           "Attach a display/dummy plug, or switch to a headless backend (--headless)."
+    fi
+    ;;
+  "")
+    warn "no capture method set in sunshine.conf — Sunshine will auto-detect" \
+         "Pin one explicitly (capture=x11|wlr|kms) for predictable headless behavior."
+    ;;
+  *)
+    note "capture=$CAP (unrecognized by this checker — skipping backend-specific checks)"
+    ;;
+esac
+
+# ---- 5. encoder -------------------------------------------------------------
+section "Encoder"
+case "${ENC:-}" in
+  *nvenc*|"")
+    if command -v nvidia-smi >/dev/null 2>&1; then
+      if nvidia-smi -L >/dev/null 2>&1; then pass "NVIDIA GPU reachable ($(nvidia-smi -L | head -1 | sed 's/(UUID.*//'))"
+      else fail "nvidia-smi present but no GPU responding" "Check the NVIDIA driver / 'nvidia-smi'."; fi
+    elif [[ "${ENC:-}" == *nvenc* ]]; then
+      warn "encoder=nvenc but nvidia-smi not found" "Install nvidia-utils, or switch encoder to vaapi/software."
+    fi
+    ;;
+esac
+if [[ -f $LOG ]]; then
+  recent=$(tail -n 4000 "$LOG" 2>/dev/null)
+  if grep -q 'Unable to find display or encoder' <<<"$recent"; then
+    fail "log shows 'Unable to find display or encoder during startup'" \
+         "Display backend wasn't ready at probe time — see Display backend section above & TROUBLESHOOTING.md §4."
+  elif grep -qE 'Found (H.264|HEVC|AV1) encoder' <<<"$recent"; then
+    enc_found=$(grep -oE 'Found (H.264|HEVC|AV1) encoder: [a-z0-9_]+' <<<"$recent" | tail -3 | sed 's/Found //' | paste -sd', ')
+    pass "encoders detected in recent log: ${enc_found:-yes}"
+  else
+    note "no recent encoder-probe lines in log (service may not have probed since last start)"
+  fi
+fi
+
+# ---- 6. network: ports + web UI ---------------------------------------------
+section "Network"
+if command -v ss >/dev/null 2>&1; then
+  for p in 47984 47989 47990; do
+    if ss -tln 2>/dev/null | grep -q ":$p "; then pass "TCP $p listening"
+    else fail "TCP $p NOT listening" "Service likely down or failed to bind — check the Service section."; fi
+  done
+else
+  note "ss not available — skipping port checks"
+fi
+code=$(curl -sk -o /dev/null -m 5 -w '%{http_code}' https://localhost:47990 2>/dev/null)
+case "$code" in
+  401|200) pass "web UI responding on :47990 (HTTP $code)";;
+  000|"")  fail "web UI not responding on :47990" "Service down, or not bound. Check Service section.";;
+  *)       warn "web UI returned HTTP $code on :47990" "Unexpected — inspect manually.";;
+esac
+
+# ---- 7. input injection (/dev/uinput) ---------------------------------------
+section "Input (/dev/uinput)"
+if [[ -e /dev/uinput ]]; then
+  if id -nG "$SUSER" 2>/dev/null | grep -qw input; then
+    pass "$SUSER is in the 'input' group"
+  else
+    fail "$SUSER is NOT in the 'input' group — keyboard/mouse injection will fail" \
+         "sudo usermod -aG input $SUSER  (then re-login)"
+  fi
+  perms=$(stat -c '%U:%G %a' /dev/uinput 2>/dev/null)
+  mode=$(stat -c '%a' /dev/uinput 2>/dev/null)
+  grp_digit=${mode: -2:1}   # group permission digit; write bit set in 2,3,6,7
+  if [[ $grp_digit =~ [2367] ]]; then
+    pass "/dev/uinput group-writable ($perms)"
+  else
+    warn "/dev/uinput not group-writable ($perms) — udev rule may not have applied" \
+         "Ensure 60-sunshine.rules is installed and 'udevadm control --reload && udevadm trigger'."
+  fi
+else
+  fail "/dev/uinput does not exist — no virtual input devices" "Load the uinput module: 'sudo modprobe uinput'."
+fi
+
+# ---- 8. certs + pairing -----------------------------------------------------
+section "Certificates & pairing"
+if [[ -f "$CONF_DIR/credentials/cacert.pem" ]]; then
+  pass "host cert present (credentials/cacert.pem)"
+else
+  warn "no host cert in credentials/ — clients see Sunshine's self-signed default" \
+       "Run the cert step (./install.sh with op signed in) if you use the shared CA."
+fi
+STATE="$CONF_DIR/sunshine_state.json"
+if [[ -f $STATE ]]; then
+  if command -v jq >/dev/null 2>&1; then
+    n=$(jq -r '[.. | objects | select(has("uniqueid") or has("uuid")) | (.name // empty)] | length' "$STATE" 2>/dev/null)
+  fi
+  [[ -z ${n:-} || $n == 0 ]] && n=$(grep -oc '"uniqueid"' "$STATE" 2>/dev/null)
+  if [[ -n ${n:-} && $n -gt 0 ]]; then note "$n paired client(s) on record"
+  else note "no paired clients yet (pair from Moonlight, then enter the PIN)"; fi
+fi
+
+# ---- verdict ----------------------------------------------------------------
+printf "\n${B}── verdict ──${N}\n"
+printf "  ${G}%d passed${N}   ${Y}%d warnings${N}   ${R}%d failures${N}\n" "$oks" "$warns" "$fails"
+if (( fails == 0 && warns == 0 )); then
+  printf "\n  ${G}${B}g2g${N} — everything checks out. Stream away.\n"
+elif (( fails == 0 )); then
+  printf "\n  ${G}${B}good to go${N} (with %d non-blocking warning(s)):\n\n" "$warns"
+  for t in "${TODO[@]}"; do printf "    • %s\n" "$t"; done
+else
+  printf "\n  ${R}${B}NOT ready${N} — fix these:\n\n"
+  for t in "${TODO[@]}"; do printf "    • %s\n" "$t"; done
+fi
+echo
+exit $(( fails > 0 ? 1 : 0 ))
--- a/uninstall.sh
+++ b/uninstall.sh
@@ -6,6 +6,10 @@ set -euo pipefail
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 # shellcheck source=lib/common.sh
 source "$SCRIPT_DIR/lib/common.sh"
+# shellcheck source=lib/distro.sh
+source "$SCRIPT_DIR/lib/distro.sh"
+
+detect_distro

 PURGE=0
 KEEP_MOONLIGHT=0
@@ -21,7 +25,7 @@ Usage: $(basename "$0") [--purge] [--keep-moonlight] [--remove-ca-trust]

  --purge             Also delete ~/.config/sunshine and ~/.local/share/sunshine
  --keep-moonlight    Do not uninstall moonlight-qt
-  --remove-ca-trust   Remove the omarchy-stream CA from /etc/ca-certificates
+  --remove-ca-trust   Remove the omarchy-stream CA from the system trust store
                      (default: leave it — other hosts/services may rely on it)
 EOF
      exit 0 ;;
@@ -32,8 +36,9 @@ done

 require_not_root

-step "Stopping Sunshine service"
+step "Stopping services"
 systemctl --user disable --now sunshine.service 2>/dev/null || true
+systemctl --user disable --now sway-headless.service 2>/dev/null || true

 step "Removing user lingering (if enabled by us)"
 if loginctl show-user "$USER" -p Linger --value 2>/dev/null | grep -qx yes; then
@@ -42,19 +47,37 @@ if loginctl show-user "$USER" -p Linger --value 2>/dev/null | grep -qx yes; then
 fi

 step "Removing packages"
-# Remove -debug siblings first so they don't collide with re-installation later.
-for pkg in sunshine-debug sunshine-bin-debug sunshine sunshine-bin; do
-  if pacman -Qi "$pkg" >/dev/null 2>&1; then
-    as_root pacman -Rns --noconfirm "$pkg"
-  fi
-done
-if [[ $KEEP_MOONLIGHT -eq 0 ]]; then
-  for pkg in moonlight-qt moonlight-qt-bin; do
-    if pacman -Qi "$pkg" >/dev/null 2>&1; then
-      as_root pacman -Rns --noconfirm "$pkg"
+case "$DISTRO" in
+  arch)
+    # Remove -debug siblings first so they don't collide with re-installation later.
+    pkg_remove sunshine-debug sunshine-bin-debug sunshine sunshine-bin
+    if [[ $KEEP_MOONLIGHT -eq 0 ]]; then
+      pkg_remove moonlight-qt moonlight-qt-bin
    fi
-  done
-fi
+    ;;
+  debian)
+    pkg_remove sunshine
+    if [[ $KEEP_MOONLIGHT -eq 0 ]]; then
+      pkg_remove moonlight-qt
+    fi
+    ;;
+  *)
+    warn "Unknown distro; skipping package removal."
+    ;;
+esac
+
+step "Removing user-installed systemd units + drop-ins"
+rm -f \
+  "$HOME/.config/systemd/user/sway-headless.service" \
+  "$HOME/.config/systemd/user/sunshine.service.d/sway-headless.conf" \
+  "$HOME/.config/systemd/user/sunshine.service.d/headless-prestart.conf" \
+  "$HOME/.config/systemd/user/app-dev.lizardbyte.app.Sunshine.service.d/headless-prestart.conf"
+# Clean empty .d directories
+rmdir --ignore-fail-on-non-empty \
+  "$HOME/.config/systemd/user/sunshine.service.d" \
+  "$HOME/.config/systemd/user/app-dev.lizardbyte.app.Sunshine.service.d" \
+  2>/dev/null || true
+systemctl --user daemon-reload 2>/dev/null || true

 step "Removing udev rule (if we wrote one)"
 if [[ -f /etc/udev/rules.d/60-uinput.rules ]]; then
@@ -64,10 +87,10 @@ fi

 if [[ $REMOVE_CA_TRUST -eq 1 ]]; then
  step "Removing omarchy-stream CA from system trust store"
-  anchor="/etc/ca-certificates/trust-source/anchors/omarchy-stream-ca.pem"
-  if [[ -f "$anchor" ]]; then
+  anchor="$(ca_anchor_path)"
+  if [[ -n "$anchor" && -f "$anchor" ]]; then
    as_root rm -f "$anchor"
-    as_root update-ca-trust extract >/dev/null
+    ca_update_trust
    ok "Removed $anchor and refreshed trust store"
  else
    info "CA anchor not present; nothing to remove"
@@ -75,11 +98,12 @@ if [[ $REMOVE_CA_TRUST -eq 1 ]]; then
 fi

 if [[ $PURGE -eq 1 ]]; then
-  step "Purging Sunshine user data"
-  rm -rf "$HOME/.config/sunshine" "$HOME/.local/share/sunshine"
+  step "Purging Sunshine + sway-headless user data"
+  rm -rf "$HOME/.config/sunshine" "$HOME/.local/share/sunshine" "$HOME/.local/share/omarchy-moonlight"
+  rm -f "$HOME/.config/sway/config-headless"
 fi

 ok "Uninstall complete. Firewall rules and 'input' group membership were left in place."
 if [[ $REMOVE_CA_TRUST -eq 0 ]]; then
-  info "The omarchy-stream CA was left in /etc/ca-certificates (--remove-ca-trust to drop it)."
+  info "The omarchy-stream CA was left in the system trust store (--remove-ca-trust to drop it)."
 fi
Author	SHA1	Message	Date
Levi Woodard	cc5daaaf37	status.sh: don't misreport an unreachable user bus as a missing unit Running status.sh in the first seconds after a reboot (before /run/user/$UID exists / the lingering user manager is reachable), or as the wrong user without a session bus, made every `systemctl --user` call fail with "Failed to connect to bus". The Service check read that the same as "unit doesn't exist" and printed a scary "no sunshine user unit found" for a perfectly healthy, auto-starting install. Probe the user manager once up front; if the bus is unreachable, say so explicitly (and point at 'ss -tulnp \| grep 47990' to verify Sunshine independently) instead of cascading into false negatives. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>	2026-06-03 00:04:50 +00:00
Levi Woodard	84ddf8c1c6	Default the x11 headless desktop to GNOME (Openbox still opt-in) 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>	2026-06-02 23:56:17 +00:00
Levi Woodard	6fc34a2bd2	Add reproducible headless desktop for the X11/NVENC capture path 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>	2026-06-02 23:43:00 +00:00
Levi Woodard	ab23107300	Add runtime status checker + headless/X11 docs; distro-support refinements - status.sh: runtime health check (service state, boot wiring, display backend auto-detect, encoder, ports, web UI, /dev/uinput, pairing) ending in a g2g verdict or concrete TODO list - docs: TROUBLESHOOTING §12 (headless graphical-session.target boot trap) + §13 (X11/NVENC path & stale wlr drop-in env conflict); ARCHITECTURE capture-backend comparison; FOLLOWUPS P3 (installer X11/Ubuntu support); README diagnostics pointer - lib/{config,packages,permissions,service}.sh, files/sway-headless.service: in-progress Debian/Ubuntu + headless support refinements Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>	2026-06-02 22:57:03 +00:00
Levi Woodard	ee1379d5be	Add Debian/Ubuntu support via a thin distro dispatch layer 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.	2026-05-23 01:17:42 +00:00