diff --git a/docs/dev/rest-api/dashboard.md b/docs/dev/rest-api/dashboard.md new file mode 100644 index 00000000..fd85cf38 --- /dev/null +++ b/docs/dev/rest-api/dashboard.md @@ -0,0 +1,82 @@ +# Developer Dashboard + +The dashboard endpoints show the operator of a `serve` instance what the server is doing: +version and uptime, request counts, live remote sessions, download jobs, and the recent +log lines. They exist so you can watch a headless server (`serve --quiet`) from a web page +instead of a terminal. + +The dashboard endpoints are for the person who runs the server, not for API users. They +have their own key: a user key or a tier key never opens them. + +## Enable + +Set a dashboard key under `serve.dashboard` in `unshackle.yaml`: + +```yaml +serve: + api_secret: ... + dashboard: + key: a-long-random-string +``` + +Without `dashboard.key` the server does not register the routes, and they answer `404`. +`serve --no-key` turns off user authentication only; the dashboard key stays required. +Once the dashboard key is set, every `/api/dashboard/` request must carry it in +`X-Secret-Key`. +Every other endpoint refuses the dashboard key, and the dashboard refuses user keys. The +routes are available in `--remote-only` mode too. + +Run the server headless with `--quiet`: no banner, no Rich output, one plain log line per +event on stderr, and `api.*` loggers stay at `INFO` so remote session activity reaches the +log ring. Add `--debug` to raise the level to `DEBUG` and also write the full log to +`directories.logs` as `unshackle_serve_