Skip to content

Business operating system for Claude Code — 57 skills, 21 agents, smart daemon. Unified inbox (WhatsApp/Email/Slack/Telegram), autonomous PR merge, full-AWS monitoring, revenue (Stripe+RevenueCat), e-commerce (Shopify), marketing (Klaviyo/Meta/GA4), voice (Bland/ElevenLabs), APM (Datadog/NewRelic/OTEL), YOLO mode.

feat(systemd): persistent noVNC desktop over Tailscale (#374)

Aurora Capital79be435353f2
diff --git a/scripts/systemd/README-novnc-vnc.md b/scripts/systemd/README-novnc-vnc.md
new file mode 100644
index 00000000..6360adac
--- /dev/null
+++ b/scripts/systemd/README-novnc-vnc.md
@@ -0,0 +1,75 @@
+# Persistent browser-based desktop (noVNC over Tailscale)
+
+Gives a headless box a GUI desktop you can reach from any browser on the tailnet —
+no VNC client, no SSH tunnel — and survives reboots. Built for `dev-sandbox-fra`
+but host-agnostic.
+
+## Architecture
+
+```
+browser ──HTTPS (tailnet)──> tailscale serve ──> 127.0.0.1:6080
+ │ (novnc.service, --user)
+ ▼
+ websockify ──WebSocket⇄VNC──> localhost:5901
+ │
+ ▼
+ TigerVNC Xvnc :1 (vncserver@:1.service)
+ │
+ ▼
+ GNOME desktop on display :1
+```
+
+## Install
+
+```bash
+./setup-novnc-desktop.sh
+```
+
+Idempotent. It installs `websockify` (pip --user), clones `noVNC` to `~/noVNC`,
+installs + enables the `novnc.service` user unit, enables linger, ensures
+`vncserver@:1` is boot-enabled, fronts it with `tailscale serve`, and disables the
+GNOME idle screen-lock.
+
+## Boot persistence — the four things that must be true
+
+| Layer | Unit / setting | Why |
+|---|---|---|
+| VNC server `:1` | `vncserver@:1.service` (system, **enabled**) | starts the X/GNOME desktop |
+| noVNC proxy `:6080` | `novnc.service` (**--user**, enabled, `Restart=always`) | bridges WS↔VNC + serves the web client |
+| user-service-without-login | `loginctl enable-linger $USER` | the `--user` unit starts at boot, no login needed |
+| HTTPS front | `tailscale serve --bg 6080` | config persists in tailscaled state across reboots |
+
+If any one is missing the desktop won't come back after reboot. Verify:
+
+```bash
+systemctl is-enabled vncserver@:1.service # enabled
+systemctl --user is-enabled novnc.service # enabled
+loginctl show-user "$USER" -p Linger # Linger=yes
+sudo tailscale serve status # shows / -> 127.0.0.1:6080
+```
+
+## Access
+
+- Tailnet IP: `http://<tailscale-ip>:6080/vnc.html`
+- MagicDNS: `https://<host>.<tailnet>.ts.net/vnc.html` (via `tailscale serve`)
+- Connect, enter the **VNC password**.
+
+The box has no public IP, so `0.0.0.0:6080` is effectively tailnet-only. Keep it
+that way — do **not** `tailscale funnel` this (that would expose the desktop to the
+public internet).
+
+## Secrets (NOT in this repo)
+
+- **VNC password** — `~/.vnc/passwd` (TigerVNC obfuscated, 8-char max). Reset:
+ `printf '%s\n' '<pw>' | vncpasswd -f > ~/.vnc/passwd`
+- **Desktop login password** — the Unix user password (`passwd` / `chpasswd`).
+- **GNOME login keyring** — separate from the above; if its password is unknown,
+ launch Chromium/Brave with `--password-store=basic` to avoid a keyring unlock hang
+ (saved credentials won't decrypt, but the browser runs).
+
+## Troubleshooting
+
+- noVNC loads but won't connect → `systemctl --user restart novnc.service`; check
+ `vncserver@:1` is active and `:5901` is listening.
+- `tailscale serve` denied → run with `sudo`, or `sudo tailscale set --operator=$USER` once.
+- Only one process should `LISTEN` on `:6080` — the service one. Kill strays by PID.
diff --git a/scripts/systemd/novnc.service b/scripts/systemd/novnc.service
new file mode 100644
index 00000000..cc22a24c
--- /dev/null
+++ b/scripts/systemd/novnc.service
@@ -0,0 +1,16 @@
+[Unit]
+Description=noVNC websockify proxy (HTTP/WebSocket -> local VNC :5901)
+Documentation=https://github.com/Lifecycle-Innovations-Limited/claude-ops/blob/main/scripts/systemd/README-novnc-vnc.md
+After=graphical-session.target network-online.target
+
+[Service]
+Type=simple
+# Serves the noVNC web client and bridges WebSocket <-> the local TigerVNC
+# server on :5901 (display :1). Bound to 0.0.0.0 so it is reachable over the
+# Tailscale interface; the box has no public IP, so this is tailnet-only.
+ExecStart=/usr/bin/python3 -m websockify --web %h/noVNC 0.0.0.0:6080 localhost:5901
+Restart=always
+RestartSec=3
+
+[Install]
+WantedBy=default.target
diff --git a/scripts/systemd/setup-novnc-desktop.sh b/scripts/systemd/setup-novnc-desktop.sh
new file mode 100755
index 00000000..6534110c
--- /dev/null
+++ b/scripts/systemd/setup-novnc-desktop.sh
@@ -0,0 +1,94 @@
+#!/usr/bin/env bash
+# setup-novnc-desktop.sh — make a headless box's TigerVNC desktop reachable as a
+# browser-based noVNC client over Tailscale, persistent across reboots.
+#
+# Idempotent. Safe to re-run. Installs nothing it can't find a reason to.
+#
+# Layers it wires up:
+# 1. TigerVNC server on display :1 -> systemd `vncserver@:1.service` (must exist)
+# 2. noVNC proxy :6080 -> localhost:5901 -> systemd --user `novnc.service` (this script)
+# 3. HTTPS front over the tailnet -> `tailscale serve --bg 6080`
+# 4. linger ON so the --user service runs without an interactive login
+#
+# Prereqs assumed already present: tigervnc-server, a configured `vncserver@:1`,
+# python3, git, tailscale (logged in). The script checks and warns if missing.
+set -euo pipefail
+
+VNC_DISPLAY="${VNC_DISPLAY:-1}"
+VNC_PORT="${VNC_PORT:-5901}"
+NOVNC_PORT="${NOVNC_PORT:-6080}"
+NOVNC_DIR="${NOVNC_DIR:-$HOME/noVNC}"
+UNIT_SRC="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)/novnc.service"
+USER_UNIT_DIR="$HOME/.config/systemd/user"
+
+log() { printf '\033[36m[novnc-setup]\033[0m %s\n' "$*"; }
+warn() { printf '\033[33m[novnc-setup] WARN:\033[0m %s\n' "$*" >&2; }
+
+# 1. websockify (user-site pip; system python is restricted on AL2023)
+if ! python3 -c 'import websockify' 2>/dev/null; then
+ log "installing websockify (pip --user)"
+ pip3 install --user --quiet websockify
+fi
+
+# 2. noVNC web client
+if [ ! -f "$NOVNC_DIR/vnc.html" ]; then
+ log "cloning noVNC -> $NOVNC_DIR"
+ git clone --depth 1 https://github.com/novnc/noVNC.git "$NOVNC_DIR"
+fi
+
+# 3. install + enable the user service
+mkdir -p "$USER_UNIT_DIR"
+sed -e "s/0.0.0.0:6080/0.0.0.0:${NOVNC_PORT}/" \
+ -e "s/localhost:5901/localhost:${VNC_PORT}/" \
+ "$UNIT_SRC" >"$USER_UNIT_DIR/novnc.service"
+chmod 0644 "$USER_UNIT_DIR/novnc.service"
+systemctl --user daemon-reload
+systemctl --user enable --now novnc.service
+log "novnc.service: $(systemctl --user is-enabled novnc.service) / $(systemctl --user is-active novnc.service)"
+
+# 4. linger so the user unit survives logout / starts at boot
+if [ "$(loginctl show-user "$USER" -p Linger --value 2>/dev/null)" != "yes" ]; then
+ log "enabling linger for $USER"
+ sudo loginctl enable-linger "$USER"
+fi
+
+# 5. VNC server enabled on boot
+if systemctl list-unit-files "[email protected]" >/dev/null 2>&1; then
+ if [ "$(systemctl is-enabled "vncserver@:${VNC_DISPLAY}.service" 2>/dev/null)" != "enabled" ]; then
+ log "enabling vncserver@:${VNC_DISPLAY}.service"
+ sudo systemctl enable "vncserver@:${VNC_DISPLAY}.service"
+ fi
+else
+ warn "[email protected] not installed — install tigervnc-server and configure :${VNC_DISPLAY} first"
+fi
+
+# 6. HTTPS front over Tailscale (config persists in tailscaled state across reboots)
+if command -v tailscale >/dev/null 2>&1; then
+ log "asserting tailscale serve -> :${NOVNC_PORT}"
+ sudo tailscale serve --bg "${NOVNC_PORT}" || warn "tailscale serve failed (is tailscaled up & logged in?)"
+else
+ warn "tailscale not found — skipping HTTPS front; use http://<tailnet-ip>:${NOVNC_PORT}/vnc.html"
+fi
+
+# 7. kill the GNOME idle screen-lock (it interrupts long remote sessions)
+if command -v gsettings >/dev/null 2>&1; then
+ DISP=":${VNC_DISPLAY}"
+ if DISPLAY="$DISP" DBUS_SESSION_BUS_ADDRESS="unix:path=/run/user/$(id -u)/bus" \
+ gsettings set org.gnome.desktop.screensaver lock-enabled false 2>/dev/null; then
+ DISPLAY="$DISP" DBUS_SESSION_BUS_ADDRESS="unix:path=/run/user/$(id -u)/bus" \
+ gsettings set org.gnome.desktop.session idle-delay 0 2>/dev/null || true
+ log "disabled GNOME idle screen-lock"
+ fi
+fi
+
+TS_IP="$(tailscale ip -4 2>/dev/null | head -1 || true)"
+[ -n "$TS_IP" ] || TS_IP='<tailscale-ip>'
+
+cat <<EOF
+
+[novnc-setup] done.
+ Local: http://localhost:${NOVNC_PORT}/vnc.html
+ Tailnet: http://${TS_IP}:${NOVNC_PORT}/vnc.html
+ HTTPS: https://<magicdns-name>/vnc.html (if tailscale serve succeeded)
+ VNC pw: set with printf '%s\\n' '<pw>' | vncpasswd -f > ~/.vnc/passwd
+EOF