Node-based terminal manager for AI coding agents — tmux-backed terminals and parallel agent sessions as draggable nodes on an infinite pan/zoom canvas. macOS, Linux, and a browser Server Edition.
nodeterm Server Edition (Phase 2)
Run nodeterm's canvas in a browser, backed by a headless Node server on your own
machine or box. The server serves the same built renderer the desktop app uses
and speaks a WebSocket-RPC protocol to it; a browser-side window.nodeTerminal
shim (src/renderer/bridge/) stands in for the Electron preload, so the React UI is
unchanged. It boots the same Electron-free core services (src/core/) through a
ServerPlatform, so terminals get the same tmux session continuity as the desktop app.
Phase 2 scope: terminals only. This is a real, usable terminal canvas over the network, but it is deliberately narrow — see Limitations.
Quickstart
Host requirements: Linux, or macOS 12 Monterey or newer. Building the server runs the same
esbuild binary Vite uses, and that binary needs macOS 12+ (see Build from source in the
README) — a Big Sur Mac cannot build or run the Server Edition, but any browser on it can open
one hosted elsewhere.
npm run server:dev
server:dev runs npm run build (renderer + core) then npm run server:build
(bundles src/server/main.ts → out/server/main.cjs via esbuild) and finally
node out/server/main.cjs. On a repeat run where the renderer is already built you
can skip straight to npm run server:start.
First run (setup token)
With no password configured yet, the server prints a one-time setup URL to stdout:
Setup: http://127.0.0.1:8443/setup?token=<32-hex>
nodeterm-server listening on http 127.0.0.1:8443
Open that URL, choose a password (min 8 chars), and you're signed in. The setup token is single-use and lives only in memory (never written to disk), so it's regenerated if the process restarts before setup completes.
Headless setup (no interactive setup URL)
Seed the password out-of-band with an env var — useful for containers / CI where nobody is watching stdout:
NODETERM_SERVER_PASSWORD='choose-a-strong-one' npm run server:start
When NODETERM_SERVER_PASSWORD is set and no password is configured yet, the
server writes the scrypt hash on boot and skips the setup URL entirely — go straight
to /login. It is ignored once a password already exists (it never overwrites).
Use at least 8 characters, the same rule the setup form enforces. A shorter value is
still used (an existing deployment must keep booting), but the boot prints a loud
✖ NODETERM_SERVER_PASSWORD is shorter than 8 characters line.
Manual build + run
npm run build # electron-vite build → out/renderer, out/core
npm run server:build # esbuild → out/server/main.cjs
npm run server:start # node out/server/main.cjs
Configuration
Precedence: CLI flag > environment variable > default.
| Flag | Env var | Default | Meaning |
|---|---|---|---|
--port <n> |
NODETERM_PORT |
8443 |
TCP port to listen on. |
--host <h> |
NODETERM_HOST |
127.0.0.1 |
Interface to bind. |
--data-dir <path> |
NODETERM_DATA_DIR |
~/.nodeterm-server |
Where auth, sessions, workspace, settings, and scrollback live. |
--renderer-dir <path> |
NODETERM_RENDERER_DIR |
out/renderer (resolved from cwd) |
Directory of the built renderer (index.html + hashed assets). |
--insecure-http |
— | off | Acknowledge serving plain HTTP directly on a non-loopback interface (see below). |
| — | NODETERM_SERVER_PASSWORD |
— | Seed the password headlessly on first boot (see above). |
--trust-proxy-header <name> |
NODETERM_TRUST_PROXY_HEADER |
— (off) | Reverse-proxy SSO trust: identity header asserted by your proxy (see Reverse-proxy SSO). |
--trust-proxy-nets <list> |
NODETERM_TRUST_PROXY_NETS |
127.0.0.0/8, ::1/128 |
Comma-separated IPs/CIDRs (IPv4+IPv6) whose requests may use the trust header. Only meaningful with the header set. |
| — | NODETERM_TRUST_PROXY_SECRET |
— | Shared secret your proxy sends as X-Nodeterm-Proxy-Secret (at least 32 printable characters). Required when the trusted nets include loopback. Environment only: a command-line flag is refused, because argv is readable by every local user. |
--public-origin <url> |
NODETERM_PUBLIC_ORIGIN |
— | The https origin you open in the browser, e.g. https://term.example.com. Forces the Secure cookie flag, sends HSTS, and lets that Origin pass the same-origin checks when the proxy rewrites Host. See TLS. |
Binding a non-loopback host (anything other than 127.0.0.1 / localhost /
::1) without --insecure-http is refused at startup — plain HTTP on a public
interface would leak the session cookie. The intended deployment is loopback-bound
behind a TLS-terminating reverse proxy (see TLS).
Headless notification host
The Server Edition doubles as a headless notification host: a background process on any Linux box that gives a phone SSHing into it full push / Live-Activity coverage — without serving the browser UI and without opening a single port.
One-line install
curl -fsSL https://raw.githubusercontent.com/eneskirca/nodeterm/main/scripts/install-server.sh | bash
The installer (scripts/install-server.sh) is idempotent — re-run it any time to update. It:
- needs only
git,curlandtaron the host — Node.js is no longer a prerequisite: if a system Node ≥ 20 (with npm) is present it's used as-is, otherwise the installer downloads a pinned Node LTS from nodejs.org into~/.nodeterm-server-app/runtime/nodeand uses it for the build and the systemd service (nothing is installed system-wide; Alpine/musl hosts still need a distronodejs). It also warns (with the apt/dnf one-liner) if the C toolchain (make/gcc/python3) node-pty's native build needs is missing; - clones (or
git pulls) the repo into~/.nodeterm-server-app; - installs deps (
npm ci --ignore-scripts, thennpm rebuild node-ptyagainst Node's ABI — the same trap the Docker build documents) and builds the renderer + server bundle; - installs a systemd service (
NODETERM_HEADLESS=1,Restart=on-failure, journald logs): a system unit at/etc/systemd/system/nodeterm-server.servicewhen run as root, or a per-user unit +loginctl enable-lingerotherwise — then enables and (re)starts it; - writes
<data-dir>/install-meta.json({version, commit, installedAt}, where<data-dir>defaults to~/.nodeterm-server). The server reads it at boot and surfaces it to a paired phone through the agent-status mirror's top-levelserverblock, so a connection can show which version this install is on — the answer to "how does an installed Server Edition learn about updates?"; - installs a daily auto-update timer (unless you opt out — see below).
Follow the logs with journalctl -u nodeterm-server -f (add --user for a non-root install).
Auto-update
The installer also installs a nodeterm-server-update.service (a oneshot) plus a
nodeterm-server-update.timer (OnCalendar=daily, RandomizedDelaySec=3600, Persistent=true),
with the same root/user split as the main service (a system unit under
/etc/systemd/system/, or a per-user unit under ~/.config/systemd/user/). When it fires, the
service:
git pull --ff-onlyin~/.nodeterm-server-app— updating the checkout including this updater script, so the updater logic keeps itself current;- re-execs the freshly-pulled
scripts/install-server.sh, which rebuilds and restarts the service. The installer is idempotent, so an already-current pull just no-ops through a harmless rebuild.
Opt out: run the installer with NODETERM_NO_AUTOUPDATE=1 — it skips the timer, and (so a
re-run can turn auto-update off) removes an existing timer/service. The installer prints the
timer status (systemctl list-timers) in its summary so you can confirm the next run.
Check or trigger it manually:
systemctl list-timers nodeterm-server-update.timer # add --user for a non-root install
systemctl start nodeterm-server-update.service # run an update now
Per-user installs (one per Unix user)
An install covers only the Unix user it runs as — its systemd unit, ~/.nodeterm-server-app
checkout, and ~/.nodeterm-server data dir are that user's. A box with several server users
(root, customerservice, …) needs one install per user; the phone offers this per
connection (it installs under whichever user its SSH session logs in as). Non-root installs rely on
loginctl enable-linger <user> (the installer runs it) so the user's systemd manager — and thus
both the service and the auto-update timer — keep running without an active login session.
NODETERM_HEADLESS
Set NODETERM_HEADLESS=1 (also accepts true, case-insensitive) to boot in headless mode.
Everything boots exactly as usual — the loopback hook server, the agent-status mirror, the
usage poll, the granted push senders (push-notify + Live-Activity), and the pending-approvals
sweep — except the public HTTP/WS listener, which is never bound. There is no renderer
serving and no auth surface. NODETERM_HOST / NODETERM_PORT are ignored (nothing binds), and
platform.broadcast is a no-op while no browser UI is attached.
Security rationale: zero open ports
The whole point of this mode is that it adds no network attack surface:
- No public listener at all. The HTTP/WS server is never created, so there is no port to expose, no login page to brute-force, and no session cookie in flight.
- The hook server stays loopback-only. Agent CLIs POST their lifecycle hooks to
127.0.0.1(a per-session bearer token, fail-open) — it never leaves the host. - Push is outbound-only. Notifications reach the phone over outbound HTTPS, authorized
by a signed, device-scoped grant the phone itself drops at
~/.nodeterm/push-grants/<deviceId>.grantwhen it reaches the host over SSH. No inbound connection, no standing relay identity — a grant a phone never dropped simply means no push.
The phone's own SSH session into the host is the trust boundary; nodeterm adds nothing listening beside it.
Session budget (idle-session reaper)
tmux sessions deliberately outlive their clients (that is the continuity contract), so a host that
serves many SSH projects slowly accumulates detached agent sessions nobody will ever come back
to — a field report counted 95 sessions holding 34 GB of idle claude processes. Every
nodeterm-server (headless or serving) runs a session budget (src/core/session-budget.ts, the
tmux counterpart of the renderer's WebGL budget): every 10 minutes it sweeps the local
node-terminal and legacy SSH-remote nodeterm-rmt sockets and reaps the least-recently-active
detached nt-* sessions when
- host available memory drops below a watermark (default 10% of RAM, floor 1 GB) — the primary, pressure-driven trigger; or
- the detached session count exceeds a cap (default 48) — the accumulation backstop.
Attached sessions are never touched, a grace window (default 6 h since last activity) protects
recent work, kills are re-verified against a fresh listing, and each sweep reaps at most a small
batch (default 8) so convergence is gradual. A reaped session is indistinguishable from a reboot
to its node: on next open it cold-restores (scrollback snapshot + claude --resume). Tuning /
kill switch via env: NODETERM_SESSION_MIN_AVAILABLE_MB, NODETERM_SESSION_MAX_DETACHED,
NODETERM_SESSION_GRACE_HOURS, NODETERM_SESSION_REAP_BATCH, NODETERM_SESSION_REAP_DISABLED=1.
Session memory (the RAM pill + per-session panel)
The reaper's counterpart for a human: startSessionMemoryService (src/core/session-memory-service.ts)
is booted here too, beside the reaper in src/server/index.ts, and window.nodeTerminal.sessionMemory
has a real ws-bridge implementation (not a stub). So the browser gets the bottom-left RAM pill and
the per-session breakdown, and both describe the machine the server is served from: its
/proc/meminfo, its node-terminal (and legacy nodeterm-rmt) tmux sockets, its process table. Full write-up:
docs/session-memory.md.
An SSH project's scope answers ok:false — "could not measure" — and that is deliberate. The
server has no ControlMaster, so it cannot read the other host; answering with its own sessions would
publish this machine's memory under that host's name. Same degrade as remote usage, one step
stricter:
- The service is given
isRemoteProjectbut norun. Knowing which projects are somebody else's machine and being able to read them are different capabilities, and the option pair is asymmetric to say so (runoptional,isRemoteProjectrequired). - The refusal is decided by identity, not by trusting the renderer's
remoteflag:sshScopePredicate({ sshProjectIds: () => workspaceStore.sshProjectIds() }). A query arriving without that flag — a client that has not learned the project is an SSH one yet — would otherwise fall through to the LOCAL sweep, which is exactly the misattribution the refusal exists to prevent. - That predicate depends on the boot-time
await workspaceStore.load(...)instartServer(a line documented there as being for Context Link). Drop it — or stop awaiting it beforeserver.listen()— and every SSH project silently reads as local again;test/server/session-memory-e2e.test.tsfails if that happens. What is not load-bearing is where that load sits relative to the service boot:isRemoteProjectis a closure evaluated per QUERY, and no query can arrive beforestartServerreacheslisten(). The requirement is that the load completes before the server serves, not that it precedes any particular boot line.
A headless host boots the service like every other core service, but with no UI attached nothing queries it.
Hosted team relay (the team CLI)
A Server Edition can host a team that desktops join over the relay, run with the team CLI as the
service's own user (node ~/.nodeterm-server-app/out/server/main.cjs team …); the operator guide is
docs/hosted-team-relay.md. Two of its verbs exist for the desktop's Share with team, and both
work by hand from a shell on the host. team bootstrap --owner-key <key> --adopt <dir> [--owner-label <name>] is the whole setup in one idempotent call: it creates the team and starts
hosting, makes the key an owner, adopts the folder into this core's workspace (deduplicated by real
path; an existing .nodeterm/project.json keeps its nodes) and shares it, then prints the join
code. team resume --project <id> restarts, on this core's own tmux socket, the agent sessions a
desktop handed over, each with its conversation resumed; it reads its session list as JSON on
stdin, never from the command line. Under --json, a server failure (exit 1) prints one JSON
line on stdout, with a stable code when the server sent one (E_BAD_KEY, E_BAD_CWD,
E_HOSTING_OFF, E_ADOPT_FAILED, E_BAD_REQUEST, E_UNSUPPORTED); a command line the CLI itself
refuses exits 2 on stderr only. The browser build cannot start Share with team: it has no SSH
projects, and its shareTeam rejects with E_UNSUPPORTED.
Security model
Single-user auth. There is one password; sessions are per-browser.
- Password hashing: scrypt (
N=16384, r=8, p=1, 32-byte key, per-password random salt), stored asauth.json(mode0600) in the data dir. Login comparison is constant-time (crypto.timingSafeEqual). The app never stores the plaintext. - Password verification runs the asynchronous scrypt, at most two at a time (a FIFO gate), so a burst of login attempts never stalls the event loop that carries every terminal's WebSocket.
- Session cookie: on successful login the server sets
nt_session=<random>withHttpOnly; SameSite=Strict; Path=/, plusSecurewhenNODETERM_PUBLIC_ORIGINis set or the proxy sendsX-Forwarded-Proto: https(see TLS). Sessions are persisted (sessions.json, mode0600) with a 30-day TTL and swept lazily. - Signing out:
POST /auth/logoutdeletes the presented session on the server, so a copy of the cookie stops working too (it used to clear only the browser's cookie and leave the session valid for 30 days).POST /auth/logout-all("Sign out everywhere") deletes every session; it needs a signed-in caller. Both are in the browser UI under Settings → Application → Sign-in (Server Edition only). An open WebSocket remembers the session it was opened with and is closed (code4401) the moment that session is signed out, and on the next heartbeat (≤ 30 s) after it expires. A socket opened through proxy header trust is bound to the proxy's identity, not to a cookie, and stays open. - Same-origin checks: the WebSocket upgrade and every
POST /auth/*(login, logout, logout-all, setup) refuse a request whoseOriginis not this server: its host must equal the requestHost, or theOriginmust equalNODETERM_PUBLIC_ORIGIN.Origin: nulland a malformed Origin are refused. A request with noOriginis a non-browser client (browsers always send one on a POST and on a WebSocket handshake) and is allowed — unless it saysSec-Fetch-Site: cross-siteorsame-site. A refused auth POST is answered403 cross_originand is not charged to the lockout. So a page the owner visits can neither post the login form (to lock them out) nor sign them out. - Login rate limit / lockout, per client:
- A login attempt reserves a slot before its body is read, and the budget counts attempts in flight as well as failures. (It used to be checked before the body and charged after verification, so requests whose bodies were held back all passed it: 60 of 60 were verified in the audit's repro.) A body that does not arrive within 10 s is abandoned and its slot released without a charge.
- 5 failures (or attempts still in flight) lock that client for 1 minute; each
further lock doubles, up to 1 hour. A success resets the client; a client quiet for an
hour after its last lock is forgotten. Refusals are
429 too_many_attemptswith aRetry-Afterheader (a browser gets the sign-in page with the wait in minutes). - A global ceiling of 50 failures plus attempts in flight per 5-minute sliding window, across all clients, is the backstop against a guesser with many addresses. Its cost: under a sustained distributed attack it refuses the owner too, until the window drains.
- Who is a client: the TCP peer, except when the peer is a forwarder — loopback, a
private, CGNAT, link-local or ULA address, or inside
NODETERM_TRUST_PROXY_NETS— in which case it is the lastX-Forwarded-Forentry (the one your proxy appended; the entries to its left were written by whoever called the proxy). IPv6 clients are grouped by their /64. Consequences: a process that reaches the server from a forwarder address (a local user, another container on the network) can pick the bucket it is charged to — the global ceiling still applies to it; and behind two proxies (a CDN in front of your proxy) clients are grouped by the CDN's edge address.
- No framing: every response carries
X-Frame-Options: DENYandContent-Security-Policy: frame-ancestors 'none'(the app's own CSP is a<meta>tag, whereframe-ancestorsis ignored), plusX-Content-Type-Options: nosniff. - Auth gate: every route except the login/setup pages and their POST handlers
requires a valid session — HTML navigations redirect to
/login, API/WS get401.
Reverse-proxy SSO (header trust)
Deployments that front the server with an SSO reverse proxy (Cloudflare Access,
Tailscale, oauth2-proxy, Authelia…) already authenticate every request before it
reaches nodeterm, and the proxy asserts the identity in a request header. Setting
NODETERM_TRUST_PROXY_HEADER makes such requests count as authenticated — no
password, setup token, or session cookie needed:
# Cloudflare Access
NODETERM_TRUST_PROXY_HEADER=Cf-Access-Authenticated-User-Email node out/server/main.cjs
# Tailscale (tailscale serve / funnel with identity headers)
NODETERM_TRUST_PROXY_HEADER=Tailscale-User-Login node out/server/main.cjs
# oauth2-proxy / Authelia / most others
NODETERM_TRUST_PROXY_HEADER=X-Forwarded-User node out/server/main.cjs
A request is trusted only when all of these hold:
- its TCP peer address is inside
NODETERM_TRUST_PROXY_NETS(default: loopback only — the same-host proxy deployment). If your proxy reaches the container over a private network, list it explicitly, e.g.NODETERM_TRUST_PROXY_NETS=10.0.0.0/8; - it carries the configured header with a non-empty value;
- when
NODETERM_TRUST_PROXY_SECRETis set, it carriesX-Nodeterm-Proxy-Secretequal to it (compared in constant time; never logged).
The header content is not validated (no JWT verification) — the trusted-network boundary is the trust statement, and on loopback that boundary holds every local process: every Unix account on the host, every container on the host network, every sandboxed agent is "from the trusted networks". So:
- Loopback nets need the secret. If the trusted nets include loopback (127.0.0.0/8 or
::1, including the default and anything wider such as0.0.0.0/0) and no secret is set, header trust stays OFF: the server still boots with password sign-in, and the boot prints a✖ Proxy header trust is OFFerror naming what to set. A loopback peer is never header-trusted without the secret, whatever the configuration. - Other nets work without it, but get a warning: every host that can reach the server from those networks — other containers on the same network, the Docker host's bridge address — counts as your proxy. Set the secret there too.
To turn it on, generate a secret (openssl rand -hex 32), give it to the server through the
environment (a --trust-proxy-secret flag is refused: argv is readable by every local user),
and have the proxy send it on every request, WebSocket upgrades included:
# nginx
proxy_set_header X-Nodeterm-Proxy-Secret "<secret>";
# Caddy (inside reverse_proxy)
header_up X-Nodeterm-Proxy-Secret "<secret>"
# Traefik (a headers middleware attached to the router)
http:
middlewares:
nodeterm-secret:
headers:
customRequestHeaders:
X-Nodeterm-Proxy-Secret: "<secret>"
The proxy must also strip/overwrite the identity header on incoming client requests (Cloudflare Access, Tailscale and oauth2-proxy all do). A request that comes from a trusted address with the identity header but without the right secret is treated as signed out, and the server logs (at most once a minute, without any header value) that the secret was missing. A typo'd nets entry, a secret shorter than 32 characters, a secret with spaces, or a secret without a header all fail the boot rather than silently changing who is trusted; setting nets without a header is likewise refused.
Upgrading a deployment that already uses header trust on loopback (the default nets): after this change header trust is off until you set
NODETERM_TRUST_PROXY_SECRETand the proxy header. Users then see the password page; sign in with the password, or set the secret.
Everything else stays intact: password/cookie auth keeps working beside it (e.g.
for loopback ops access), the WS upgrade still enforces the same-host Origin check,
and a proxy-authed visit to /login or /setup just redirects home. The boot log
prints a ⚠️ Proxy header trust ENABLED line naming the header, the networks and
whether a secret is required — verify it matches what you meant to trust.
TLS (reverse proxy)
The server speaks plain HTTP by design. For anything beyond localhost, run it
bound to loopback and put a TLS-terminating reverse proxy (nginx, Caddy, Cloudflare
Tunnel, a VPN, etc.) in front, and tell the server the address you open in the browser:
NODETERM_PUBLIC_ORIGIN=https://term.example.com node out/server/main.cjs
With it, the session cookie is always Secure and every response carries
Strict-Transport-Security: max-age=31536000; an Origin equal to it also passes the
same-origin checks when the proxy rewrites Host. It must be an https origin with no path
(anything else fails the boot). Without it the server behaves as before — Secure is set only
when the proxy sends X-Forwarded-Proto: https, and no HSTS is sent — and it logs one warning
the first time a request arrives for a non-loopback Host, because a proxy that does not send
that header silently loses Secure. --insecure-http only exists as an explicit, eyes-open
escape hatch for trusted private networks — prefer the proxy.
Docker / Dokploy
The repo ships a multi-stage Dockerfile (root) that builds the renderer + server bundle and
produces a slim runtime image with tmux, git and curl (the managed hook scripts POST
through curl). Any Dockerfile-based PaaS (Dokploy, Coolify, plain compose) can deploy it:
docker build -t nodeterm-server .
docker run -d -p 8443:8443 \
-e NODETERM_SERVER_PASSWORD='choose-a-strong-one' \
-v nodeterm-data:/data \
nodeterm-server
On Dokploy specifically: create an app from this repo (Dockerfile build), attach a volume at
/data, set NODETERM_SERVER_PASSWORD and NODETERM_PUBLIC_ORIGIN=https://<your domain>, and
point a domain at container port 8443 — Traefik terminates TLS (and forwards
X-Forwarded-Proto), so the session cookie gets its Secure flag and the clipboard runs in a
secure context.
Things the image decides for you (see the Dockerfile comments for the full why):
- node-pty is compiled against Node's ABI, not Electron's. The repo's
postinstallrunselectron-rebuild, which targets Electron — every install in the image uses--ignore-scriptsplus an explicitnpm rebuild node-pty. Don't "simplify" that away. --insecure-httpis passed because the container must bind0.0.0.0for the proxy to reach it, and TLS lives in the proxy. Never publish the port directly on a public interface.- A container restart/redeploy kills the tmux server (it lives inside the container). The
cold-restore path bridges it — scrollback replays from the
/datasnapshot and resumable agents relaunch with--resume— but running processes die with each deploy. This is the one behavioral difference from a long-lived host install, where only a machine reboot does that. /datamust be a volume — auth, sessions, workspace and scrollback snapshots live there; without it every restart forgets the password and the canvas.
Agent CLIs (claude etc.) are not baked into the image — install them into the running
container (or extend the image) and authenticate inside a terminal node; their config lives
under the container user's home, so consider a volume there too if you rely on them.
CSP
The inline login/setup pages carry a strict CSP. The built index.html ships with a
default-src 'self' marker that the server rewrites at serve time to
default-src 'self'; connect-src 'self'; so the browser can open the WebSocket: CSP3
matches a same-origin ws:/wss: URL against 'self', and the bridge only ever opens
/ws on the page's own host. (It used to be connect-src 'self' ws: wss:, i.e. a socket to
any host — harmless without an XSS, an exfiltration channel with one.) Verified with headless
Chrome 153 against http/ws and https/wss: the same-origin socket opens, a
cross-origin one is blocked. Firefox and Safari follow the same CSP3 rule but were not run;
a browser too old to apply it would block the WebSocket and show the reconnect overlay. If
that marker is ever missing, the server logs a loud warning (the WS would otherwise be
blocked) — rebuild the renderer or update the rewrite. Framing is refused by HTTP header on
every response (see Security model).
Dictation
Voice-to-text input works in the browser via the same core speech service the desktop app uses. Dictate with ⌘⌥D (or the dock mic button); transcribed text goes into the overlay's editable field and is sent only via explicit Send/Insert into the node that was selected when the overlay opened — nothing auto-submits. Browser constraints: getUserMedia requires a secure context — HTTPS or localhost; the microphone permission prompt is the browser's own. Model storage: Downloaded models (tiny free tier; larger Pro models) are stored on the server's data dir under speech-models/, persisted across sessions and server restarts.
Documented deviations from the spec
Two intentional departures from docs/superpowers/specs/2026-07-10-server-edition-design.md:
node:http+ws, not Fastify. The HTTP/WS surface is tiny (a handful of routes + one WS endpoint); the built-inhttpmodule pluswskeeps the dependency footprint minimal and avoids a framework for no gain.- scrypt, not argon2. scrypt is in Node's standard library (
crypto), so there's no native dependency to build/ship. Parameters follow the OWASP baseline.
Phase 2 limitations
- Terminal-only. Terminal nodes work (spawn, I/O, resize, tmux continuity). The
git panel, source control, Monaco editor/diff nodes, SDK chat node, agent-status
badges/hooks, and the folder picker are not wired into the server bridge yet —
their
window.nodeTerminalmethods are stubbed. Deferred to Phase 3. - Reconnect = full-page reload. When the WebSocket drops, the bridge shows an overlay and the recovery path is to reload the page; on reload each terminal warm-reattaches to its still-running tmux session and tmux redraws. (The spec's lighter "thin reconnect strip" is recorded as a v1 tradeoff.)
- Initial-connect failure showed a blank screen (resolved in Phase 3c). If the server was unreachable at the very first page load (as opposed to a mid-session drop), the reconnect overlay did not appear — you got a blank page. The bridge now shows the reconnect overlay on a failed first connect instead of booting the app, and reloads on reopen. See Phase 3c.
- No backpressure / flow-control auto-trigger. The
pty.setFlowplumbing exists end-to-end, but nothing automatically pauses a flooding PTY based on WebSocketbufferedAmountyet. Deferred to Phase 3. - Single user. One password, no accounts/roles.
Phase 3a: files, editor, diff & source control
Phase 3a widens the browser surface from terminals-only to the file-and-git
workflow. The server now registers the core fs, git, and commit-message
handlers and the browser bridge exposes real fs / git / files / context
APIs, so several node kinds and panels that were stubbed in Phase 2 now work in the
browser:
- Editor & diff nodes — Monaco editor nodes read/write files over
fs:read/fs:write(⌘S saves), and diff nodes rendergit:show-file+fs:read— both now function unchanged in the browser. - Source Control panel — stage / unstage / discard, diff, branch switch/create,
commit + push, and the ✦ AI commit message (BYO local agent CLI on the staged
diff) all run against the server's
gitservice. - Explorer — the file tree lists the project
cwdviafs:list.
The following affordances change shape in the browser (no native OS is reachable):
- Folder / file picker — there is no native dialog. "Open folder…" and file
pickers use an in-app server-directory browser (built on
fs:list) that lets you navigate and pick a path on the server's filesystem. shell.openExternal— opens the URL in a new browser tab rather than a desktop-side default browser.- "Reveal in Finder" / "open with default app" — inert in the browser (there is no desktop file manager to reveal into); these actions are hidden or no-op rather than erroring.
- Clipboard (copy) — the browser's
navigator.clipboardonly exists in a secure context (https orlocalhost). Over plain http on a LAN it isundefined, so the bridge falls back to a hidden-textareadocument.execCommand('copy'). That fallback only works inside a user gesture: the copy shortcut and the click-driven copy buttons are fine, but anOSC 52write driven by terminal output (vim "+y,gh,yazi) is not — it fails and raises a banner ("the browser blocks clipboard access over plain http"). Copy never fails silently, but if you want it to work properly, serve over https (or localhost) — that is one more reason for the TLS proxy above. Note also that Ctrl+Shift+C (advertised as copy on Linux/Windows) additionally opens Chromium's element inspector and a page cannot suppress that; Ctrl+Insert is the browser-safe copy chord. - Markdown view toggle (⌘/Ctrl+M) — works in the browser: with no main process to
intercept it, the bridge matches the user's
node.toggleMarkdownbinding with its own window keydown listener (src/renderer/bridge/markdown-toggle-key.ts) and honors the terminal-first policy like the desktop. macOS Chrome reserves ⌘M for window minimize and never delivers it to the page, so on a Mac the default chord does nothing — remap it in Settings → Keyboard Shortcuts, or use the node's right-click "Markdown view". On Linux/Windows the default is Ctrl+M, which under the default app-first policy is taken from a focused terminal exactly as on the desktop (a shell sees Ctrl+M as Enter). Inside a focused Monaco editor Ctrl+M stays Monaco's own "toggle Tab key moves focus" binding; hover the node with focus elsewhere to toggle its preview.
The backpressure / flow-control gap noted in the Phase 2 limitations is now
closed: a flooding PTY is automatically paused based on the WebSocket
bufferedAmount and resumed when it drains, so the WS is protected.
Loose coordination (follow-up). The server-side WS backpressure and the renderer's terminal (xterm) flow control coordinate only loosely over a shared pause actuator (
ptyManager.setFlow) — full two-master coordination is a follow-up. Because either side can resume the pty independently, the server re-asserts its pause on every send while the socket buffer stays above the high-water mark (rather than latching on a single rising edge), so a renderer-side resume cannot silently latch the server's protection off.
Still deferred to Phase 3b: the SDK chat node and the agent-status badges/hooks are not yet wired into the server bridge.
Phase 3b: agent status, subagents & the context meter
Phase 3b brings the agent-observability surface — the same code path the desktop app
uses — to the browser. The server boots the loopback hook server
(hookServer.start(), on its own 127.0.0.1 port) and installs the managed hook
scripts, so every agent CLI the server spawns POSTs its lifecycle hooks back to the
host. wireAgentStatus installs the hook server's normalized + raw listeners and
routes each event over platform.broadcast, so the existing renderer badge / subagent
/ context code now works unchanged in the browser:
- Agent-status badges — an agent's own hooks (not output parsing) drive the shared
4-state model; the normalized event is broadcast over
agent:statusand the header shows the pulsing RUNNING (working) / NEEDS YOU (waiting/blocked) badge, plus the unread dot and completion notification (as a Web Notification — see Phase 2). - Subagent visualization — subagent start/end drive ephemeral SubagentNode cards
over
agent:subagent-activity; the main-process subagent tail streams each card's live transcript to the browser. - Context-window meter — the per-node context tail streams
context:updateso the meter fills as the session's transcript grows (this channel was already real in 3a; 3b feeds it from the hook pipeline).
Because the hook POST carries a transcript_path, a forged POST is defended by jailing
that path to the system-default ~/.claude/projects or a managed account dir
(isSafeLocalTranscriptPath) before any tail reads it.
Context Link
Context Link works in the Server Edition. The feature itself lives entirely in core
(src/core/context-link.ts) and writes everything under dataDir; what it needs from a
shell is the link map — who is linked to whom.
The desktop gets that from its renderer, because React Flow holds the live canvas. That
does not fit here: agents and their tmux sessions keep running with the browser closed,
and a headless deployment may never have one attached. So the server derives the same map
from the persisted bridges[] of every canvas (workspaceStore.persistedCanvases() →
buildBackgroundLinkMaps, in src/server/context-link.ts). A workspace save re-derives
immediately; a 15 s sweep also catches transcript paths, which arrive from the hooks
rather than from any canvas change, and skips the write when nothing moved.
Consequences worth knowing:
- Boot reads the workspace once (
load({ sideline: false })) so links are live before the first browser connects. Read-only on purpose — sidelining a conflictedproject.jsonstays a renderer/probe decision. - Boot also writes into agent configuration directories when managed hook installation
is on: the
get-linked-contextClaude skill, plus marker-delimited instruction blocks in~/.codex/AGENTS.md,~/.gemini/GEMINI.mdand opencode'sAGENTS.md. The blocks are idempotent and preserve surrounding content. SetinstallHooks: falseto skip every one of those writes — the Context Link read handler still works, agents simply have to be told about the shim some other way. - Local-only, deliberately. No remote deps are injected (
initContextLink(pty, {})): the server runs ON the host whose transcripts and tmux it reads, and SSH projects are a desktop-only concept. contextLink.info()is still unsupported in the browser bridge, so the canvas note that announces a new link cannot quote the shim path. The boot-installed instructions cover discovery independently.
Deliberate scope and feature-gate differences:
- The SDK chat node is still deferred — it is not wired into the server bridge.
- Canvas-control (
agent:control) is opt-in on the Server Edition. With the feature disabled,/control/<verb>answers HTTP 400 witherror: control-unsupported-on-this-editionand a sentence containing the literal "do not retry". With it enabled, only the bounded v1 verbs described below are wired; every other verb receives the same named permanent refusal.browseradditionally names why it is structural rather than unimplemented — a browser node on this edition renders in the viewer's own browser tab, which this server has no debugger for, and never can. The wholebrowserdrive set shipped over S8 (nav/read/click/type/press/scroll/wait/screenshot/cookies) is therefore desktop-only: it needs Electron's<webview>+ CDP, which this edition has none of, so there is no browser driving here at all. Seesrc/server/control-unsupported.ts. The agent-messaging verbs (send/reply/notify) are verified-only. When Server control is enabled they additionally require process-local proof that the caller spawned the target in this run (areplymay also go to the node that spawned the caller); with control disabled they receivecontrol-unsupported-on-this-edition. - The
ptyDestroytail-teardown — resolved in Phase 3c. Phase 3b left this skipped (agent tails self-cleared only onSessionEnd, so a node closed without one left an idle file-tail); the server now untracks agent tails on node close, at desktop parity. See Phase 3c. - SSH-remote agent tails are N/A — the server has no SSH-project manager, so the SSH branch of the desktop hook-wiring block is dropped (the raw listener falls straight through to the local logic).
Phase 3c: follow-up hardening
Phase 3c closes two follow-ups left open by Phase 3b, bringing the browser bridge to desktop parity on agent-tail cleanup and first-connect behavior:
ptyDestroytail-teardown (desktop parity). When a node is closed the server now untracks its agent tails (the per-node context/subagent session state plus the context tail and subagent tail) onptyDestroy, exactly as the desktop app does — no more idle file-tail lingering for a node closed without aSessionEnd(e.g. the × button). This was enabled by makingplatform.onmulti-listener (matching Electron'sipcMain.on): the new teardown listener runs alongsidePtyManager's ownptyDestroydestroy handler instead of clobbering it.- Clean boot on a failed initial connect. A failed first WebSocket connect no longer boots the app into a broken/blank state — the bridge shows the standard reconnect overlay and the app reloads on reopen, so first-load failure now behaves like a mid-session drop.
Still deferred: the SDK chat node, full two-master flow-control coordination (the server still re-asserts its WS backpressure pause on each send rather than co-managing a single actuator with the renderer), and the web folder picker's hardcoded start directory.
Opt-in canvas control and creator ownership
Server canvas control is disabled by default. Set NODETERM_SERVER_CANVAS_CONTROL=1 (or pass
--canvas-control) to install the Server-local shim and enable its /control/* implementation.
Every enabled request requires verified node identity. Enabling it lets an agent session run
arbitrary commands on this host as the user the server runs as — open-terminal --cmd <command>
is executed in a PTY this process spawns, with that user's environment, files and credentials. The
gates below decide which agent may ask, not what may be asked for, so the surface this flag
opens is the host, not the canvas. Enable it on a host where you would be content to hand those
agents a shell.
Ownership is intentionally narrower than the desktop confirmation UI: an agent may mutate, message,
or close only a node it opened during the current Server process run (one exception: a reply to
the node that opened it). Link, group, rename, color,
sticky updates, dependency targets, message delivery, and close validate their complete target set
before any write or PTY kill; an unowned member refuses the whole operation. Queued messages repeat
the creator check at flush time in addition to the existing verified and per-project switch gates.
The creator ledger is memory-only and is never reconstructed from a project file, title, hook
record, or tmux session name. After a service restart it is empty, and boot performs no canvas-node
or terminal-session adoption: it does not attach-or-create missing backends and does not send a
persisted queued command even when a tmux backend survived. A later explicit owner open or browser
view is the only cold-spawn path. Plain terminals carry no agent identity or canvas-control grant;
missing agentId never means Claude.
A canvas-control write is not an outside edit. The factory mutates the project, saves it, and
broadcasts the whole thing on workspace:server-change — a channel of its own, separate from
the workspace:external-change the workspace watcher uses for a git pull or a hand edit. It shared
that channel until it was measured: the renderer classifies an outside edit by comparing the
project shell, ropes included, so the single ctrl-… rope every open-agent appends read as a
conflict whenever the canvas was dirty — which it is right through a spawn burst, because the
paired canvas:mut marks it dirty, spawns arrive inside the autosave debounce, and the conflict
bar suspends autosave, so the first one latched the bar on and every later write re-raised it.
"Keep my version" then serialized the browser's own edges over the file and dropped the ropes this
factory had just persisted. On the new channel the browser three-way merges instead
(renderer/lib/serverChange.ts): nodes the server opened are adopted silently, ropes and bridges
are merged against the last-known disk copy, and unsaved local edits survive. Nothing is asked of
the user, because both sides of this merge are the same application.
open-terminal / open-agent accept --run-now as a no-op: server opens already start at once,
headless. --run-now together with --after is refused, in the desktop's words
(RUN_NOW_AFTER_REFUSAL). run --node <id> delivers a node's retained launch (the Run now
button's job) for the node's creator only. It requires verified identity and resolves the node
through the ownership record, never by the first id match, because node ids can repeat across
projects. It refuses an SSH node before its write-ahead claim, and answers a --project naming any
other project as "no node with id". run, and every immediate open that carries a launch command,
deliver through the same echo-verified launcher the desktop's headless start uses
(core/headless-launch.ts), with release:false: the server keeps its client attached, which is
what keeps even a plain-shell session reachable. The deferred --after release (refreshArmed)
still pastes with sendText. Neither --run-now nor run unhides a closed project or raises a
notice, the same as the server's other immediate opens.
Validate upgrades with a disposable NODETERM_DATA_DIR and port. Restarting a shared live Server
service is an explicit operator action; it is not part of a test, repair, or boot-rescue flow.
Managed Claude accounts
Managed Claude accounts (several logged-in Claude identities side by side, each with its own
CLAUDE_CONFIG_DIR) work in the browser. Selecting one always did — env injection, the
transcript readers, the usage rows and the account pickers are all src/core — but the
lifecycle was welded to ipcMain, so a browser-only deployment could pick an account it had no
way to create (issue #313).
- The lifecycle is core.
src/core/claude-accounts-service.tsowns the fiveclaude-accounts:*channels (add / wait-login / cancel-wait / remove / link) and registers them through the platform seam, so both shells serve them:src/main/claude-accounts.tsis now a thin desktop wrapper, andregisterCoreHandlerscalls the sameregisterClaudeAccountsIpc(). The browser reaches them through a realbuildClaudeAccountsApiin the ws-bridge instead of the oldE_UNSUPPORTEDstub.waitLoginis a straight passthrough of a poll that runs up to five minutes — safe because the WS RpcClient has no request timeout, so a pending request rejects only when the socket drops. - Per-account hooks are installed at boot and at add. A managed account carries its own
settings.json(Claude Code resolves it relative toCLAUDE_CONFIG_DIR), so the managed status hook has to be written there too or that account reports no agent status at all.startServerruns the same per-account loop the desktop does right afterinstallManagedAgentHooks(), andaddinstalls into the fresh dir up front. - The canvas skill is desktop-only. Canvas control is not wired on this edition at all (the
hook server answers
control unavailableby name), so the service takes the skill installer as an optional dep and the server passes none — a per-accountSKILL.mdhere would point at nothing. - No remote (SSH) accounts. The Server Edition has no SSH-project manager, so an account
context carrying a
projectIdtakes the local path — the same degrade the desktop takes before its manager exists. - "Link existing config dir…" is a path on the SERVER. The handler
stats the directory and writes into it (the account'ssettings.json, the managed status hook) as the server user, wherever that user can reach — and a~typed in the browser expands to the server's home, not the browser user's. That is the same rule every other path field on this edition follows (the folder picker browses the server's disk), but it is worth saying out loud here, because the dir a person is linking is usually one they created by hand and think of as "mine".
Managed Codex accounts (S6)
The Server Edition arms the Codex record-signing secret but does not host the account-management IPC — that surface is desktop-driven over SSH.
- Arms the record secret (Decision 1). At boot
armServerNodeIdentity(src/server/node-identity-arm.ts) loads the raw node-auth secret and callssetCodexThreadIdentityAuthSecret(...)with it, so a managed Codex account's thread→node→account ownership records can sign and verify on a headless host. Headless Linux has no OS keychain, so the secret is 32 raw bytes atnode-auth-key.bin, mode0600— the same both-shells channel the desktop seals viasafeStorage. When the managed runtime and launcher are available, headless canvas-control launches route throughnodeterm-codexand claim that signed node identity; an unavailable capability still degrades to the barecodexcommand. - Does NOT host the account-management verbs.
initCodexAccountsregisters its IPC over Electron'sipcMainwith WebContents-owner authorization, which the headless bridge does not provide, sostartServernever calls it. This is not a silent gap: managed Codex logins on an SSH host are driven by the desktop over SSH (the remote account-add / device-login / import legs + the relay) — the host runs the relay + import, not its own copy of the account IPC. - Fail-closed, both ways. With no secret armed (unwritable key file), the record layer throws rather than writing anything unsigned, and Codex nodes keep working bare. A machine with no managed accounts is byte-for-byte the pre-S6 layout (a bare-root record per thread).
- A browser-only deployment therefore cannot manage Codex accounts — the case issue #313 is
about. Managed Claude accounts moved into core (above); Codex did not follow, and the reason
is not effort: its switch verbs (
switchThread/commitSwitch/finishSwitch/rollbackSwitch) authorize the owning window by Electron WebContents id, which has no meaning over a WS connection where every browser tab is an equally anonymous socket. Hosting them headless needs a connection-identity redesign first, not a handler port. Until then thecodexAccountsnamespace stays anE_UNSUPPORTEDstub in the bridge and the Settings section says so by name rather than failing silently — an unhandled rejection there previously stopped the spinner and showed nothing.
Manual browser smoke checklist
Run against a real browser (this is the human-verified path; the automated harness
only exercises the HTTP/auth surface). With npm run server:dev running:
- Setup / login — open
http://127.0.0.1:8443. On first run you're redirected to/setup(or use the printed setup URL); choose a password. On later runs you land on/login; sign in. - Add a terminal — click the dock
+and add a terminal node. It should spawn a shell and show a prompt. - Terminal I/O — type
echo hiand confirmhiprints. - Resize — drag the node's resize handle; the terminal should re-fit (cols/rows update) without garbling.
- Refresh the page — reload. The terminal must warm-reattach to its tmux session and redraw its current contents (running processes survive).
- Restart the server — stop
node out/server/main.cjs, start it again, reload the page. Same warm-reattach: the tmux server outlived the app, so state is intact. - Lockout — sign out (or open a fresh session), enter the wrong password 5 times; the 6th attempt should be rejected with a "too many attempts" lockout for ~60s.
- Open a folder (Phase 3a) — use "Open folder…"; the in-app server-directory
picker appears (no native dialog). Navigate to a git repo on the server and pick
it; a project opens on its
cwd. - Edit & save a file (Phase 3a) — open a file (Explorer or picker) into an editor node, make an edit, press ⌘S; the dirty dot clears and the change lands on disk.
- Source Control (Phase 3a) — open the Source Control panel; your edit shows as a change. Click it to see the diff, stage it (+), type a message, and commit; the file leaves the change list and the commit appears in recent commits.
- Agent status (Phase 3b) — open a Claude terminal node, run a prompt; the header should show the pulsing RUNNING badge while it works and clear (with an unread dot if the tab is unfocused) when it's done.
- Subagent card (Phase 3b) — from a Claude node, run a prompt that dispatches a
subagent (e.g. a
/task); an ephemeral subagent card appears connected to the parent node; click it to watch its live transcript stream. - Context meter (Phase 3b) — as a Claude session accumulates transcript, the node's context-window meter should fill.