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.