Run Noumenon as a Shared Service

Why Run a Shared Instance

A team using the same codebase doesn't each need their own knowledge graph. A shared Noumenon daemon holds one Datomic database per repo, everyone queries it, and the analyze cost is paid once instead of N times.

• Consistent answers. The Ask agent, MCP tools, and direct queries all read from the same graph, so different teammates get the same view of the same code.
• Cost amortization. The analyze stage is the expensive one. Run it once on the server, every reader benefits.
• Always-fresh data. Webhooks or a polling loop keep the graph current without anyone running noum update.
• No client setup beyond a token. noum connect <url> --token <t> makes every CLI command and MCP tool route through the remote daemon. Local repo paths are translated to canonical names, so noum ask ./my-repo "..." works against a shared graph.

How It's Deployed

One Docker container per instance. Bind mount a data volume for the Datomic store and the cloned repos, set NOUMENON_TOKEN to a random secret, and you're done. Front it with Caddy or Nginx if you want TLS and a public hostname.

The image is 167 MB. It runs Alpine plus a custom seven-module JRE built with jlink (just java.base, java.logging, java.naming, java.sql, java.xml, java.management, and jdk.unsupported); the only runtime dependency outside the JVM is git from Alpine's package repo.

Two roles. The admin token registers repos, mints reader tokens, and triggers re-imports. Reader tokens are read-only. Raw tokens are shown once at creation; only their SHA-256 hashes are stored in the Datomic meta-database, so leaks of disk state do not leak tokens. Rotate any of them at runtime without restarting the daemon.

Federated, not multi-tenant. Each instance is independent. There's no user identity beyond tokens, no single sign-on, no cross-instance graph sharing. Want a per-team or per-product split? Run multiple instances; they don't know about each other.

Datomic Local backs the default deployment with on-disk storage. For deployments that need full ACID durability across nodes — replication, backups against managed object stores, multi-AZ — Datomic Pro (free) supports PostgreSQL, DynamoDB, and Cassandra storage. The Noumenon codebase uses the Datomic client API, so swapping storage is a configuration change, not a code change.

Webhook Refresh

Point GitHub or GitLab at /api/webhook and the daemon re-imports on every push. Set NOUMENON_WEBHOOK_SECRET and the server verifies the HMAC signature (X-Hub-Signature-256 on GitHub, X-Gitlab-Token on GitLab) before doing anything.

If webhooks aren't an option, the server falls back to a polling loop on NOUMENON_POLL_INTERVAL minutes. Set it to 0 to disable polling entirely (recommended once webhooks are wired up). The configuration table and the exact request shape are in the Webhook Setup section of the deploy guide below.

Hardening note: when the daemon binds to anything other than 127.0.0.1 it automatically disables the ~/.noumenon/credentials fallback, so LLM credentials must come from env vars on the host. The daemon also warns at startup if NOUMENON_LLM_BASE_URL is http:// — terminate TLS at a reverse proxy and front the upstream LLM call with https:// in production. See Deployment Shapes.

Day-Two Operations

The DEPLOY.md mirror below covers the operational specifics: env vars (bind address, port, log format, concurrency, poll interval), reverse-proxy snippets for Caddy and Nginx, monitoring via /health plus structured-JSON logs, backup and restore via volume snapshot, rolling upgrades, and webhook setup with HMAC verification.