EKOSdocs
Docs / Configuration Build

Configuration File

ekos.toml — every section, with defaults.

ekos.toml lives at the workspace root — or, for a project in the EKOS home, at ~/.ekos/data/<tenant>/<project>/ekos.toml, where [workspace] root names the source directory. Unknown keys are rejected, so typos surface immediately; ekos config validate checks syntax and [observe] mistakes, and ekos config schema --json prints every section and setting with its type, default and description.

[workspace]
root = "."
log-level = "info"          # trace | debug | info | warn | error
log-format = "pretty"       # "pretty" | "json"

[observe]
paths = ["."]               # what `ekos init` writes (the schema default is empty: the workspace root)
ignore-patterns = [".ekos", ".git", "target", "node_modules"]   # file or directory NAMES, not paths or globs
git-max-commits = 500       # newest commits read from git history

[recover.sql]
default-dialect = "generic"

[[recover.sql.dialect-rules]]
path-glob = "db/postgresql/**"
dialect = "postgres"

[llm]
provider = "ollama"         # "ollama" | "anthropic" | "openai" | "zen" (main)
model = "llama3:latest"

[security]
extra-excluded-globs = []

Sources: [[sources]]

A project of several repositories and directories names each input. They compile into one ledger, and every object records the source it came from. Empty means one unnamed source: the directories of [observe] paths.

[[sources]]
name = "api"                # [a-z0-9][a-z0-9_-]{0,62}; keys the source's objects
path = "/repos/payments-api"   # absolute, or relative to the workspace root
kind = "git"                # "dir" (default) | "git": history expected, a missing .git is reported

[[sources]]
name = "handbook"
path = "/srv/handbook"

Renaming a source gives its objects new ids, and a project compiled without names cannot gain them later. ekos source add|list|remove edits this table and keeps comments.

Databases: [[databases]]

Live databases whose catalog ekos build reads — read-only, once per build, with a write probe that must be refused. Their objects are marked origin: live and never merge with objects from files. ekos database add|list|test|remove edits this table.

[[databases]]
name = "erp-db"
kind = "oracle"             # default
connect = "localhost:51521/XEPDB1"   # Easy Connect host:port/service
user = "ekos_ro"
password-env = "EKOS_ORACLE_PASSWORD"   # the variable's NAME, never the password
owners = ["ADEMPIERE"]      # schemas, as the dictionary spells them
profile = "p0"              # p0 statistics (default) | p1 row counts | p2 one scan per table
dictionary = "idempiere"    # optional: AD_Table delete / change-log flags

[[databases]]
name = "shop"
kind = "postgres"
connect = "db.local:5432/shop"       # host[:port]/database
user = "shop_ro"
password-env = "SHOP_PW"
owners = ["public"]         # schemas

[[databases]]
name = "wh"
kind = "clickhouse"
connect = "https://ch.local:8443"    # http[s]://host[:port]
user = "ro"
password-env = "WH_PW"
owners = ["analytics"]      # ClickHouse databases
Kind connect owners Profile, dictionary Needs
oracle host:port/service schemas p0–p2, idempiere the oracle build feature, Oracle Instant Client
postgres host[:port]/database schemas refused (Oracle only) nothing
clickhouse http[s]://host[:port] databases refused (Oracle only) nothing

A profile never reads a value out of a text column; p2 measures null counts, number and date bounds and text lengths.

Checks and review

[xref]                      # the cross-reference integrity check
enabled = true              # false: commit writes no integrity index (ekos check refs still runs)
min-confidence = 0.0        # hide findings below this (0–1)
entry-points = ["api_*"]    # reachability roots beyond what analyzers record
# ignore-file = "xref-ignore.toml"   # relative to the state directory
[xref.severity]
UnresolvedReference = "warning"

[tickets]                
keys = ["IDEMPIERE"]        # exact tracker keys; empty = commits are not linked to tickets

[review.scope]              # table classes for the scope review, first match wins
replace-defaults = false    # true replaces the built-in T_*/I_*/*_Trl/*Log*/AD_* rules
[[review.scope.classes]]
pattern = "TMP_*"
class = "transient"

[conflicts]
enabled = true              # false: the last definition wins without a trace

[freshness]
enabled = true
content-hash = false        # true: a file whose time moved but bytes did not is not "changed"
ttl-seconds = 30            # how long the MCP server reuses one check

[semantics]                 # business semantics → LinkML, opt-in
enabled = false
min-sites = 2               # statements a filter must recur in to become a concept
max-enum-values = 12
rationale = true            # git blame the evidence lines
llm-definitions = false     # opt-in cite-or-drop text from [llm]

[docs-estate]               # ekos docs generate --layout estate
licences = { handbook = "CC-BY-4.0", "erp-db" = "none" }
# max-er-tables = 30

All sections

Section Purpose Page
[workspace], [observe], [[sources]] root, logging, what to observe this page
[[databases]] live Oracle, PostgreSQL, ClickHouse catalogs (main) this page, Indexing a Database
[recover.sql] SQL dialect and per-path dialect rules Indexing a Database
[llm], [ai] provider for compilation passes and for ekos ask LLM Providers
[embeddings], [retrieval] vector index, LLM rerank Embeddings
[llm-description], [document-semantics], [architecture-reasoning], [binary-reconstruction] opt-in LLM stages Advanced Configuration
[xref], [tickets], [review], [docs-estate] integrity check, ticket links, review scope, estate docs (main) this page
[conflicts], [freshness] where sources disagree, is the ledger behind (on by default) this page
[semantics] business semantics → LinkML Business Semantics
[session-memory] agent session memory Agent Session Memory
[migrate] EKOS Migrate, PostgreSQL → ClickHouse Migrating a Database
[security] extra redaction patterns and excluded globs Security Model
[storage] containers, partitioning, distributed Storage
[extensions.<name>] settings of an extension such as EKOS Lakehouse; core keeps them and never reads them (main) Building a Lakehouse
[clickhouse], [architecture], [marketing] connector- and feature-specific Configuration Reference

Comments inside ekos.toml are ignored, so use them liberally — the repository's own ekos.toml records why each exclusion exists.