config.md

Cluster configuration reference

Source: https://www.omnigraph.dev/docs/clusters/config

--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

--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

# 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

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:

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

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 serving process resolves the environment variable at boot and during live deployment preflight for affected graphs. cluster validate, plan, and direct apply do not resolve it. 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.

A base must also name storage outside the selected cluster root. That root holds every graph and the applied state, and ingress reads with the process's own storage credentials, so a base over it would let any writer copy another graph's data or the cluster ledger into a readable Blob value. Plan and apply refuse such a base with external_blob_base_overlaps_storage_root, whatever its scope. Offline validation checks overlap when storage declares a root; otherwise the destination check waits for plan/apply. Put external objects under a sibling prefix instead, for example s3://company-assets/cluster-external/ beside storage: s3://company-assets/cluster. A server that finds an overlapping server_safe base in the applied state quarantines that graph and serves the others; if no applied graph is left to serve, startup fails with cluster_no_healthy_graphs. An embedded handle refuses a policy whose base overlaps its own graph root.

A base is compared only with a storage root of its own kind: an s3:// base with an s3:// root, a file:// base with a local root. When the root is spelled with a path component a base URI cannot express (an empty component such as s3://bucket/a//cluster, or a percent sign in a local path), a same-kind base is refused with external_blob_storage_root_uncomparable, because disjointness cannot be proven. Moving the base does not clear that code; the storage root spelling does.

The allow-list controls which external objects an authorized writer may cause the process to inspect: a new external Blob reference, and the source of a load csv statement, which the engine reads in full once (CSV loading). 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

Plan and apply always use the selected direct-root or server target. Omitting storage makes the bundle portable between explicitly selected destinations. If present, storage is an equality assertion: a mismatch refuses before effects. Remote operations require an absolute path or file://, s3:// or az:// URI and read only source files from the caller's filesystem.

Registered direct targets accept local files only. The storage assertion above describes the deployment root; it does not select a target. An inline s3:// root reaches only the commands listed in S3 cluster roots. Cloud storage credentials and provider settings belong to the server or embedded initializer. Azure remains a qualification preview and requires its admission wrapper for every writer; see Deployment.

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: a .. segment is refused with config_path_escape, and a path that reaches its file through a symbolic link, on the way to it or as a query file discovered inside a declared directory, is refused with config_path_symlink. Each diagnostic names the setting that declared the path. The bundle is one directory of files read exactly as declared, so what gets applied never depends on something outside it.

An absolute path is accepted as given and is not checked for either shape. Prefer relative paths; they are what keep a bundle portable and hermetic.

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

All execution uses ledger v2 and requires state.lock: true. A server target submits apply to its existing writer and activates without restart. Direct apply owns exclusive admission and requires an explicit handoff before serving. Retained graph roots and storage formats stay fixed. Policy/provider/Blob bindings can change; removing a graph declaration deletes its managed storage and history. See deployment boundaries. Apply does not load rows or start servers. Root-addressed status, reconciliation and conversion do not use cluster.yaml; see the deployment workflow.

Limits

Configuration loading refuses limits before schema effects. Shared files with identical bytes count once toward the aggregate source limit.

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

Deployment admission checks the actual encoded prepared intents and reserves ledger/result space to record completion before accepting schema effects. JSON escaping and prepared state can make a deployment exceed its encoded limit even when raw source bytes fit. Result history may evict older completed records to admit a new deployment; outstanding authority is retained. These bounds do not cap graph data, native manifest-history scans or total process memory.

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

Operator targets

The operator file declares destinations separately from this source bundle. See Operator targets for the format, provider settings, credentials, administration and migration.