peepshow serve
Local HTTP server · loopback by default · zero deps
peepshow serve boots a local HTTP server that browses the run history, streams frames + audio, manages auto-sinks, and exposes a JSON API. Pure node:http, no extra runtime deps. Single-user, bound to 127.0.0.1 by default — non-loopback bind requires a token.
Quick start
peepshow serve # http://127.0.0.1:7331/
peepshow serve --port 8080 --open # custom port + auto-open in browser
peepshow serve --host 0.0.0.0 # expose on the LAN — auto-generates a token
Routes
Pages
| Method | Path | Notes |
|---|
| GET | / | Homepage with newest-first run table. |
| GET | /runs/:runId | Per-run detail — same shell as the standalone report.html. |
| GET | /sinks | Auto-sink management UI (add via the form, remove per row). |
Streaming
| Method | Path | Content-Type |
|---|
| GET | /runs/:runId/manifest.json | application/json |
| GET | /runs/:runId/frames/:idx | image/jpeg (or png) |
| GET | /runs/:runId/audio.m4a | audio/mp4 (when present) |
JSON API
| Method | Path | Response |
|---|
| GET | /api/runs.json?limit=N&cursor=<runId> | { runs, nextCursor? } (paginated) |
| GET | /api/sinks | { sinks: SinkSpec[] } |
| POST | /api/sinks | { ok: true, idx } |
| DELETE | /api/sinks/:idx | { ok: true } |
| POST | /runs/:runId/annotate | Pipe LLM analysis from any HTTP client |
| GET | /healthz | { ok, version, runsCount } |
Security
- Loopback by default.
127.0.0.1, no auth, single-user. - Public bind requires a token.
--host 0.0.0.0 auto-generates one when omitted; pass via ?token=<hex> or the X-Peepshow-Token header. - No accounts, no sessions. This is a personal tool. Want multi-user? Run a reverse proxy with auth in front.
Config
peepshow config init # interactive wizard (covers report + serve)
peepshow config set serve.port 8080
peepshow config set serve.host 0.0.0.0
peepshow config set serve.autoOpen true
| Key | Type | Default | Meaning |
|---|
serve.port | int | 7331 | Default port. Override per-invocation with --port or PEEPSHOW_SERVE_PORT. |
serve.host | str | 127.0.0.1 | Default bind host. Override with --host or PEEPSHOW_SERVE_HOST. |
serve.autoOpen | bool | false | Open the configured browser on startup. |
Programmatic use
# Latest 10 runs as JSON
curl -s http://127.0.0.1:7331/api/runs.json?limit=10 | jq '.runs[].videoFilename'
# Annotate a run from a script
echo '{"summary":"Sintel meets the gatekeeper at 0:12"}' \
| curl -X POST -H "content-type: application/json" -d @- \
http://127.0.0.1:7331/runs/<runId>/annotate
