Files
pipelines/web
..

Pipelines web client

The browser client for the Pipelines server: the Android app's feature set, rendered for the web, against the same WebSocket protocol and the same words. web/PARITY.md is the acceptance checklist and the single source of truth for what is done; this file covers how to run, test and verify it.

  • Dependency-free. Plain ES modules in the browser, hand-written CSS. No framework, no bundler, no build step, no npm install.
  • Browser-native transport. The page opens one WebSocket to /connect, matched by request id, with the same server-URL rules as the Android client.
  • Reported chat metrics. The top-right Chat information button opens output tokens/sec, total tokens, context usage/window and reported USD cost without taking space from the conversation. Unreported metrics are unavailable, not zero or a subscription-price estimate.
  • Verified in a real browser. UI claims are backed by PNGs captured from headless Chrome against a live server (test/ui-smoke.mjs); a unit test alone never marks a parity row done.

Safety

  • Authenticated browser proxy. Pages, assets, artifacts, and /connect require a signed session cookie. The proxy refuses to start without its configured password/secret file. Never disable authentication on a real service.
  • Private control APIs. Pipelines and harness APIs have no authentication. Keep them on loopback; expose only the authenticated proxy on a trusted LAN/VPN. Use TLS/VPN for remote access, not an Internet-facing raw API.
  • No secrets. The page stores only the server URL and its own small UI preferences (sort/filter choices, attention dismissals, device-local chat overrides) in localStorage; nothing is sent anywhere but the configured server.
  • No hardcoded server. The URL is entered by the user, prefilled from the page origin, and can be overridden.

Run it for development

For normal installation, use ./install. The following commands are for a separate development process with an existing web-auth file (PIPELINES_WEB_AUTH_FILE, default ~/.config/pipelines/web-auth.json). They do not create an account or configure autostart.

cd web
node serve.mjs                    # http://127.0.0.1:8090/ (proxies /connect and /artifacts/ -> 127.0.0.1:8080)
node serve.mjs --host 0.0.0.0     # reachable from other devices (trusted LAN/VPN)
node serve.mjs --port 8095 --pipelines 127.0.0.1:8080

The page's Server URL field (in Settings → Connection) prefills with ws://<this page's host><port>/connect — the proxy. Press Connect there the first time; the endpoint is then remembered and re-opened on later loads. Nothing is baked in.

On a deployment where ntfy already uses 8090, pick another port for the page (e.g. --port 8095). These commands are foreground processes; managed startup is described in the installation guide.

Test it

cd web
node --test test/                                             # unit tests, no server
PIPELINES_WS_URL=ws://127.0.0.1:8080/connect node test/smoke.mjs  # protocol, live
node test/ui-smoke.mjs --out /path/to/captures                # browser, live, screenshots

node --test covers the ported URL rules, the transport, and the pure feature logic (filters, sorting, diffs, graph layout, markdown, chat folding, routing, attention, alerts). It needs no server.

smoke.mjs drives the real client against a running server: ping, list_pipelines, list_runs, get_pipeline, get_run, artifact HEAD.

ui-smoke.mjs starts serve.mjs on an OS-assigned free port (so concurrent checks never collide), launches the installed Chrome headless, drives the real page and writes PNGs. That is the UI evidence: a review reports capture paths, not what it thinks would render. Set CHROME_PATH if Chrome is not at the default macOS location, and use --port/WEB_UI_PORT to pin a port.

Captures are deliberately gitignored: they are review evidence, not source, and keeping them out of the tree keeps a delivery checkout clean.

Layout

Area Where
Wire protocol, URL rules src/protocol.js, src/serverUrl.js
Transport (DOM-free, reused by the smoke test) src/client.js
Typed requests src/repository.js
Feature logic and models src/runs.js, src/runDetail.js, src/changes.js, src/artifacts.js, src/pipelines.js, src/templates.js, src/graph.js, src/chat.js, src/markdown.js, src/search.js, src/attention.js, src/actions.js, src/connection.js, src/settings.js, src/notify.js, src/runEvents.js, src/routes.js
Shell and views src/app.js (boot, state, navigation, render dispatch), view modules under src/views/
Styling per-area stylesheets linked from index.html
Server + /connect and /artifacts/ proxy serve.mjs
Tests test/*.test.mjs, test/smoke.mjs, test/browser.mjs, test/ui-smoke.mjs
Acceptance gate PARITY.md
Working map AGENTS.md

Keep client.js DOM-free: the smoke test and the page must drive the same transport module. Every server-derived string is set with textContent, never innerHTML — the transcript and diffs are untrusted model output.

Why the page connects through serve.mjs, not the server directly

internal/server/websocket.go calls websocket.Accept(w, r, nil), which rejects an upgrade whose Origin host does not match the request Host. A page served from port 8090 opening ws://HOST:8080/connect is refused with 403:

HTTP/1.1 403 Forbidden
request Origin "HOST:8090" is not authorized for Host "HOST:8080"

A Node or curl client sends no Origin and is accepted — which is why the protocol smoke can pass while a browser cannot. serve.mjs therefore proxies /connect (dropping Origin) so the page and the socket are one origin. It proxies /artifacts/ for the same reason: artifact URLs resolve against the configured server, which in a proxied deployment is the page's own origin, so the gallery's images, the viewer, session.html and downloads would otherwise 404 while the WebSocket worked.

Do not "fix" this by relaxing the server's Origin check — that check is the only thing between a random web page and an unauthenticated control API. Keep the proxy.

To open the page from another device, bind --host 0.0.0.0 and use this machine's LAN or Tailscale address for the page (e.g. http://100.85.25.33:8095/), then press Connect in Settings. Both hops are plaintext, so there is no mixed-content block; only do this on a trusted tailnet/VPN.

Verification notes

  • The browser is the gate, never a phone or emulator. No ADB, no device.
  • Artifact URLs resolve against the configured server (resolveArtifactUrl); the page opens them in a tab rather than embedding an Android WebView.
  • Where the browser genuinely cannot match Android (system-tray notifications need a secure context; pipelines:// links become URL routes), the parity row says so instead of pretending otherwise.
  • Feature checks that create server state (a chat, a pipeline) either use a scratch server or the server's explicit ephemeral flag, so verification never leaves clutter in the operator's lists.