49 Headless Server

49 Headless Server

Source: docs/design/49-headless-server.md

Status: designed (D102); auth revised 2026-10-24

Self-hosted always-on brain: kepcup-server (npm/tar, NAS/cloud, Node ≥22.19, no Docker required) embeds the same createCoreServices as desktop.

Single port:

• /ws/{sid}?role=viewer — direct WS (hub DI seam; viewers unchanged)
• / — PWA static (pairing origin = server)
• /admin/* — loopback + token (pair/devices; CLI backend)

alwaysOn hub option (desktop keeps on-demand disconnect). Direct mode default auth = account/password (scrypt, HMAC cookie 30d); --auth pairing can fall back to D96 pairing. Keystore: OS keychain or --keystore file (0600, risk disclosed). Port B capabilities unbound → existing degradations. --relay keeps outbound relay mode. Single-user single-instance (no multi-tenant). Ships via release.yml linux-x64/arm64 artifacts alongside desktop.