Everything about Centauri, on one page.

Install on Linux / macOS — the one-liner#

install.sh detects Linux or Darwin and amd64 or arm64, downloads the matching release binary from GitHub Releases, and moves it to /usr/local/bin/centauri (using sudo only if that directory isn't writable). It fetches one static file and nothing else goes through a shell. Pin a release with CENTAURI_VERSION.

curl -fsSL https://centauridb.com/install.sh | sh

# pin a version
CENTAURI_VERSION=v0.3.0 curl -fsSL https://centauridb.com/install.sh | sh
# then
centauri desktop

Manual fallback: download centauri-linux-amd64, centauri-linux-arm64, centauri-darwin-amd64 or centauri-darwin-arm64 from the latest release and chmod +x it.

Install on Windows — installer or zip#

centauri-windows-setup.exe (built from installer/centauri.iss) puts centauri.exe and the .bat launchers in C:\Program Files\Centauri, adds a Start Menu entry that runs centauri desktop, and an optional desktop icon. Your facts live in %APPDATA%\Centauri, so uninstalling never touches data. Prefer portable? Unzip centauri-windows-amd64.zip anywhere and double-click run-centauri.bat.

https://github.com/aniljacobv-lab/centauri/releases/latest
  centauri-windows-setup.exe   → installer (Start Menu + shortcut)
  centauri-windows-amd64.zip   → unzip, double-click run-centauri.bat

On first run you're asked Set up your private local AI now? [Y/n]. Press Enter and Centauri installs Ollama if needed and downloads the model trio once; when it's done you'll see ai: your private AI is ready — ASK and SEARCH now run on local models, nothing leaves this machine.

Docker & docker-compose#

The Dockerfile is a two-stage build (golang:1.22-alpine → alpine:3.20) with the binary at /usr/local/bin/centauri, VOLUME /data, port 7771, and ENTRYPOINT ["centauri"], so any subcommand works as the command. The admin token comes from CENTAURI_TOKEN.

docker build -t centauri .
docker run -p 7771:7771 -v centauri-data:/data -e CENTAURI_TOKEN=secret centauri

# docker-compose.yml (docs/deploy.md, recipe 3)
services:
  centauri:
    build: .
    command: ["serve", "-data", "/data/centauri.log", "-addr", ":7771", "-token", "${CENTAURI_TOKEN}"]
    volumes: ["centauri-data:/data"]
    ports: ["127.0.0.1:7771:7771"]   # localhost only; your proxy provides TLS
    restart: unless-stopped
volumes:
  centauri-data:

Build from source#

Go 1.22+ and nothing else: go.mod has an empty require block and the project treats that as a feature. centauri seed fills a log with synthetic retail price-change data (-skus, -stores, -changes) so there's something to query immediately.

go build -o centauri ./cmd/centauri
./centauri seed && ./centauri serve

# the same checks CI runs (CLAUDE.md)
go vet ./... && go test ./...
cd sdk/python && python -m unittest discover -s tests

Launch modes — desktop, serve, gateway and the launchers#

centauri desktop is the one-click experience: data in your profile, opens the Console in an app window or your browser, manages Ollama, AI on by default. centauri serve is headless (AI is opt-in with -ai auto). centauri gateway is the reverse proxy. Windows ships the same modes as double-click launchers; all assume port 7771 and %APPDATA%\Centauri\centauri.log (the gateway uses gateway.log on 8080).

centauri desktop                       # profile data, opens /console, manages Ollama
centauri serve                         # headless API + dashboards; AI opt-in
centauri serve -ai auto                # headless with local-AI provisioning
centauri gateway -data gateway.log -addr :8080 -admin :7771

Command reference#

usage: centauri <command> [flags]

Commands
  desktop  one-click start: data in your profile, the Centauri home opens in an app window (or your browser)
  serve    HTTP/JSON API — writes, queries, SSE watch, log shipping
  gateway  reverse proxy: routes/keys/audit live in a Centauri store (bi-temporal)
  mcp      Model Context Protocol server on stdio (connect AI agents)
  shell    interactive CeQL REPL (psql-style; \h for meta commands)
  seed     populate with synthetic price-change demo data
  demo     seed|clear a curated multi-domain example database (demo.log)
  setup    setup vision [-install] — ready a local AI (Ollama + PDF renderer)
  follow   replicate a primary's log into a read-only follower
  sync     bidirectional, echo-safe sync with a peer (-primary <url>); run on both
  verify   recompute the tamper-evidence hash chain over a log file
  doctor   read-only health check (chain, checkpoint, lock); safe on a live DB
  backup   copy a database to -to <file> and verify the copy's chain
  archive  seal a log into compressed, tamper-evident segments: -to <dir>
  seal     roll an archive's tail into a new segment: -data <archive-dir>
  merge    reconcile diverged copies: merge -to merged.log a.log b.log
  export   run a CeQL query and print/write results in a chosen format

Common flags
  -data <path>    log file to use            (default centauri.log)
  -addr <:port>   listen address (serve)     (default :7771)
  -token <tok>    HTTP API bearer token      (or set $CENTAURI_TOKEN)
  -lazy           keep payloads on disk so data can exceed RAM (serve/desktop)
  -ollama         desktop: auto-start a local Ollama & stop it on exit (default on)
  -format <fmt>   table | csv | jsonl | json | yaml | plain (export)
  -to <file>      output file ('-' or omitted = stdout)  (export/backup/merge)

Also present (not in the banner): retention, compact, archive-push, tablespace-demo. Notable serve flags: -read-token, -lazy-index, -tls-cert/-tls-key, -max-concurrency, -query-timeout, -max-concurrency-per-db, -log-format/-log-level, -group-commit, -shards, -checkpoint-every, -auto-seal-mb, -s3-endpoint/-s3-bucket/-s3-region/-s3-prefix, -oidc-issuer/-oidc-audience/-oidc-jwks/-oidc-write-scope, -pg-addr, -ha-lease/-ha-id/-ha-addr/-ha-ttl, -ai/-ai-yes. Each is explained in the track that uses it.

Five-minute quickstart — the HTTP API#

Writes go to POST /v1/append with an events array; each event names a subject, a facet, a type (OBSERVED, CORRECTION…), a provenance (SYSTEM_FEED, HUMAN_ENTRY, SCAN_VERIFIED, AI_INFERRED), a confidence and a value. Reads are plain GETs; /v1/query runs CeQL as ?q= or a JSON body. With -token set, add Authorization: Bearer to every call.

centauri serve -data my.log -token secret

curl -X POST localhost:7771/v1/append -H 'content-type: application/json' \
  -H 'Authorization: Bearer secret' -d '{
  "events": [
    {"subject":"sku:TEA-NEW","facet":"source","type":"OBSERVED",
     "provenance":"HUMAN_ENTRY","confidence":1,
     "value":{"price_cents":899,"category":"beverage","name":"loose leaf tea"}}
  ]
}'

curl 'localhost:7771/v1/stats'
curl 'localhost:7771/v1/context?subject=item:100001/store:4001'
curl 'localhost:7771/v1/asof?subject=item:100001/store:4001&at=2026-03-15'
curl 'localhost:7771/v1/pending?facet=pdt&older_than_days=21'
curl 'localhost:7771/v1/disagreements?field=price_cents'
curl -N 'localhost:7771/v1/watch?facet=pdt'
curl 'localhost:7771/v1/query?q=FACTS%20OF%20sku:TEA-NEW'

Five-minute quickstart — CLI & shell#

