Cluster configuration reference

Cluster commands read a directory containing cluster.yaml:

omnigraph cluster validate --config ./company-brain

--config defaults to the current directory. Unknown fields and duplicate YAML keys are errors so that misspelled intent is never ignored.

Complete shape

version: 1

metadata:
  name: company-brain

# Omit for a cluster stored in this directory.
storage: s3://company-data/omnigraph/company-brain

state:
  backend: cluster
  lock: true

providers:
  embedding:
    default:
      kind: openai-compatible
      base_url: https://api.example.com/v1
      model: text-embedding-3-large
      api_key: ${EMBEDDING_API_KEY}

graphs:
  knowledge:
    schema: knowledge.pg
    queries: queries/
    embedding_provider: default
    external_blobs:
      allow:
        - base: s3://company-assets/knowledge/
          scope: server_safe

policies:
  graph-access:
    file: graph.policy.yaml
    applies_to: [knowledge]
  server-access:
    file: server.policy.yaml
    applies_to: [cluster]

Top-level fields

Credentials are process configuration and must not appear in cluster.yaml.

Graphs

Each graph requires a schema file:

graphs:
  knowledge:
    schema: knowledge.pg

Optional fields:

Query declarations support three forms:

# Every declaration in top-level *.gq files in a directory
queries: queries/

# Every declaration in these files or directories
queries: [people.gq, reports/]

# Explicit registry names
queries:
  find_experts:
    file: knowledge.gq

Unreadable files, parse errors, duplicate query names, and queries that do not type-check against the graph's desired schema fail validation.

Embedding providers

Provider kind may be openai-compatible, openai, gemini, or mock. Real providers require api_key: ${ENVIRONMENT_VARIABLE}; inline secrets are rejected. The environment variable is resolved when the server boots, not by cluster validate, plan, or apply. Vector dimensions remain part of the graph schema.

See Embeddings for provider behavior.

External Blob references

New external references are denied unless their normalized URI falls under an allowed base:

external_blobs:
  allow:
    - base: s3://company-assets/knowledge/
      scope: server_safe

server_safe permits the base for a served graph. embedded_only is for an embedded host and may permit a local file:// directory; it is not installed by the HTTP server or direct-store CLI. Bases must be absolute, non-overlapping, and free of credentials, query strings, fragments, and path traversal.

The allow-list controls which external objects an authorized writer may cause the process to inspect. Cedar policy separately decides who may write. See Blob values.

Policies

policies:
  graph-access:
    file: graph.policy.yaml
    applies_to: [knowledge, catalog]
  registry-access:
    file: server.policy.yaml
    applies_to: [cluster]

A bundle targets either graph IDs or the cluster server scope, never both. Only one bundle may bind a given graph or the cluster scope. See Authorization.

Storage

When storage is omitted, applied state and graph data live under the config directory. An s3:// or az:// value puts them under that object-storage root; the source bundle still stays in the operator's working tree.

Use the standard storage credential environment for the chosen backend. Azure is a qualification preview and requires the admission wrapper for every writer; see Deployment.

Command behavior

apply can create graphs, apply supported soft schema changes, publish query and policy resources, and execute approved graph deletion. It does not load graph data, start servers, or perform hard schema drops.

See Operating a cluster for the end-to-end workflow.