@muninhq/serve

The Munin local host — munin serve.

The local PGlite store is single-process: only one process may open it at a time (an exclusive ${dataDir}.lock is taken before the store opens). munin serve is that one opener. It calls loadGraphStore(env) once, holds the handle and the lock for its whole lifetime, and exposes the engine reads and writes the local Studio, the MCP server and the munin CLI need over a loopback-only (127.0.0.1) HTTP API with a bearer token. Studio, the MCP server and the CLI data verbs (munin ingest/add/extract/docs/status/forget) all become clients of it, so they never open the store themselves and never fight over the lock.

This is part of the open-core local product (AGPL-3.0). The hosted/managed product and the verticals are separate and closed.

What it does

• Opens the store once and holds the lock (exactly one opener, always).
• Mints a random bearer token at startup and advertises { url, token } in $MUNIN_HOME/serve.json (file mode 0600).
• Serves authenticated reads on 127.0.0.1 only — no outbound network is added, so the MUNIN_LOCAL_MODE zero-egress posture is preserved.
• Releases the lock and removes serve.json on SIGINT / SIGTERM.

API

The full route list lives in src/http.ts (its header comment is the canonical index): the reads (/status, /retrieve-context, /ask, /gather, /document, /documents, the /mind/* Orrery routes, /settings), the writes (/upload + status/cancel, /documents/:id/erase, /settings/provider), and the CLI-through-host verbs (POST /extract + status/cancel, GET /documents/:id/erase-preview).

Every request must carry Authorization: Bearer <token>; anything else is 401. Permissions are enforced in the host against the real store (a single-user, fail-closed RegularReadContext); the HTTP boundary carries only already-filtered results.

Run

MUNIN_HOME=~/.munin \
GRAPH_STORE=local \
MUNIN_CONFIG_PACKAGE=@muninhq/config-personal \
pnpm --filter @muninhq/serve start

It prints the loopback URL and the path to the handshake file. Stop it with Ctrl+C (the lock is released and serve.json is removed).