Same-machine, token-gated, and local-first

Use the Local Web API when you want the Web control room plus a small same-machine HTTP surface.

./notesctl web does two things at once: it serves the local browser control room and exposes a token-gated JSON API over the same local process. This is a real local operator and builder surface. It is not a public OpenAPI, hosted API, or remote integration promise.

How to start it

export NOTES_SNAPSHOT_WEB_TOKEN="a-long-random-token"
./notesctl web --host 127.0.0.1 --port 8080

The default fit is same-machine use on 127.0.0.1. Keep the token gate on unless you have a deliberate local-only reason to relax it.

What it is good for

  • Browser-backed operator workflows: open the Web console and inspect health, state layers, recent runs, and access policy
  • Same-machine HTTP consumers: local tools that already speak HTTP can read the same local facts without screen-scraping
  • Builder debugging: inspect token, readonly, scope, allowlist, and cooldown policy from one place

Read endpoints

  • GET /api/health
  • GET /api/status
  • GET /api/log-health?tail=N
  • GET /api/doctor
  • GET /api/metrics?tail=N
  • GET /api/recent-runs?tail=N
  • GET /api/access

These endpoints stay truthful because they sit directly on top of the repo-owned notesctl, metrics, and state surfaces instead of inventing a second business system.

Action endpoints and safety boundary

  • Action routes exist for local operator actions like run, verify, ensure, install, permissions, and log rotation
  • Read-only mode, token scopes, action allowlists, rate limits, and cooldowns can all narrow what the Web API is allowed to do
  • This is why the page is called a local Web API, not a public automation platform

Stable builder contract today

  • ./notesctl help web is the narrow contract summary for the browser plus Local Web API lane
  • ./notesctl help audit is the narrow contract summary for token, scope, allowlist, readonly, and rate-limit policy
  • Safest builder starting point: read endpoints plus /api/access
  • Action routes: same-machine operator controls first; verify the current safety boundary before you treat them as reusable automation hooks

Need the host matrix and copyable setup examples? Open the Builder Integration Pack.

Need the repo-owned post-attach checklist? Start with post-attach-checklist.md and keep the first pass on /api/status, /api/recent-runs, and /api/access.

Minimal same-machine request shape

curl -H "Authorization: Bearer $NOTES_SNAPSHOT_WEB_TOKEN" \
  http://127.0.0.1:8080/api/status

curl -H "Authorization: Bearer $NOTES_SNAPSHOT_WEB_TOKEN" \
  "http://127.0.0.1:8080/api/recent-runs?tail=5"

How it differs from MCP

  • Local Web API: browser and same-machine HTTP surface behind ./notesctl web
  • MCP: stdio-first host-to-tooling contract behind ./notesctl mcp
  • Shared truth: both reuse the same deterministic local state surfaces

If your host already wants MCP, go to MCP Provider. If your local workflow is already browser- or HTTP-shaped, this page is the better fit.

What it does not claim

  • No public OpenAPI or generated SDK
  • No hosted API surface
  • No claim that remote internet exposure is the default safe path
  • No note-content API in v1