Project Deployment

ai-viewer Deployment

This skill is the durable record of how ai-viewer gets installed and run on the operator's workstation. Load it for any install/upgrade/uninstall, source-discovery or permission issue, or "how do I use this" question. The contract lives in .agents/sow/specs/deployment.md; this file is the operational quick-reference.

TL;DR

• System install (recommended): scripts/install-system.sh → binaries + data under /opt/ai-viewer, two system systemd units running as the operator, UI at http://127.0.0.1:7710/.
• User install (no root): scripts/install-systemd-user.sh → binaries in ~/.local/bin, user systemd units, data in ~/.local/share/ai-viewer/.
• Both are localhost-only (no auth in v1 — workstation-scoped).

The system install (scripts/install-system.sh)

What it does

1. Rebuilds from source (scripts/build.sh — frontend + both Go binaries).
2. Probes the installing operator's well-known agent-data paths and renders --source flags for each that exists:
   • ~/.ai-agent/sessions → aiagent_v3 + aiagent_v2 (same dir backs both)
   • ~/.claude/projects → claude-code
   • ~/.codex/sessions → codex
   • ~/.local/share/opencode/opencode.db → opencode
3. Lays out /opt/ai-viewer/{bin,data,logs}, atomically stages each rebuilt binary and renames it into place.
4. Renders the unit templates (deploy/systemd-system/ai-viewer-{ingest,serve}.service) — substituting __OPERATOR_USER__, __OPERATOR_GROUP__, and __AI_VIEWER_SOURCES__ — into /etc/systemd/system/.
5. systemctl daemon-reload, enables both units, stops active units, fixes ownership/permissions while they are down, starts the ingester, verifies ingester liveness, starts and verifies the server, re-checks ingester liveness, then prints the URL.

Commands

scripts/install-system.sh             # install or upgrade (rebuilds) + start + verify + print URL
scripts/install-system.sh status      # systemctl status for both + the URL
scripts/install-system.sh uninstall   # stop + disable + remove units + /opt/ai-viewer (data is disposable)

Layout

Two design decisions baked in (do NOT re-litigate without a new reason)

1. Runs as the operator (User=<operator>), NOT a dedicated service user. The operator's agent-data dirs (~/.ai-agent, ~/.claude, ~/.codex, ~/.local/share/opencode) are owner-only (0700), so a dedicated ai-viewer user cannot read them without invasive recursive ACLs (fragile — new files don't inherit unless default ACLs are set; surprises dotfile managers/backup tools). Running as the operator is correct and simple here:

• The app's purpose is "the operator's viewer for the operator's agent data"; localhost-only; read-only on sources by design (os.O_RDONLY).
• It's the same privilege level the operator already grants every other agent CLI they run (opencode/codex/claude — all run as the operator).
• A dedicated user for this one tool is security theater relative to the rest of the operator's stack and was actively breaking source access (the 0-sources bug during initial install — see History).
• The systemd hardening stays (NoNewPrivileges, ProtectSystem=strict, ProtectHome=read-only, PrivateTmp, ReadWritePaths scoped to the data dir for the ingester).

