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.