Deploy a cluster as code

1. Deploy a cluster from zero

Lay out a config directory:

company-brain/
├── cluster.yaml
├── people.pg            # schema for the "knowledge" graph
├── queries/             # stored queries — the .gq files ARE the declaration
│   └── people.gq
└── base.policy.yaml     # a Cedar policy bundle

# cluster.yaml
version: 1
# storage: s3://omnigraph-local/clusters/company-brain   # optional: put the
#   ledger, catalog, and graph data on object storage (default: this folder)
metadata:
  name: company-brain
graphs:
  knowledge:
    schema: people.pg
    queries: queries/            # every `query <name>` in queries/*.gq registers
policies:
  base:
    file: base.policy.yaml
    applies_to: [knowledge]      # graph-bound; use [cluster] for server-level

Bring it to life:

omnigraph cluster validate --config company-brain   # parse + typecheck everything
omnigraph cluster import   --config company-brain   # create the state ledger
omnigraph cluster plan     --config company-brain   # preview: what would apply do?
omnigraph cluster apply    --config company-brain   # converge

That single apply creates the graph (at the derived root company-brain/graphs/knowledge.omni), applies its schema, and publishes the query and policy into the content-addressed catalog (__cluster/resources/…). The output lists every change with its disposition; converged: true means there is nothing left to do — re-running apply is always safe and idempotent.

Load data through the normal graph plane (the control plane manages definitions, not rows):

omnigraph load --data seed.jsonl company-brain/graphs/knowledge.omni

Serve it:

OMNIGRAPH_SERVER_BEARER_TOKENS_JSON='{"act-reader":"s3cret"}' \
  omnigraph-server --cluster company-brain --bind 0.0.0.0:8080

--cluster accepts either a config directory (the storage root resolves through cluster.yaml's storage: key) or a storage-root URI directly (--cluster s3://bucket/prefix) — config-free serving: a serving box needs only the URI and credentials, no checkout of the config repo. The ledger and catalog on the bucket are the deployment artifact.

--cluster is an exclusive boot source: it cannot be combined with a graph URI or --config, and omnigraph.yaml is never read in this mode. Routing is always multi-graph:

curl -H 'authorization: Bearer s3cret' \
  -X POST http://localhost:8080/graphs/knowledge/queries/find_person \
  -H 'content-type: application/json' -d '{"params":{"name":"Ada"}}'

Bearer tokens and the bind address are deliberately not cluster facts — they are per-replica, set by flag or environment (server.md for the token sources).