Web UI guide

The same engine behind a local dashboard. Nothing leaves your machine: the server binds loopback and serves the SPA plus a JSON API.

Launch

uv tool install '.[web]' --force   # once: install with the web extra
devdoctor serve                     # opens a browser tab at a random free port
devdoctor serve --port 8731 --no-browser

--port 0 (the default) picks a random free port; --port N binds N.

Pages

• Disk — the scan as charts and tables, with live progress while a scan runs. Risk chips and "untouched for" chips (30d+, 90d+, 6mo+, 1y+; the web form of scan --older-than) narrow the rows already loaded without another scan, and the totals row states how much of the volume's used space an unfiltered scan accounts for.
• Memory — RAM pressure plus top live consumers by real RSS, with safe fixes instead of raw kill.
• Cleanup wizard — the plan, per-entry prompts, and live output, step by step: the GUI form of clean --execute.
• History — past cleanup runs, shared with the CLI's history log.
• Snapshots — capture and diff disk states, shared with snapshot / diff.
• Settings — app preferences (also GET / PATCH /api/settings).

API (all under /api, loopback only)

Disk: GET /api/health · GET /api/scan · GET /api/disk/scan · GET /api/scan/progress (server-sent events) · GET /api/providers · POST /api/recipe · GET /api/disk-usage · GET /api/snapshots · POST /api/snapshots · GET /api/snapshots/{name} · GET /api/diff · GET /api/history · GET /api/dashboard/disk-summary.

Cleanup jobs (the wizard backend): POST /api/clean/jobs · GET /api/clean/jobs/{job_id}/events (SSE) · POST /api/clean/jobs/{job_id}/answer · POST /api/clean/jobs/{job_id}/confirm · POST /api/clean/jobs/{job_id}/cancel.

Memory: GET /api/memory · /api/memory/history · /api/memory/snapshots* · /api/memory/sources · /api/memory/providers · /api/memory/workloads · POST /api/memory/plan · POST /api/memory/actions.

Developing the UI

cd web && bun install --frozen-lockfile && cd ..   # one-time SPA deps
uv run devdoctor serve --port 8731 --no-browser  # terminal 1: FastAPI
cd web && bun run dev                          # terminal 2: Vite HMR (proxies /api)

Open http://localhost:5173. For a production-style run, ./scripts/deploy.sh builds the SPA, drops the stale wheel, and reinstalls with the bundle included.

Next: Tutorial · CLI reference · Docs for agents