Cluster configuration reference | Omnigraph

Cluster configuration reference

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

Configuration Commands

--config DIR reads desired configuration from a directory containing cluster.yaml. --target NAME|ADDRESS separately selects the backend for plan, apply and observation. Validation needs only source files:

omnigraph cluster validate --config ./company-brain

Complete shape

version: 1

metadata:
  name: company-brain

# Optional assertion: must match the selected target for plan/apply.
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

Field Required Meaning
version yes Configuration schema; currently 1
metadata.name no Display name
storage no Optional root assertion; must match the selected target for direct or server plan/apply
state.backend no Omit or set to cluster
state.lock no Exclusive writer admission; omit or set to true; false refuses execution
providers.embedding no Named embedding provider profiles
graphs no Graph declarations keyed by graph ID
policies no Policy bundles keyed by bundle name

Graphs

Each graph requires a schema file:

graphs:
  knowledge:
    schema: knowledge.pg

Optional fields:

Field Meaning
queries Stored-query files, directories, or explicit name mappings
embedding_provider Name under providers.embedding
external_blobs Allow-list for new external Blob references

Embedding providers

Provider kind may be openai-compatible, openai, gemini, or mock. Real providers require api_key: ${ENVIRONMENT_VARIABLE}; inline secrets are rejected. The serving process resolves the environment variable at boot and during live deployment preflight for affected graphs.

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

Policies

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

Storage

Plan and apply always use the selected direct-root or server target. Omitting storage makes the bundle portable between explicitly selected destinations.

Declared paths

Every schema, queries, and policy file path is resolved against the directory that holds cluster.yaml. A relative path must stay inside that directory.

Command behavior

Command Changes graph or cluster state? Use
validate no Parse and type-check the declaration
plan no Preview desired differences; unsupported deployment effects still refuse
apply yes Converge graph inventory, schemas, queries, policies and provider/Blob settings
status no Read recorded deployment and lock status; server status also observes activation
observe no Report current observations without changing authority
force-unlock yes Remove one proven-stale lock by exact ID
upgrade-ledger state only Convert a stopped legacy ledger without resetting graph data

Limits

Resource Limit
Each cluster.yaml, schema, query or policy source 1 MiB
Distinct source bytes in one captured bundle 8 MiB
Declared resources (each graph and schema count separately) 4096
Query discovery paths plus directory entries, including ignored files 4096
Encoded immutable deployment bundle 16 MiB
Encoded cluster ledger 16 MiB
Lock metadata read 64 KiB
Outstanding deployments 1
Retained deployment results 32 records, 4 MiB total, 1 MiB each
Deployment actor / resource address / canonical root 256 / 512 / 4096 UTF-8 bytes

Operator targets

The operator file declares destinations separately from this source bundle.