2. Explicit --source flags in the unit, NOT auto-discovery. Auto-discovery probes $HOME-relative paths. The explicit list is (a) auditable — the unit file shows exactly what the service reads, and (b) independent of $HOME resolution (irrelevant now that we run as the operator, but it survived because it's the cleaner contract). The committed template carries __AI_VIEWER_SOURCES__; the install script renders it.

Verifying an install

systemctl is-active ai-viewer-ingest.service ai-viewer-serve.service   # both → active
curl -s http://127.0.0.1:7710/api/health | python3 -m json.tool         # status + sources[] (want len ≥ 1)
journalctl -u ai-viewer-ingest -u ai-viewer-serve -f                    # live tail
scripts/install-system.sh status                                       # the bundled status command

• /api/health.status is degraded on a fresh install until sources catch up (parse errors from real-data edge cases + historical staleness) — that's correct (errors are surfaced, not hidden). It is NOT an install failure.
• /api/health.sources is empty for the first few seconds (sources register on the first batch flush, after the adapters scan) — wait, don't panic.
• The ingester liveness check catches immediate startup failures. A delayed migration/startup failure after the poll window is diagnosed from systemctl status, bounded journalctl output, and the effective StartLimit* values from systemctl show.

Operating

• Logs: journalctl -u ai-viewer-ingest -u ai-viewer-serve -f (journald via stdout; the primary sink).
• Restart after a code change: scripts/install-system.sh (uninstall is NOT needed — install is idempotent; it rebuilds + atomically replaces binaries + re-renders + daemon-reload + stop/start verification).
• Data is disposable. /opt/ai-viewer/data/index.db is derived. Deleting it (or uninstall) triggers a full re-ingest on next start; the source files are the source of truth. Never back up the index.
• Read-only on sources. Neither binary writes to ~/.ai-agent/~/.claude/etc. The ingester opens source files os.O_RDONLY; the server never touches them.
• Port: 7710 (the spec default; 127.0.0.1:7710). Changing it requires editing the rendered serve unit + the frontend's Vite proxy target (dev only).
• Graceful stop budget: all system and user units use TimeoutStopSec=45s. The system ingester also has MemoryHigh=4G, MemoryMax=8G, LimitNOFILE=65536, IOSchedulingClass=idle, and OOMPolicy=stop.
• Writer one-shots: for a system install, commands such as rollups-backfill, fts-content-backfill, and reprice that target /opt/ai-viewer/data/index.db must also pass --state-dir /opt/ai-viewer/data so they detect the running system daemon lock before opening a writer handle.

Common issues

• sources: 0 after install. Either the units run as the wrong user (permission denied on the 0700 home dirs — re-run install so it renders User=<operator>), or you're checking too early (sources register on first batch flush — wait ~5s).
• permission denied on source paths in the ingest log. The unit's User= doesn't own the data. Confirm /etc/systemd/system/ai-viewer-ingest.service has User=<operator> (the install script renders this from SUDO_USER/$USER).
• Server not responding after 20s. systemctl status ai-viewer-serve + journalctl -u ai-viewer-serve — the usual cause is the schema-not-ready start-order race (the serve unit's Restart=on-failure cycles until the ingester migrates); give it another few seconds.
• Ingester start/restart loop. Inspect systemctl status ai-viewer-ingest, journalctl -u ai-viewer-ingest, and systemctl show ai-viewer-ingest.service -p StartLimitBurst -p StartLimitIntervalUSec. The project does not hard-code StartLimit* values; use the host's effective settings when diagnosing migration failures.
• bad substitution / sed errors from the installer. The script renders the unit via sed (no -o); if you edit it, don't reintroduce sed -o.

The user install (alternative, no root)

scripts/install-systemd-user.sh — binaries to ~/.local/bin, user systemd units (systemctl --user), data in ~/.local/share/ai-viewer/. Uses auto-discovery (works because it runs as the operator under the user manager). Same ports, same localhost-only. Use this when root is unavailable; the system install is otherwise preferred (runs at boot without a login session).

History (why these decisions)

• Initial system install used a dedicated ai-viewer user + auto-discovery → discovered 0 sources. Root cause #1: auto-discovery probes $HOME-relative paths, but the service user's $HOME was /home/ai-viewer. Fixed by making sources explicit.
• Re-rendered with explicit sources, still 0 sources → permission denied on every source path. Root cause #2: the operator's ~/.ai-agent etc. are 0700, so even with correct paths the dedicated user couldn't traverse them. Tried ACLs; rejected as fragile/invasive.
• Final: run as the operator + explicit sources. Correct, simple, matches the mental model, keeps the hardening. Recorded here so the dedicated-user idea is not retried without a genuinely new reason (e.g. the app gains a network-exposed surface — then least-privilege outweighs simplicity and this decision is revisited in its own SOW).
• The deployment spec (.agents/sow/specs/deployment.md §"System Install") is the authoritative contract; this skill is the quick-reference + the reasoning.