centauri shell is a psql-style CeQL REPL (it takes the writer lock so it won't race a running server): \d lists subjects; \schemas, \stats, \slots, \timing, \x, \format are the meta commands; \q quits. centauri export -q "…" prints a query as table / csv / jsonl / json / yaml / plain. centauri demo seed builds a curated multi-domain demo.log; demo clear removes it — the only "erase" in the product, and it only touches that disposable file.

centauri seed -data my.log -skus 2000 -stores 8 -changes 5
centauri export -data my.log -q "FACTS OF item:*" -format table
centauri shell -data my.log

centauri> FACTS OF toy:robot
centauri> \d
centauri> \timing
centauri> \q

The embedded web workspaces#

Every server process embeds its UIs with go:embed — nothing to deploy separately. The dashboard has the 🏗 Build my database button (Genesis), the AI panel, 📎 Vision upload, the ✨ plain-English helper and an honesty table. Studio is the AI-first IDE (object explorer, causal-graph view, edit-as-a-fact; SQL auto-routed). The Console is the suite home where you mint gateway API keys in the browser. In serve -lazy-index mode the root path serves the Tablespace Console instead: storage inspector, one-click Verify, query console, cache metrics.

http://localhost:7771/          dashboard (Genesis, AI panel, Vision, query bar)
http://localhost:7771/ceql      the CeQL Book — the canonical language reference
http://localhost:7771/studio    Centauri Studio (AI-first IDE)
http://localhost:7771/app       simple app: Ask / Add / Recent
http://localhost:7771/console   the Console: whole suite on one screen; mint API keys
http://localhost:7771/          Tablespace Console — when started with  serve -lazy-index

Open paths that need no token: the pages above, GET /v1/version, /livez, /readyz, /metrics, and (with -ha-lease) GET /v1/ha.

The mental model: subjects, facts, facets#

No tables, rows or documents. A subject is anything facts can be about (item:100001/store:4001, toy:robot), created the first time a fact mentions it. A fact is an immutable statement with two clocks (effective time — when it became true; recorded time — when the database learned it), a provenance, a confidence and causal links. A facet is which system's view the fact belongs to (source, register, pdt, shelf). A new fact on the same subject + facet supersedes the old one, which is kept forever: current state is just the newest layer of history. Name subjects like paths so wildcards behave like directories.

FACTS OF toy:robot                              -- what's true now
PUT toy:robot SET price_cents=500, color='silver'
HISTORY OF toy:robot                            -- the whole story

Reading: FACTS, projection, WHERE, paging#

Patterns use *. List fields to narrow output, including the built-in rank column for stable row numbers when paging. WHERE sees your value fields and the metadata (subject, facet, type, provenance, namespace, trust, effective, recorded, pending, superseded). Operators: = != > >= < <= IN LIKE MATCHES EXISTS AND OR NOT ( ); dotted paths reach nested values. String-equality filters use an automatic per-field secondary index; EXPLAIN shows when it's probed.

FACTS [fields] OF subject-pattern
  [FACET f] [AS OF t] [AS KNOWN AT t] [WHERE expr]
  [GROUP BY key] [ORDER BY key [DESC]] [LIMIT n] [OFFSET n]
  [WHY [DEPTH n]]

FACTS subject, price_cents, trust OF item:*/store:4001 ORDER BY price_cents DESC LIMIT 10
FACTS rank, subject, price_cents OF item:*/store:4001 ORDER BY price_cents DESC LIMIT 10 OFFSET 10
FACTS OF item:*/store:4001 WHERE trust >= 0.8 AND price_cents > 700
FACTS OF acme:* WHERE namespace = 'acme'

Writing: PUT, CORRECT, RETIRE#

Insert and update are the same act: PUT appends a fact that supersedes the prior one. CORRECT is the same but typed CORRECTION. RETIRE supersedes with {retired: true} — there is no DELETE, on purpose. PUT accepts FACET, TYPE, EFFECTIVE (future- or back-dated), CONFIDENCE, SCHEMA (validated write), PROVENANCE and REF (lineage). CeQL SET takes scalars only; nested arrays/maps go through POST /v1/append or an SDK. Writes need the admin token, an OIDC token with the write scope, or a scoped token granted write.

PUT toy:robot SET price_cents=450, color='red'
PUT toy:robot SET price_cents=400 EFFECTIVE '2026-07-01'   -- future-dated
CORRECT toy:robot SET price_cents=445                     -- typed CORRECTION
RETIRE toy:robot                                          -- supersedes with {retired: true}
RETIRE route:api FACET config                             -- retire one facet

Time travel: AS OF and AS KNOWN AT#

Two clauses because every fact has two clocks. AS OF t asks what was true at t. AS KNOWN AT t asks what the database believed at t — facts learned later are invisible even if they describe earlier times. Both together is the audit query: "on March 1, what did we think March 15 would be?" Times are forgiving: YESTERDAY, TODAY, NOW-7d, 10 DAYS AGO, 'yesterday 2pm CST', ISO dates, RFC3339, or raw UnixMicro. Aggregation, SEARCH, CONTEXT, PROFILE and the topology operators all accept these clauses.

FACTS OF item:100001/store:4001 AS OF '2026-03-15' AS KNOWN AT '2026-03-01'
FACTS OF toy:robot AS OF YESTERDAY
FACTS OF toy:robot AS OF NOW-7d
FACTS OF toy:robot AS OF 'yesterday 2pm CST'
CONTEXT FOR toy:robot AS KNOWN AT '2026-03-01'              -- decision replay
FACTS region, SUM(units) OF sku:* GROUP BY region AS KNOWN AT '2026-03-01'

Causality: WHY, EFFECTS, MATCH#

Causes are first-class links. Add WHY to any FACTS query and each result carries its causal chain; WHY <event-id> DEPTH n traces one event backwards, EFFECTS <event-id> forwards. MATCH finds every causal path between two subject patterns, walking outbound (CAUSES) or inbound (CAUSED BY), optionally restricted by VIA to one link type (TRIGGERED, SUPERSEDES, CORRECTS, DISTRIBUTED_AS, ACTIVATED_BY, ENRICHED_FROM). The HTTP equivalent of a trace is GET /v1/trace?event=<id>&direction=cause|effect.

FACTS OF toy:robot WHY DEPTH 3
WHY 0193fa2e-77c1… DEPTH 6       -- what led to this event
EFFECTS 0193fa2e-77c1…           -- what this event led to
MATCH item:* CAUSES register:* VIA TRIGGERED DEPTH 3
MATCH item:100001/store:4001 CAUSED BY * VIA CORRECTS
MATCH intent:* CAUSES pdt:* DEPTH 5 LIMIT 50

Trust: DISAGREE, PENDING, CONTEXT#

Facets let different systems hold different beliefs about one subject, and reconciliation becomes a query. DISAGREE ON <field> lists subjects whose facets disagree, with a trust-ranked suggested winner. PENDING <facet> OLDER THAN n DAYS finds facts that were distributed but never activated ("wedges"); POST /v1/activate closes one. CONTEXT FOR <subject> returns in one call what an agent needs to reason: current facts, recent history, causal chains, disagreements with a suggested resolution, pending wedges, enrichments, schemas and a confidence summary — rebuildable as of any past moment with AS KNOWN AT.

DISAGREE ON price_cents
PENDING pdt OLDER THAN 21 DAYS
CONTEXT FOR toy:robot
CONTEXT FOR toy:robot AS KNOWN AT '2026-03-01'

Reversible transactions: SNAPSHOT, ROLLBACK, DIFF#

Because nothing is erased, a rollback appends superseding reversion facts that restore each subject to a chosen past point and records the rollback itself as an auditable event. AS OF still sees the pre-rollback world, HISTORY grows rather than shrinks, and a rollback is itself reversible. SNAPSHOT 'name' is a durable fact (it survives the session, unlike SQL SAVEPOINT); DIFF previews the delta first.

SNAPSHOT 'before-import'
DIFF OF toy:* BETWEEN '2026-03-01' AND '2026-03-15'
ROLLBACK                                  -- undo the last commit
ROLLBACK TO SNAPSHOT 'before-import'
ROLLBACK OF toy:* TO '2026-03-15'

Aggregates, COUNT DISTINCT and HyperLogLog#

Aggregates run over current facts and respect time travel: COUNT(*) COUNT(f) COUNT(DISTINCT f) APPROX_COUNT_DISTINCT(f) SUM AVG MIN MAX MEDIAN STDDEV LISTAGG. COUNT(DISTINCT) is exact; APPROX_COUNT_DISTINCT uses HyperLogLog (internal/ceql/hll.go) with a fixed ~16 KB of memory and ≈0.8% error regardless of cardinality. MEDIAN, STDDEV (population) and LISTAGG carry the Oracle names.

FACTS facet, COUNT(*), AVG(price_cents), MAX(price_cents)
  OF item:*/store:4001 GROUP BY facet
  HAVING COUNT(*) > 5 AND AVG(price_cents) > 300

FACTS APPROX_COUNT_DISTINCT(region) OF item:*
FACTS MEDIAN(price_cents) OF item:*/store:4001
FACTS facet, LISTAGG(kind) OF item:*/store:4001 GROUP BY facet
FACTS facet, AVG(price_cents) OF item:* AS KNOWN AT NOW-2d GROUP BY facet

Schemas#

Optional, versioned and append-only: DEFINE SCHEMA creates a new version; facts written under v1 stay valid against v1. Types are number string bool any; constraints REQUIRED MIN MAX UNIT; a field can carry a description. Write with SCHEMA <id> to validate — a rejection names the bad field. Over HTTP: POST /v1/schema, GET /v1/schema.

DEFINE SCHEMA price (
  price_cents number REQUIRED MIN 1 UNIT 'cents',
  kind string
) TITLE 'A retail price'
PUT toy:car SET price_cents=300 SCHEMA price   -- validated
SCHEMAS            -- list all (latest versions)
SCHEMA price       -- every version of one

Standing queries: WATCH#

A WATCH never finishes: it streams every matching fact the moment it commits. In the dashboard it feeds the LIVE panel; over HTTP it is the GET /v1/watch SSE stream (filterable by facet and type); in the Python SDK it's for e in db.watch(...). Streaming endpoints (/v1/watch, /v1/changes, /v1/log) are exempt from admission limits.

WATCH ALL
WATCH toy:robot
WATCH ALL FACET pdt TYPE DISTRIBUTED

curl -N 'localhost:7771/v1/watch?facet=pdt'

Hybrid search: SEARCH, BM25, vectors, SIMILAR#

SEARCH '<text>' OF <pattern> ranks by Okapi BM25 computed in a single pass in pure Go (internal/ceql/bm25.go) — bi-temporal like everything else. It blends with vectors two ways: SIMILAR TO <event> ALPHA a mixes BM25 with embedding similarity to a reference event (ALPHA 1.0 = pure keyword, 0.0 = pure semantic, default 0.5); and with a local embedder registered, SEARCH embeds the query text itself and blends meaning into the ranking. The final order folds in recency, trust (confidence × provenance) and causal centrality, and every hit returns its signal breakdown. SIMILAR TO <event-id> TOP k MIN score is pure vector search. Without an embedder SEARCH is plain BM25 and never errors. SEARCH also indexes AI-derived text (vision descriptions, summaries).

SEARCH 'late markdown' OF item:* LIMIT 10
SEARCH 'markdown' OF item:* SIMILAR TO 0193fa2e-77c1 ALPHA 0.5
SEARCH 'penny' OF item:* AS KNOWN AT '2026-03-01'
SIMILAR TO 0193fa2e-77c1… TOP 5 MIN 0.7

curl 'localhost:7771/v1/similar?event_id=<id>&k=5&min_score=0.7'

Topology: SHAPE, CONSISTENCY, CYCLES, DRIFT#

Four stdlib-only operators (internal/ceql/topology.go) answer questions about the shape of data. SHAPE OF <pattern> ON <fields> computes persistent homology of a value cloud (Betti-0 clusters, Betti-1 loops, Betti-2 voids with MAXDIM 2); WINDOW n STRIDE m builds a time-delay embedding so a periodic signal becomes a loop; ON EMBEDDING METRIC cosine analyses stored vectors. CONSISTENCY OF <subject> ON <field> [EPS n] treats the facets observing a subject as a sheaf: a global section exists iff they agree. CYCLES finds H1 of the causal graph — lineage must be acyclic, so any cycle is a data-integrity alarm. DRIFT … BUCKETS n is a regime-change detector. All accept AS OF / AS KNOWN AT.

SHAPE OF item:*/store:4001 ON price_cents
SHAPE OF item:* ON price_cents, trust, av_cost MAXDIM 2
SHAPE OF item:100001/store:4001 ON price_cents WINDOW 12 STRIDE 2
SHAPE OF item:* ON EMBEDDING METRIC cosine
CONSISTENCY OF item:100001/store:4001 ON price_cents EPS 5
CYCLES IN CAUSES OF item:100001/store:4001
DRIFT OF item:*/store:4001 ON price_cents BUCKETS 6

Modeling hierarchies without foreign keys#

Nodes are subjects and parent pointers are ordinary facts, so a hierarchy is bi-temporal: a reclass is one PUT, and January reports re-run under January's hierarchy. Denormalize ancestry onto leaf facts (dept, class, region) so roll-ups are one GROUP BY that time-travels. Facets carry each system's belief about a leaf, so DISAGREE and PENDING replace reconciliation batches. Integrity is schemas plus CePL procedure gateways: applications call procedures; only admins use raw PUT. Full write-up: docs/modeling-hierarchies.md.

PUT class:3204       SET name='Slim Fit',   parent='dept:320'
PUT sku:100001-RED-32/store:4001 FACET source
  SET units=12, cost_cents=900, price_cents=1999,
      dept='dept:320', class='class:3204', region='region:4'
  SCHEMA sku_loc_status
FACTS dept, SUM(units), AVG(price_cents) OF sku:* GROUP BY dept
FACTS OF class:3204 AS OF '2026-01-15'     -- which dept was it in, in January?

Operations: PROFILE, SUBJECTS, STATS, EXPLAIN#

PROFILE OF <pattern> describes the data (fields, types, coverage, ranges, top values) as of any moment. SUBJECTS LIKE … LIMIT n lists subjects; STATS returns store counters. EXPLAIN <query> returns the access path plus the JSON AST without running; EXPLAIN ANALYZE runs it and reports rows and timing (reads only). Agents can submit the JSON AST directly to /v1/query — also the escape hatch for strings that can't be embedded in CeQL literals, which have no escapes.

PROFILE OF item:*
PROFILE OF item:* AS KNOWN AT '2026-03-01'
SUBJECTS LIKE item:*4001 LIMIT 50
STATS
EXPLAIN FACTS OF toy:robot WHY
EXPLAIN ANALYZE FACTS OF item:*

Lean read-only SQL at /v1/sql#

For people and LLMs who think in SELECT, a lean SQL subset (internal/ceql/sql.go) transpiles to CeQL and runs through the same executor (GET /v1/sql?q= or POST /v1/sql {"q"}; Studio auto-routes SQL). Supported: SELECT * | col, AGG(col) with COUNT SUM AVG MIN MAX; FROM <name> maps to namespace <name>:*, FROM facts to all subjects, a quoted FROM 'item:1' to an exact subject or pattern; WHERE with = != <> < <= > >= IN LIKE AND OR NOT (); GROUP BY, HAVING, ORDER BY, LIMIT n [OFFSET m]; time travel with AS OF / AS KNOWN AT, with SQL:2011 FOR SYSTEM_TIME AS OF as a synonym. It rejects what it doesn't support rather than mis-answering.

SELECT * FROM sku WHERE category = 'beverage' AND price_cents > 1000 ORDER BY price_cents DESC LIMIT 5
SELECT category, AVG(price_cents) FROM facts GROUP BY category HAVING COUNT(*) > 3
SELECT * FROM 'item:1' FOR SYSTEM_TIME AS OF 'yesterday'

curl "localhost:7771/v1/sql?q=SELECT%20*%20FROM%20sku%20LIMIT%2010"
curl -X POST localhost:7771/v1/sql -H 'content-type: application/json' \
  -d '{"q": "SELECT category, COUNT(*) FROM facts GROUP BY category"}'

Postgres wire protocol: psql, JDBC, DBeaver, BI tools#

Start serve with -pg-addr :5432 and Centauri also speaks the PostgreSQL frontend/backend protocol v3 (internal/pgwire, stdlib only), so psql, JDBC/ODBC clients and BI tools connect directly and run the same read-only SELECT subset. Both the simple and the extended (Parse/Bind/Describe/Execute) sub-protocols are implemented, so prepared statements with parameters work in JDBC and psycopg default modes.

centauri serve -data my.log -pg-addr :5432 -token secret
psql 'host=localhost port=5432 user=any password=secret sslmode=disable'

-- inside psql
SELECT * FROM sku WHERE category='beverage' LIMIT 10;
SELECT * FROM 'item:1' FOR SYSTEM_TIME AS OF 'yesterday';

Plain English → CeQL#

The dashboard query bar accepts plain English and the ✨ helper translates it (internal/ceql/natural.go): deterministic rules first — no model, no API key, shows you the CeQL — then the local LLM for the long tail when one is registered. Model output is re-parsed before it's offered, so a suggestion is never invalid CeQL. When a query fails to parse the same helper offers a "did you mean".

curl -X POST localhost:7771/v1/assist -H 'content-type: application/json' \
  -d '{"text": "what was the price of item:100001/store:4001 yesterday at 2pm CST"}'

Scoped tokens and field masking#

Beyond the admin (-token) and read-only (-read-token) tokens, POST /v1/acl registers a token confined to subject prefixes (only its SHA-256 is stored, as an acl:<hash> fact). It may run CeQL only over subjects within its prefixes, only via /v1/query, and may write only if granted; mask lists value fields redacted ("***") in that token's results — the store is never mutated. Deny-by-default for anything broader. A CePL procedure plus a scoped token is the safe surface for an agent.

curl -X POST localhost:7771/v1/acl -H 'Authorization: Bearer <admin>' \
  -H 'content-type: application/json' \
  -d '{"token":"agent-secret","prefixes":["item:"],"write":false,"mask":["cost_cents"]}'

How local AI works — and what is not in the binary#

Orchestration — retrieval, hybrid BM25+vector ranking, RAG answering, enrichment, model selection — lives in stdlib Go (internal/ai). Model weights (2–20 GB) do not. Ollama is the default runtime (OpenAI-compatible; LocalAI and vLLM also work). A model is registered as a plain fact (model:<name>, facet config). With no suitable model registered, the non-LLM path answers and queries never break.

PUT model:chat FACET config SET endpoint='http://localhost:11434/v1/chat/completions',
  kind='chat', model='qwen3:14b'

Tiers & presets#

-ai auto (default for desktop; opt-in on serve) detects total memory and picks a tier; small | balanced | max force one. Each tier is a chat + embedder + vision trio pulled via Ollama. The table is config, not a contract (internal/ai/presets.go).

glm-4.7-flash is a 30B MoE / 3B-active, MIT-licensed model with a 200K context, ~19 GB at Q4 — the strongest open model that fits a 24 GB GPU.

centauri desktop                   # turnkey: auto-detect, auto-install, auto-pull
centauri serve -ai auto            # server: detect hardware + provision
centauri serve -ai small           # force a tier: small | balanced | max
centauri serve -ai auto -ai-yes    # skip the one-time consent prompt (unattended)

Ollama provisioning — what happens in the background#

With AI mode on, startup is instant and provisioning runs in the background: detect the tier from total memory; install Ollama if missing (winget on Windows, brew on macOS; on Linux it prints the one-line installer and never pipes curl|sh automatically); start Ollama (stopping on exit only the instance it started; -ollama=false opts out; serve never auto-manages Ollama); pull the tier's models, skipping any already present; register them as model:* facts and turn on auto-embed. Everything is idempotent. The one-time opt-out is recorded in .centauri-ai-optout next to the data file. If Ollama can't be installed automatically, Centauri still runs; AI lights up once you install it and restart.

GET  /v1/ai/status                     # progress; where answers are computed (local / cloud / none)
POST /v1/ai/enable  {"tier":"auto"}    # turn on fully-local AI (auto | small | balanced | max)
POST /v1/ai/local   {"tier":"auto"}    # switch back to local — the reversible off-switch

All /v1/ai/* endpoints are admin-token-only, including the GET.

Auto-embed and ENRICH#

With local AI enabled, every new fact embeds itself in the background right after it commits — both ingest paths — so data is instantly SEARCH / SIMILAR / ASK-able. Embeddings are ordinary enrichment facts and never touch the original write's hash chain. ENRICH <pattern> USING <model> [ON <field>] [AS <kind>] (internal/ceql/enrich.go) runs a registered model over matching events from the query itself and stores the result as a superseding, provenanced enrichment fact; re-runs skip what's done, so inference is cached in the log. POST /v1/feedback {event, score, note} stores an append-only rating in [-1, 1] that nudges future retrieval — no weights change.

PUT model:embed FACET config SET
  endpoint='http://localhost:11434/v1/embeddings', kind='embedding', model='nomic-embed-text'
ENRICH item:*   USING embed                       -- embeddings → vector index
ENRICH ticket:* USING summarize ON body AS summary
ENRICH asset:*  USING vision                      -- describe images / PDF pages

ASK — RAG with citations#

ASK '<question>' answers from the built-in knowledge base first (Q&A live as kb:<slug> facts, ranked by the same BM25 ranker as SEARCH). With a chat model registered, a question the KB can't answer retrieves your most relevant facts (hybrid BM25 + vector), has the local LLM answer using only those, and returns grounded: true, the answer, and sources (event ids) so every answer is checkable. Without a chat model, ASK records the question as a kb_gap:<slug> fact instead of guessing — an agent can later answer it by appending a kb: fact. Because knowledge is facts, FACTS OF kb:* AS KNOWN AT … tells you what the assistant would have said last month.

ASK 'how much does the widget cost'
ASK 'summarize the history of item:1'
ASK 'why do these prices disagree'

FACTS OF kb_gap:*                       -- 1. what couldn't we answer?
PUT kb:does-it-scale FACET knowledge    -- 2. an agent teaches the answer
  SET question='does it scale?', answer='Single-node, in-RAM working set…'
ASK 'does it scale?'                    -- 3. now answered from the database

Vision — files an AI can read, locally#

Upload an image or PDF (POST /v1/assets or the dashboard's 📎 panel); pages are rendered locally, a vision model describes them, and the description is embedded into the vector index — so SEARCH 'E-3 200A panel' finds the drawing. Two helpers can't be bundled: Ollama (multimodal model + embedder) and a PDF rasteriser (poppler pdftoppm or ImageMagick magick; plain images need neither). centauri setup vision -install installs what's missing via your OS package manager and pulls the models; drop -install to just check (exits non-zero when something is missing). Status: GET /v1/vision/status; fetch a stored asset with GET /v1/assets/{sha}.

centauri setup vision -install
centauri desktop                 # or: centauri desktop -ollama=false to manage Ollama yourself

SEARCH 'E-3 200A panel' OF asset:*
FACTS OF asset:*
SIMILAR TO <asset-event-id> TOP 5

Windows gotcha: the bare convert command is the System32 filesystem tool, not ImageMagick; Centauri ignores it and uses pdftoppm or magick.

The cloud boost — GLM-5.2, GPT-5.5, Claude, custom#

Out of the box Centauri is 100% local. Optionally, paste a provider key into the dashboard AI panel (or POST /v1/ai/cloud) to switch chat to a cloud model. Providers: zai (GLM-5.2, the default), openai (GPT-5.5), anthropic (Claude), or custom (any OpenAI-compatible server, key optional — a LAN Ollama box works keyless). Each provider keeps its own key in its own 0600 file next to the data file; the key never enters the log. Embeddings and vision stay local either way.

curl -X POST localhost:7771/v1/ai/cloud -H 'Authorization: Bearer <admin>' \
  -H 'content-type: application/json' \
  -d '{"provider":"zai","api_key":"<ZAI_KEY>","model":"glm-5.2"}'
curl -X POST localhost:7771/v1/ai/local -H 'Authorization: Bearer <admin>' -d '{"tier":"auto"}'
curl localhost:7771/v1/ai/status -H 'Authorization: Bearer <admin>'

-- registering a remote model by hand: the secret is named, never stored
PUT model:summarize FACET config SET endpoint='https://api.openai.com/v1/chat/completions',
  kind='chat', model='gpt-4o-mini', auth_env='OPENAI_KEY'
PUT model:cloud FACET config SET endpoint='https://api.z.ai/api/paas/v4/chat/completions',
  kind='chat', model='glm-5.2', auth_file='/path/to/zai.key', timeout_secs='600'

The Genesis Engine — describe it, get a database#

Describe your scenario in plain language and Centauri (internal/architect) interviews you and builds the entire database — schemas, CePL procedures, watches, starter queries — then stores the conversation as blueprint:* facts so the database forever remembers why it exists. Two paths: a description with an adaptive interview, or paste CREATE TABLE DDL (the RDBMS import path). POST /v1/architect/plan with {description, answers} returns questions until none remain, then a blueprint; POST /v1/architect/apply (admin) builds it into a new named environment (<env>.log next to the data file — the server must host a data directory). The dashboard's 🏗 button and the centauri_genesis MCP tool drive the same engine.

curl -X POST localhost:7771/v1/architect/plan -H 'content-type: application/json' \
  -d '{"description":"a small bakery tracking orders, suppliers and daily waste","answers":{}}'
# → {"questions":[...]}  … answer them, resend with "answers" filled … → {"blueprint":{...}}
curl -X POST localhost:7771/v1/architect/apply -H 'Authorization: Bearer <admin>' \
  -H 'content-type: application/json' -d '{"description":"...","answers":{...}}'

# RDBMS import path
curl -X POST localhost:7771/v1/architect/plan -H 'content-type: application/json' \
  -d '{"ddl":"CREATE TABLE item (id INT PRIMARY KEY, name TEXT, dept_id INT);","answers":{}}'

CePL stored procedures#

CePL (internal/proc) is a deliberately tiny near-English language inside the database: a procedure is stored as a versioned proc:<name> fact, run by name, and every run returns a step-by-step trace. Statements: PROCEDURE name(p1, p2) … END, LET x = FIRST FACTS OF … (binds a CeQL read), LET y = <expression>, WHEN <guard>: <step> (IS MISSING / IS PRESENT), PUT / CORRECT / RETIRE with ${var} holes, FAIL 'msg', RETURN value. Substitution is injection-safe: templates are re-parsed as CeQL after filling, numbers render bare, a string glued to a word accepts only token-safe characters and never *, and anything else becomes a quoted literal. HISTORY OF proc:x shows every version; writes carry REF 'proc:x' lineage; every stored procedure is auto-exposed over MCP as a typed proc_<name> tool.

PROCEDURE duty_estimate(item, units)
  LET rate = FIRST FACTS OF hts:${item} FACET assess
  WHEN rate IS MISSING: FAIL 'no duty rate on file for ${item}'
  LET cost = FIRST FACTS OF cost:${item}
  WHEN cost IS MISSING: FAIL 'no average cost for ${item}'
  LET duty = cost.av_cost * units * rate.comp_rate
  PUT duty:${item} SET duty_amt=${duty}, units=${units} REF 'proc:duty_estimate'
  RETURN duty
END

# define (admin): body is {"source": "<procedure text>"}
curl -X POST localhost:7771/v1/proc -H 'Authorization: Bearer <admin>' \
  -H 'content-type: application/json' -d '{"source":"PROCEDURE …\n…\nEND"}'
# run
curl -X POST localhost:7771/v1/proc/run -H 'Authorization: Bearer <admin>' \
  -H 'content-type: application/json' \
  -d '{"name":"duty_estimate","args":{"item":"100001","units":3}}'

RUN duty_estimate WITH item='100001', units=3      -- from the query bar / shell
HISTORY OF proc:duty_estimate                      -- every version ever deployed

MCP server — Claude Desktop, Claude Code, Cursor, agents#

centauri mcp runs a Model Context Protocol server over stdio against a local log (internal/mcp), keeping stdout clean. It exposes 20 typed tools — centauri_context, centauri_current, centauri_asof, centauri_history, centauri_trace, centauri_pending, centauri_disagreements, centauri_similar, centauri_by_ref, centauri_append, centauri_activate, centauri_enrich, centauri_put_schema, centauri_get_schemas, centauri_ceql, centauri_define_procedure, centauri_run_procedure, centauri_genesis, centauri_subjects, centauri_stats — plus one auto-generated proc_<name> tool per stored procedure. Any MCP host uses the same mcpServers block: Claude Desktop (claude_desktop_config.json), Claude Code (.mcp.json or claude mcp add), Cursor (.cursor/mcp.json).

{ "mcpServers": { "centauri": { "command": "centauri", "args": ["mcp"] } } }

{ "mcpServers": { "centauri": { "command": "centauri", "args": ["mcp", "-data", "/path/to/my.log"] } } }

Non-MCP hosts (OpenAI, Gemini, Grok, Mistral, local runners) use a single centauri_query tool that forwards CeQL to POST /v1/query — the CeQL Book (section 14½) shows the pattern, including OpenAI(base_url="http://localhost:11434/v1") for Ollama.

The hash chain: verify, backup, doctor#

The store is an append-only JSONL log with in-memory indexes (internal/store). On open it replays the log (shortcut by centauri.checkpoint); -checkpoint-every N seconds writes that recovery checkpoint while serving so a crash replays only seconds of tail. Every committed line is covered by a per-line SHA-256 chain (integrity.go). centauri verify recomputes it and prints the chain head — record it somewhere external; a future verify reproducing it proves the history is byte-for-byte intact. backup copies the committed log (safe while serving) and verifies the copy's chain head equals the source's. -lazy keeps payloads on disk so data can exceed RAM while the index still fits.

centauri verify -data my.log
centauri backup -data my.log -to backups/my-2026-10-28.log
centauri doctor -data my.log
centauri serve -data my.log -checkpoint-every 30 -lazy

Tablespaces: archives, sealed segments, Merkle roots#

centauri archive -to <dir> seals a log into compressed (typically 5–10×), tamper-evident segments plus a manifest.json. Each segment carries a Merkle root (internal/segment/merkle.go; O(log n) inclusion proofs) and zone maps (min/max times, namespace prefixes, field stats) so queries skip segments that can't match; stats and chain heads stay uncompressed in the manifest, so pruning and verify need no decompression. Serving an archive dir replays sealed segments plus an appendable tail; -auto-seal-mb N seals the tail once it passes N MB (Oracle-style log switch) and centauri seal does it by hand, crash-safe via one atomic manifest switch. compact merges consecutive segments offline without erasing. verify -fast scrubs per-segment Merkle roots in parallel. Sealed segments support per-segment AES-256-GCM crypto-erasure — destroy the key, keep the chain.

data/
  manifest.json              # ordered segments + stats + chain heads
  segments/
    00000001.log             # sealed, immutable
    current.log              # the open, appendable tail
  centauri.checkpoint

centauri archive -data mydb.log -to mydb-archive -seg-max 100000
centauri serve -data mydb-archive -auto-seal-mb 256
centauri seal -data mydb-archive
centauri compact -data mydb-archive -group 8
centauri verify -data mydb-archive -fast
centauri tablespace-demo        # seed → archive → retrieve → insert, end to end

The lazy index — serving bigger-than-RAM, read-only#

serve -lazy-index -data <archive-dir> opens an archive with the disk-backed index (internal/store/lazyindex.go): one streaming pass keeps only the current fact per (subject, facet) in RAM, so memory scales with live subjects, not total events. history/asof stream zone-map-pruned segments from disk through an LRU of decompressed segments; a Merkle-validated pointer checkpoint (lazy.ckpt) makes restart replay only the tail. It honours -read-token, native TLS, admission limits, and serves the Tablespace Console at / plus /livez, /readyz, /metrics.

centauri serve -lazy-index -data mydb-archive -read-token viewer

curl 'localhost:7771/v1/lazy/stats'
curl 'localhost:7771/v1/segments'
curl 'localhost:7771/v1/verify'
curl 'localhost:7771/v1/current?subject=sku:COFFEE-001&facet=source'
curl 'localhost:7771/v1/lookup?field=category&value=beverage'
curl 'localhost:7771/v1/history?subject=sku:MILK-002&facet=source'
curl 'localhost:7771/v1/search?q=beverage&limit=10'
curl 'localhost:7771/v1/cache'

S3-compatible object store — the cold tier#

internal/objstore provides a segment store with a local-dir backend and an S3-compatible backend (AWS S3, MinIO, Cloudflare R2, Backblaze B2) using stdlib net/http and a hand-rolled AWS Signature V4 signer — no SDK. centauri archive-push uploads a sealed archive; -pull restores it; serve -lazy-index -s3-endpoint … -s3-bucket … reads segments from the bucket on demand, Merkle-verifies each one (untrusted storage is safe) and LRU-caches them. GET/PUT/byte counters appear on /metrics as centauri_objstore_*. Credentials come only from AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY.

export AWS_ACCESS_KEY_ID=… AWS_SECRET_ACCESS_KEY=…
centauri archive-push -data mydb-archive -s3-endpoint http://localhost:9000 -s3-bucket centauri -s3-prefix prod
centauri archive-push -data restored-archive -s3-endpoint http://localhost:9000 -s3-bucket centauri -s3-prefix prod -pull
centauri serve -lazy-index -s3-endpoint https://s3.us-east-1.amazonaws.com -s3-bucket my-bucket -s3-prefix prod -read-token viewer

Write scaling: group commit and sharding#

Writes are single-writer per log by design — the per-line hash chain is sequential. Two levers: -group-commit coalesces concurrent appends into one fsync per batch on a single chain; serve -shards N (with -data a directory) partitions subjects across N independent shard logs by FNV-1a hash of the subject — each its own chain, lock and committer — written in parallel (~N× throughput). Routed: /v1/append, /v1/current, /v1/history, /v1/asof, /v1/subjects (union), /v1/shards, /v1/query for a concrete subject, and fan-out (internal/ceql/fanout.go) for wildcard FACTS/HISTORY/SEARCH.

centauri serve -data my.log -group-commit
centauri serve -data ./shards -shards 4 -token secret
curl localhost:7771/v1/shards

HA failover and leader election#

serve -ha-lease <shared dir> -ha-addr <url> runs lease-based leader election (internal/ha): the node holding the lease is the writable primary; the rest start read-only and replicate from it; when the primary's lease lapses a replica acquires it and promotes itself — no operator action. Split-brain is prevented by a monotonic epoch fencing token plus self-fencing: a primary stops accepting writes the instant it can't confirm a live lease. GET /v1/ha reports role/epoch/leader. The bundled lease store uses atomic O_EXCL creation on a shared POSIX filesystem (NFS / EBS multi-attach / k8s shared volume); for multi-AZ without shared storage, plug in any CAS-capable LeaseStore (one interface, two methods).

# node A and node B, same shared lease dir
centauri serve -data a.log -addr :7771 -ha-lease /mnt/shared/centauri-lease -ha-id a -ha-addr http://a.internal:7771 -token secret
centauri serve -data b.log -addr :7771 -ha-lease /mnt/shared/centauri-lease -ha-id b -ha-addr http://b.internal:7771 -token secret
curl http://a.internal:7771/v1/ha

Replication: follow, sync, merge#

centauri follow -primary <url> keeps a live read-only replica by polling GET /v1/log and ingesting raw bytes, so the follower's hash chain is byte-identical to the primary's; add -addr to serve a read-only API from it. centauri sync -primary <peer> is bidirectional, record-level and echo-safe: it pulls the peer's /v1/changes from a per-peer replication slot, ingests facts it doesn't hold (dedup by event id), and advances the slot — run it on both ends. Multi-master on the same subject converges because "current" is a deterministic function of the facts. merge produces one canonical re-chained log offline.

centauri follow -data replica.log -primary https://db.example.com -token secret -addr :7772
centauri sync -data laptop.log -primary http://desktop:7771 -token secret   # and the mirror on the peer
centauri merge -to merged.log a.log b.log && centauri verify -data merged.log

CDC, replication slots and WATCH#

Change data capture is GET /v1/changes?from=<cursor> (internal/store/cdc.go): it returns events, a cursor (byte offset) and caught_up; resume from the cursor and you never miss or duplicate a fact. Durable replication slots make this resumable server-side: ?slot=<name> resumes from the slot's confirmed position, POST /v1/changes/ack confirms progress, GET /v1/slots lists them; retention is gated by the minimum slot cursor so no consumer misses changes. /v1/watch is the push alternative (SSE; internal/store/watch.go); /v1/log is the raw byte feed replication uses.

curl 'localhost:7771/v1/changes?from=0'
curl 'localhost:7771/v1/changes?slot=warehouse'
curl -X POST localhost:7771/v1/changes/ack -H 'Authorization: Bearer <admin>' \
  -H 'content-type: application/json' -d '{"slot":"warehouse","cursor":1048576}'
curl 'localhost:7771/v1/slots'

Retention and legal holds#

centauri retention -pattern '<glob>' -older-than N (internal/retention) previews which subjects would be retired — dry-run by default; -apply RETIREs them by appending retired:true corrections so queries skip stale facts. History is kept, the chain stays intact, and the log does not shrink. A hold:<name> fact with a subject pattern places matching subjects under a legal hold that retention skips — and the engine enforces it: any RETIRE of a held subject is rejected on every originating write path (CeQL, raw append, sharded) until the hold is lifted; replication is exempt so replicas mirror the primary.

centauri retention -data gateway.log -pattern 'gw:*' -older-than 30          # dry-run plan
centauri retention -data gateway.log -pattern 'gw:*' -older-than 30 -apply   # RETIRE

PUT hold:litigation-2026 SET pattern='order:2025-*', active=true
RETIRE hold:litigation-2026                        -- lift the hold

Authentication: tokens, scoped tokens, field masking, OIDC#

serve gates every /v1/* route behind -token (admin, env CENTAURI_TOKEN) and -read-token (read-only, env CENTAURI_READ_TOKEN); dashboards, /v1/version, probes and /metrics stay open. Scoped tokens (POST /v1/acl) confine a principal to subject prefixes and can mask fields. Enterprise SSO: -oidc-issuer (plus -oidc-audience, -oidc-jwks, -oidc-write-scope) accepts bearer JWTs from any OIDC provider (Okta, Azure AD, Auth0, Keycloak, Google), verifying RS256/384/512 against the provider's JWKS (fetched over HTTPS, cached, refreshed on rotation) plus exp/nbf/iss/aud (internal/oidc). A valid token grants read; write requires the configured scope matched against scope/roles/groups.

centauri serve -data my.log -token admin-secret -read-token viewer-secret
centauri serve -data my.log -token admin-secret \
  -oidc-issuer https://login.example.com -oidc-audience centauri -oidc-write-scope centauri:write

curl -X POST localhost:7771/v1/acl -H 'Authorization: Bearer admin-secret' \
  -H 'content-type: application/json' \
  -d '{"token":"bot-secret","prefixes":["item:","sku:"],"write":true,"mask":["cost_cents"]}'

TLS, admission control, structured logs, probes#

-tls-cert/-tls-key terminate HTTPS natively on serve, desktop, -lazy-index and the gateway's proxy listener — no reverse proxy required (Caddy/nginx in front is fine; bind to localhost if so). Admission control: -max-concurrency (HTTP 429 over the cap), -query-timeout seconds (HTTP 503), -max-concurrency-per-db for a per-tenant cap; streaming endpoints and health/metrics are exempt. -log-format json -log-level info emits one slog line per request with method, path, status, bytes, duration and an X-Request-ID (honoured inbound, echoed back). /livez, /readyz and Prometheus /metrics exist on every serve mode and the gateway.

centauri serve -data my.log -tls-cert srv.pem -tls-key srv.key \
  -max-concurrency 64 -query-timeout 30 -max-concurrency-per-db 16 \
  -log-format json -log-level info
curl -s localhost:7771/metrics | head
curl localhost:7771/livez; curl localhost:7771/readyz

Named environments (multi-database)#

A server whose -data sits in a directory can host several named environments (<name>.log beside the default); clients pick one with ?db=<name> (SDKs: WithDatabase / { database } / Airbyte database). GET /v1/databases lists them; POST /v1/databases (admin) creates one; Genesis apply creates a fresh environment per blueprint. The Postgres wire listener has no ?db= routing — it serves the default database.

curl 'localhost:7771/v1/databases'
curl -X POST localhost:7771/v1/databases -H 'Authorization: Bearer <admin>' \
  -H 'content-type: application/json' -d '{"name":"bakery"}'
curl 'localhost:7771/v1/query?db=bakery&q=STATS'

The gateway: routes and keys as facts#

centauri gateway (internal/gateway, stdlib httputil) turns a Centauri log into a reverse proxy whose entire control plane — routes, API keys, request audit — lives in the database as facts. Config therefore time-travels (AS OF, AS KNOWN AT, HISTORY OF route:api) and the audit is hash-chained and verify-able. Data plane default :8080; -admin :7771 serves the normal dashboard/API over the same store; -admin-inline serves it on the proxy port for unmatched paths (single-port deploys). A route is the current fact of route:<name> facet config; a key is gwkey:<sha256> (the plaintext is printed once and never stored). Mint keys offline with -newkey <name> or live in the Console (/console → Keys & Access).

centauri gateway -data gateway.log -addr :8080 -admin :7771

PUT route:api FACET config SET prefix='/api/', upstream='http://127.0.0.1:9000', auth='key', rate_per_min=120, timeout_ms=10000, audit='meta'

centauri gateway -data gateway.log -newkey ci-bot          # key printed ONCE
curl -H 'Authorization: Bearer <the printed key>' http://localhost:8080/api/health

FACTS OF route:api FACET config AS OF 'last tuesday 9am'
FACTS OF route:api FACET config AS KNOWN AT '2026-08-01'
HISTORY OF route:api
RETIRE gwkey:<sha256> FACET config           -- revoke a key; history stays

Route field reference#

Maps and arrays (providers, add_request_headers, allow_ips…) must be written through POST /v1/append or an SDK, because CeQL SET takes scalars only. Parsing is fail-closed: an unknown auth value, a bad CIDR or glob, a broken webhook URL or a missing policy procedure rejects the whole route (its paths 404) — a typo can never mean "open".

Key fields: name, routes (prefixes it may call; empty = all), rate_per_min (per-key budget), retired. Middleware order per request: CORS → auth → rate limit → header add/remove → IP filters → body cap → path blocks → authorization webhook → CePL policy → proxy.

Gateway auth modes: key, OIDC, mTLS#

auth='key' requires a minted gateway key as a bearer token. auth='oidc' validates the caller's JWT with the same verifier serve uses, forwards X-Auth-Subject: <sub> (any client-supplied value of that header is stripped), and records the JWT sub as the audit key; the bearer passes through to the upstream unless you add "remove_request_headers": ["Authorization"]. -mtls-ca <pem> (mtls.go, with -tls-cert/-tls-key) requires every connection on the proxy listener to present a client certificate signed by that CA — requests without one die at the TLS handshake; the cert CN becomes the audit key when nothing else named the caller. Listener-wide, not per-route.

PUT route:api FACET config SET prefix='/api/', upstream='http://127.0.0.1:9000', auth='oidc', oidc_issuer='https://login.example.com', oidc_audience='my-api'

centauri gateway -data gateway.log -tls-cert srv.pem -tls-key srv.key -mtls-ca clients-ca.pem

Token issuer: POST /gw/token (client-credentials only)#

The gateway can issue short-lived service tokens so machine callers pass auth='oidc' routes without an external IdP (issuer.go). Every gateway key doubles as an OAuth2 client: client_id is the key's name, client_secret is the key. The token is an RS256 JWT with iss = -issuer, sub = key name, aud = -token-aud (default centauri), exp after -token-ttl seconds (default 900), signed by an RSA-2048 key generated on first use and stored as PEM next to the log (issuer.key, mode 0600) — never in the log, because the log can never erase it. The public half is served at /.well-known/jwks.json and /.well-known/openid-configuration. Every issuance and failure is audited on gw:_tokens. RETIRE gwkey:… stops new tokens immediately; issued ones live out their TTL.

curl -s http://localhost:8080/gw/token \
  -d grant_type=client_credentials \
  -d client_id=ci-bot \
  -d client_secret=<the minted key>
# → {"access_token":"eyJ…","token_type":"Bearer","expires_in":900}

PUT route:svc FACET config SET prefix='/svc/', upstream='http://127.0.0.1:9100', auth='oidc', oidc_issuer='http://localhost:8080', oidc_audience='centauri', oidc_jwks_url='http://localhost:8080/.well-known/jwks.json'

Rate limits, CePL request policies, webhook authorization#

Rate limiting (ratelimit.go) is per route (rate_per_min) and per key on top. For programmable logic a route names a stored CePL procedure in policy (policy.go); it runs after auth, rate limit and built-in middleware, immediately before proxying, receiving any subset of method, path, key (resolved caller name, or '' when anonymous) and ip. Its RETURN decides: 'allow'/true proceeds; 'deny'/'deny:<message>'/false is 403; a record is honoured as {"allow", "status", "message", "add_headers"}; anything else, a runtime error, or FAIL is 403 fail-closed. Policies are parsed once per config load and hot-reload when the procedure fact changes; denials are audited even on audit:'none' routes. Measured cost ≈2 µs per request. authz_webhook POSTs {method, path, key, ip, headers} (safe subset only, never the credential) to your service; anything but 2xx, or the 2-second timeout, is 403 fail-closed unless webhook_fail_open.

PUT route:api FACET config SET prefix='/api/', upstream='http://127.0.0.1:9000', auth='key', policy='office_rules'

PROCEDURE office_rules(method, path, key, ip)
  -- writes only from the ci key; reads for everyone
  WHEN method != 'GET' AND key != 'ci': RETURN 'deny:only ci may write here'
  RETURN 'allow'
END

PUT route:api FACET config SET prefix='/api/', upstream='http://127.0.0.1:9000', auth='key', authz_webhook='https://authz.internal/check'

LLM routing, streaming and token accounting#

Set llm: true and a providers list (llm.go); the gateway speaks the OpenAI-compatible chat-completions shape and fails over in order on unreachable or 5xx providers. Each provider entry pins the model — the gateway forces it into the forwarded request so callers can't choose an expensive model. Secrets never live in facts: auth_env names an env var, auth_file a key file; local servers like Ollama are keyless. When a provider reports usage, the audit fact records model, prompt_tokens, completion_tokens, so per-key token spend is a query. stream: true passes SSE through, flushed per chunk, with stream_options.include_usage injected so the trailing usage chunk lands token counts.

curl -s http://localhost:7771/v1/append -H 'Content-Type: application/json' -d '{
  "events": [{
    "subject": "route:chat", "facet": "config", "type": "OBSERVED",
    "value": {
      "prefix": "/v1/chat/", "llm": true, "auth": "key", "audit": "meta",
      "providers": [
        {"endpoint": "http://127.0.0.1:11434/v1/chat/completions", "model": "glm-4.7-flash"},
        {"endpoint": "https://api.openai.com/v1/chat/completions", "model": "gpt-5.5", "auth_env": "OPENAI_API_KEY"}
      ]
    }
  }]
}'

Audit, metrics, retention and scale-out#

With audit: "meta" each request appends a fact on subject gw:<route> facet gateway (audit.go) carrying method, path, status, ms, key (name, never the secret), upstream, bytes_out, and for LLM routes model and token counts — bodies are never recorded. FACTS OF gw:* is the latest request per route; HISTORY OF gw:<route> is the full log. /metrics is on the admin plane. Audit grows the log: retire old audit facts with centauri retention -pattern 'gw:*', or set audit: 'none' on hot routes. Scale-out: run N gateways with -control-follow https://primary:7771 -control-token …; each follows the primary's control log read-only and writes audit to its own local log (-audit-data).

HISTORY OF gw:chat FACET gateway ORDER BY recorded DESC LIMIT 100
HISTORY OF gw:chat WHERE status >= 500          -- every 5xx, forever
FACTS OF route:api FACET config AS OF 5 minutes ago

centauri gateway -data replica.log -addr :8080 -control-follow https://primary:7771 -control-token $PRIMARY_TOKEN
centauri verify -data gateway.log

Gateway flags: -data (default gateway.log), -addr (:8080), -admin, -admin-inline, -token, -read-token, -tls-cert, -tls-key, -mtls-ca, -control-follow, -control-token, -audit-data, -newkey, -issuer, -token-ttl (900), -token-aud (centauri).

Python SDK#

sdk/python is zero-dependency, Python 3.8+. Centauri.launch() finds the binary, starts a server (optionally on a given data= log) and connects; Centauri(url=…, token=…) connects to a running one. Insert and update are the same call (db.add). Errors say what happened and what to do next (CentauriConnectionError, CentauriAPIError with .status/.message). db.api.get/post/stream reaches any endpoint the SDK hasn't wrapped. Use a with block and the launched server stops automatically.

cd sdk/python
pip install -e .

from centauri import Centauri

db = Centauri.launch()                        # finds & starts the server for you
db.add("toy:robot", {"price_cents": 500})     # save your first fact
print(db.get("toy:robot"))                    # read it back

db.at("toy:robot", "2026-06-01", known="2026-05-01")  # what we BELIEVED on May 1
ctx = db.context("toy:robot")
db.pump("prices.csv")                                 # needs a 'subject' column
db.define_schema("price", {"price_cents": {"type": "number", "required": True, "min": 1}})
db.add("toy:car", {"price_cents": 300}, schema="price")
db.run("duty_estimate", item="100001", units=3)

Python — the five examples#

sdk/python/examples/ holds five runnable scripts, each under a minute (and TUTORIAL.md walks through them). All use Centauri.launch(data="tutorial.log") except 04, which connects to the already-running server.

# 01_hello_centauri.py — start, save, update, read current and history
db = Centauri.launch(data="tutorial.log")
db.add("toy:robot", {"price_cents": 500, "color": "silver"})
db.add("toy:robot", {"price_cents": 450, "color": "silver"})  # update — old kept!
print("Current:", [e.value for e in db.get("toy:robot")])
print("History:", [e.value for e in db.history("toy:robot")])
db.stop()

# 02_time_travel.py — back-dated write, then at() and double time travel
db.add("toy:rocket", {"price_cents": 900}, effective=yesterday)
db.add("toy:rocket", {"price_cents": 700})  # effective now
db.at("toy:rocket", yesterday)
db.at("toy:rocket", now, known=yesterday)   # as known then

# 03_pump_csv.py — bulk-load a CSV with a 'subject' column
csv_file.write_text("subject,price_cents,kind\ntoy:car,300,REGULAR\ntoy:boat,550,REGULAR\ntoy:kite,120,SALE\n")
count = db.pump(csv_file)
print(f"Pumped {count} facts!")

# 04_watch_live.py — SSE watch loop; run 01 or 03 in another terminal
db = Centauri()  # connect to the already-running server
for event in db.watch():
    print(f"  NEW: {event.subject}  {event.value}  (facet={event.facet})")

# 05_ai_context.py — schema, validated write, enrichment, embedding, context bundle
version = db.define_schema("price", {
    "price_cents": {"type": "number", "required": True, "min": 1, "unit": "cents"},
    "kind": {"type": "string"},
})
e = db.add("toy:drone", {"price_cents": 2500, "kind": "REGULAR"}, schema="price")
db.enrich(e.event_id, "demand_forecast", {"next_30d": "high"}, model_id="forecaster", confidence=0.85)
db.embed(e.event_id, [0.12, 0.98, 0.33], model_id="my-embedder")
ctx = db.context("toy:drone")
print(ctx.enrichments, ctx.confidence_min, ctx.confidence_mean)

Go SDK#

sdk/go is a thin zero-dependency client (stdlib net/http + encoding/json) with the same surface as Python: Add, Get, History, At(subject, atMicros, knownMicros), Context, Query (any CeQL), DefineProcedure, Run, and Changes(cursor). Options: WithToken, WithDatabase, WithHTTPClient.

import centauri "github.com/aniljacobv-lab/centauri/sdk/go"

c := centauri.New("http://localhost:7771", centauri.WithToken("secret"))
c.Add("toy:robot", map[string]any{"price_cents": 500})
facts, _  := c.Get("toy:robot")
hist, _   := c.History("toy:robot")
past, _   := c.At("toy:robot", atMicros, knownMicros)
bundle, _ := c.Context("toy:robot")
res, _    := c.Query("FACTS OF item:* WHERE region='EU' WHY")

c.DefineProcedure(`PROCEDURE reprice(item, pct)
  LET cur = FIRST FACTS OF ${item}
  WHEN cur IS MISSING: FAIL 'unknown ${item}'
  LET newp = cur.price_cents * pct / 100
  PUT ${item} SET price_cents=${newp}
  RETURN newp
END`)
c.Run("reprice", map[string]any{"item": "toy:robot", "pct": 90})
evs, cursor, caughtUp, _ := c.Changes(0)

JavaScript / TypeScript ESM SDK#

sdk/js/centauri.mjs is a zero-dependency fetch-based ESM client for Node 18+ and the browser. Methods: add, append(events), get, history, at(subject, at, known), context, stats, subjects, query(ceql), defineProcedure(source), run(name, args), changes(from). Options { token, database }. Inside a JS template literal the CePL ${…} holes must be escaped as \${…}.

import { Centauri } from "@centauri/client"; // or "./centauri.mjs"

const db = new Centauri("http://localhost:7771", { token: "secret" });
await db.add("toy:robot", { price_cents: 500 });
const facts  = await db.get("toy:robot");
const hist   = await db.history("toy:robot");
const bundle = await db.context("toy:robot");
const res    = await db.query("FACTS OF item:* WHERE region='EU' WHY");

await db.defineProcedure(`PROCEDURE reprice(item, pct)
  LET cur = FIRST FACTS OF \${item}
  WHEN cur IS MISSING: FAIL 'unknown \${item}'
  LET newp = cur.price_cents * pct / 100
  PUT \${item} SET price_cents=\${newp}
  RETURN newp
END`);
await db.run("reprice", { item: "toy:robot", pct: 90 });
const { events, cursor, caught_up } = await db.changes(0);

CDC streams from the SDKs#

All three SDKs wrap GET /v1/changes as changes(cursor) returning the events, the byte-offset cursor to resume from, and a caught-up flag; Python additionally wraps /v1/watch as a generator. Persist the cursor — or use a server-side slot with POST /v1/changes/ack — and you get exactly-once-per-fact delivery across restarts. This is the same mechanism centauri sync and the Airbyte source ride.

# Python: resumable polling with the escape hatch
page = db.api.get("/v1/changes", **{"from": cursor})
for ev in page["events"]: ...
cursor = page["cursor"]

Airbyte destination — land anything into Centauri#

connectors/airbyte/destination_centauri is a standalone pure-stdlib Python program speaking the Airbyte Protocol over stdin/stdout — no Airbyte CDK, nothing linked into the binary. Each Airbyte RECORD becomes one fact via POST /v1/append: subject <stream>:<key> (the primary_key field if configured, else a per-stream counter), facet from config, type OBSERVED, value = the full record. STATE messages are acknowledged only after the preceding records are durably appended, which is what makes resumable syncs safe. Commands: spec, check, write.

printf '%s\n' \
  '{"type":"RECORD","record":{"stream":"users","data":{"id":7,"name":"Alice"}}}' \
  '{"type":"STATE","state":{"data":{"cursor":1}}}' \
| python3 destination_centauri/main.py write --config dest-config.json --catalog catalog.json

Airbyte source — stream Centauri facts out#

connectors/airbyte/source_centauri exposes one stream, facts. read pages GET /v1/changes?from=<cursor>, emits one RECORD per event, and emits the byte-offset cursor as Airbyte STATE, so the next sync resumes exactly. Sync modes: full_refresh and incremental (source_defined_cursor: true). Each record's data is the full event: event_id, subject, facet, type, value, effective_time, recorded_time, provenance, confidence. Config: centauri_url (required), token, database. Commands: spec, check, discover, read.

python3 source_centauri/main.py read \
    --config src-config.json --catalog configured-catalog.json [--state state.json]

# register as custom Docker connectors in the Airbyte UI
docker build -t airbyte/destination-centauri:dev destination_centauri/
docker build -t airbyte/source-centauri:dev      source_centauri/

Production checklist#

The dashboard ships inside the binary, so going to production is running the binary somewhere public with HTTPS in front. From docs/deploy.md:

• Always set -token (and ideally -read-token) — without one, anyone with the URL owns your data.
• Terminate TLS natively (-tls-cert/-tls-key) or behind Caddy/nginx bound to localhost.
• Take periodic centauri backup snapshots off the box and record the chain head somewhere separate — tamper evidence needs an external anchor.
• Set -max-concurrency, -query-timeout and -max-concurrency-per-db; scrape /metrics; probe /livez and /readyz; emit -log-format json.

# Recipe 1 — systemd unit on a ~$5 VPS, Caddy in front
ExecStart=/usr/local/bin/centauri serve -data /var/lib/centauri/centauri.log -addr 127.0.0.1:7771 -token CHANGE_ME -read-token CHANGE_ME_TOO

# Caddyfile
db.example.com {
    reverse_proxy 127.0.0.1:7771
}

# Recipe 2 — Fly.io via the Dockerfile
fly launch --no-deploy
fly volumes create centauri_data --size 1
fly secrets set CENTAURI_TOKEN=CHANGE_ME
fly deploy

Kubernetes#

infra/k8s.yaml deploys Centauri on Kubernetes as a normal workload (it is not an ingress controller — no IngressClass, Gateway API or CRDs). It defines a Secret centauri-token, a centauri-db Service on 7771 and a StatefulSet with replicas: 1 and a 1Gi volumeClaimTemplate — the store is single-writer, so never raise replicas; run read replicas with centauri follow. The gateway is a Deployment (replicas: 1, strategy Recreate) with its own PVC, a LoadBalancer on 80 → 8080, args gateway -data /data/gateway.log -addr :8080 -admin-inline, and probes on /livez and /readyz. Build and push your own image first; no public image is assumed. Scale gateways horizontally with -control-follow.

docker build -t <your-registry>/centauri:latest . && docker push <your-registry>/centauri:latest
kubectl create secret generic centauri-token --from-literal=token=$(openssl rand -hex 32)
kubectl apply -f infra/k8s.yaml

livenessProbe:  { httpGet: { path: /livez,  port: 8080 } }
readinessProbe: { httpGet: { path: /readyz, port: 8080 } }

Render blueprint#

render.yaml is a Render Blueprint (Deploy to Render) that creates two Docker web services on the starter plan: centauri (health check /, 1 GB disk at /data, CENTAURI_TOKEN auto-generated) and centauri-gateway (health check /livez, gateway -data /data/gateway.log -addr :7771 -admin-inline, its own disk and token). Render exposes one port per service, which is why the gateway runs -admin-inline: proxied routes win and any unmatched path serves the token-gated admin dashboard. Mint keys in the Console, since the writer lock blocks -newkey while running.

-- the demo flow, from the query bar
PUT route:api FACET config SET prefix='/api/', upstream='https://your-backend', auth='none', rate_per_min=60
HISTORY OF gw:api FACET gateway
FACTS OF route:api FACET config AS OF 5 minutes ago

Observability endpoints#

Every serve mode exposes the same three unauthenticated endpoints: /livez, /readyz and Prometheus /metrics (process + API counters, store counters and build info on normal serve; segment-cache gauges on lazy; centauri_objstore_* with an object store; never fact data). GET /v1/version is the deploy stamp. Structured request logs carry X-Request-ID. GET /v1/integrity exposes the live chain state, and /v1/verify (lazy mode) recomputes Merkle roots and the chain online with no downtime.

curl -s localhost:7771/livez
curl -s localhost:7771/readyz
curl -s localhost:7771/metrics | grep -i centauri_ | head
curl -s localhost:7771/v1/version

Releases and what's in them#

Pushing a version tag runs .github/workflows/release.yml, which builds six static binaries, the Windows installer, and a checksum file, then publishes a GitHub Release. Asset names are stable, so /releases/latest/download/<asset> always points at the newest release. Every component — engine, dashboards, Studio, Console, App, CeQL Book, gateway, MCP server, local-AI orchestration — is inside the one binary; there is nothing else to download.

https://github.com/aniljacobv-lab/centauri/releases/latest/download/
  centauri-linux-amd64            centauri-linux-arm64
  centauri-darwin-amd64           centauri-darwin-arm64     # Intel / Apple Silicon
  centauri-windows-amd64.exe      centauri-windows-arm64.exe
  centauri-windows-setup.exe      # Inno Setup installer (Start Menu, launchers)
  SHA256SUMS.txt                  # verify any download

curl -LO https://github.com/aniljacobv-lab/centauri/releases/latest/download/centauri-linux-amd64
curl -LO https://github.com/aniljacobv-lab/centauri/releases/latest/download/SHA256SUMS.txt
sha256sum -c --ignore-missing SHA256SUMS.txt

SDKs and connectors are source in the repository (sdk/python via pip install -e ., sdk/go as a Go module path, sdk/js/centauri.mjs as an ESM file, connectors/airbyte as Docker builds). Publishing the Python SDK to PyPI is on the roadmap; nothing is published to PyPI or npm today.

CI: tests, AI code review, performance gate#

Every pull request runs ci.yml (go vet, go test ./..., the Python SDK tests) and claude-review.yml, an automatic code review by Claude on non-draft PRs. perf.yml benchmarks the PR's base and head and compares them with benchstat, warning on possible regressions; it also runs weekly on main as a drift check. sync.yml keeps the two canonical→copy pairs identical on every push (internal/api/ceql.html → docs/ceql.html; docs/kb.json → internal/assistant/kb.json), so the embedded textbook and the assistant's knowledge never drift from the website.

# the same gate, locally
go vet ./... && go test ./...
cd sdk/python && python -m unittest discover -s tests
go test -bench . -benchmem ./internal/store/

The Dream cycle — AI-maintained development#

Three nights a week (dream.yml, Mon/Wed/Fri 06:00 UTC, or on demand from the Actions tab), Claude reviews the codebase, picks one item from ROADMAP.md top-to-bottom — or one real bug it finds — implements it with tests, and opens a pull request. CI gates it and a human merges, always: auto-merge is explicitly out of scope. Humans steer what gets built by editing the roadmap. Items are kept small enough for one PR, and the roadmap lists what is deliberately never dreamed about: multi-writer clustering, third-party Go dependencies, and rewrites of working subsystems without a human-filed issue.

ROADMAP.md
  ## Now (v0.4)            # prioritized, picked top to bottom
  ## Next
  ## Always welcome        # dream-sized: NL rules, catalog entries, Genesis packs, tests
  ## Explicitly out of scope

Performance: methodology, not marketing numbers#

Centauri ships a reproducible benchmark suite rather than baking numbers into the docs — run it on your own hardware and data shape. Core-path benchmarks (internal/store/core_bench_test.go) cover Append, Current and AsOf; the lazy/archive suite (lazyindex_bench_test.go) isolates each win in pairs: HistoryCold vs HistoryCached (segment-cache), AsOfCold vs AsOfCached (zone-map pruning), SearchCold vs SearchResident, and OpenCold vs OpenFromCheckpoint (fast restart). bench/baseline.txt holds a committed baseline (from deploy.bat) that the Perf workflow compares against; the gateway's own BenchmarkPolicyOverhead measures the per-request cost of a CePL policy.

go test -bench . -benchmem ./internal/store/
go test -bench Policy -benchmem ./internal/gateway/

# bench/baseline.txt — one developer machine (windows/arm64), for drift detection only
BenchmarkAppend-12      ~19–36 µs/op    46 allocs/op
BenchmarkCurrent-12     ~0.4–0.8 µs/op   4 allocs/op
BenchmarkAsOf-12        ~0.5–0.75 µs/op  4 allocs/op

Roadmap#

From ROADMAP.md, as of this page. Now (v0.4): encryption at rest + crypto-erasure end to end (the segment-level AES-256-GCM primitive and legal holds are shipped; per-subject keys for the live log are open); an HNSW/ANN index for SIMILAR beyond brute-force cosine; cross-subject joins in CeQL (FACTS OF a:* JOIN b:* ON …, nested-loop first); a CePL step-debugger in the dashboard; Windows/macOS code-signing docs. Next: referential field types in schemas (parent ref(item:*)); the rest of the governance pack (named roles, PII classification tags, scheduled data-quality checks); derived facts (DERIVE summary:<x> AS FACTS … GROUP BY …, incrementally maintained); window frames; spatial fields; stemming for MATCHES; PyPI publishing for the Python SDK.

Shipped since the list was first written (kept for honesty): sharded writes, group commit, tablespaces + S3 offload + auto-seal, the lazy index, CDC with slots, HA failover, log shipping, read-only SQL + Postgres wire, retention + legal holds, scoped tokens + masking, OIDC, admission control, backup/verify, the local-AI appliance, and the gateway.

Contributing: the invariants#

CLAUDE.md is the guide for every contributor, human or AI. Five invariants; violating one is a rejected PR:

1. Nothing is ever erased. No code path may mutate or delete committed log bytes. Update = append a superseding fact; delete = RETIRE.
2. Replay determinism. Every replay-visible state change goes through store.apply(); new index state must also be checkpointed and reset.
3. Write-then-apply. Memory changes only after bytes are durably written; events before their supersession markers.
4. The hash chain covers every committed line identically in commit, replay and raw ingest.
5. Zero Go dependencies. The empty require block in go.mod is a feature.

A new CeQL capability is complete only with parser + executor + tests, a section in the CeQL Book, an entry in the autocomplete catalog (its examples must parse — the catalog test enforces this), and, if user-facing, a dashboard surface: features without one don't exist for users. Documentation honesty is policy — comparison tables state what Centauri does not do. Ideas go to issues (bug and feature templates); accepted features get implemented.

go vet ./... && go test ./...
cd sdk/python && python -m unittest discover -s tests
# then open a PR — Claude reviews it, the Perf gate runs, a human merges

Design documents, positioning and license#

The docs/ folder keeps the reasoning, not just the result. Design notes: own-your-data storage (your data never lives on our infrastructure), vision, tablespaces, segmentation & Merkle proofs, sync, object-store backend. Status matrices: enterprise readiness (the live ✓/partial/✗ table), plus dated review snapshots (audit-updated-capabilities.md, enterprise-deployment-gaps.md, production-suggestions.md, product-positioning-audit.md). Messaging: positioning.md is the source of truth for how Centauri is described, and db-engines-submission.md is the DB-Engines listing request.

License: the MIT License — OSI-approved, permissive, free for any use including commercial, no copyleft. Copyright JacobLabs LLC and contributors. There is no paid edition: the binary you download is everything. Related pages on this site: how it works, internals vs Oracle, gateway comparison, showcase.