Configuration reference¶

Layers · sections · keys

Telha loads one TelhaConfig from four layers, lowest precedence first, and validates the merged result before serve binds a single port. This page walks every section; the exhaustive per-key table lives in Reference › Configuration keys.

How layering works¶

flowchart LR
    A[Built-in defaults<br/>TelhaConfig::default] --> B[TOML file<br/>--config or TELHA_CONFIG]
    B --> C["TELHA_* env vars<br/>__ nesting, whitelisted keys only"]
    C --> D[CLI flags<br/>whitelisted overrides]
    D --> E[Validated TelhaConfig]

1. Built-in defaults. Every field in TelhaConfig has a Default impl; an empty config is a complete, valid config.
2. TOML file. Pass --config <path> on any subcommand, or set TELHA_CONFIG (read by the CLI's RunArgs, not by the config loader itself). A path that does not exist is an error; an omitted --config simply skips this layer.
3. TELHA_* environment variables. Nested keys use a double underscore (__) as the separator, e.g. TELHA_REST__ADDR=0.0.0.0:7625 or TELHA_LLM__TENANT_CAPS__DAILY_TOKENS=2000000. Only a fixed whitelist of dotted keys is read (ENV_KEYS in config.rs) so unrelated TELHA_* variables, including TELHA_CONFIG itself, never leak into the figment.
4. CLI flags. A small set of fields can be overridden per-invocation: --data-dir, --rest-addr, --grpc-addr, --uds-path, --log-level, --log-format. These win over everything else and apply to serve, check-config, and every subcommand that takes RunArgs.

Validate the fully resolved configuration (file + env + flags, in that order) before starting the server for real:

telha check-config --config /etc/telha/telha.toml

check-config prints every non-fatal warning to stderr, then prints the resolved configuration as TOML to stdout, then exits 0. A structurally or semantically invalid configuration exits non-zero with the specific validation error (see each section below for what gets validated).

data_dir¶

The single top-level scalar. Directory holding RocksDB column families, vector partition files, api_keys.json, and the erasure ledger. Created on serve if missing; must not be empty.

[rest]¶

The REST/Axum listener. GET /healthz and GET /readyz are served unauthenticated from this listener.

Port 0 binds ephemerally. rest.addr and grpc.addr must differ unless both use port 0 (checked at load).

[grpc]¶

The gRPC/Tonic listener that carries the internal worker, MCP, clarify, admin, and connector token audiences. gRPC (and MCP, which shares its token key) stay disabled until token_key is set.

token_key is a 64-character hex string (32 bytes) used as an HMAC key for every internal service token. uds_path is Unix-only; setting it on Windows produces a startup warning and gRPC falls back to grpc.addr (TCP).

[log]¶

log.level is a tracing_subscriber::EnvFilter directive (e.g. info or telha_core=debug,info) and is validated as such at load; an invalid filter string is a fatal config error. log.format is json (structured, production) or pretty (human-readable, local dev).

[storage]¶

RocksDB tuning. No environment overrides are whitelisted for this section (TOML file only).

Turning sync_writes off trades crash-durability of the most recent write batch for throughput; leave it on unless you understand the tradeoff.

[global_scan]¶

Limits for the global temporal scan operator. No environment overrides are whitelisted (TOML file only).

[compare]¶

/v1/compare temporal-diff limits.

Beyond this ceiling a compare page returns partial-with-warning and a resume cursor.

[decay]¶

Confidence decay parameters (path-based decay across graph hops).

fusion_alpha balances similarity and decay in fused scoring: S = sim^α · decay^(1−α), with a per-query override available via vector.alpha. decay.weights is a per-edge-type override map, e.g. decay.weights.OWNS = 0.9; it is TOML-only because a map has no __-safe single env key. Paths whose decay falls below floor are pruned rather than expanded. All weights are validated at load; out-of-range values are a fatal config error, never silently clamped.

[bitmap]¶

Bitmap predicate acceleration for equality/range filters. Enabling on an existing dataset requires telha index rebuild-bitmaps first.

range_bands must equal 16; v1 supports no other value and any other value is a fatal config error. The bitmap path is chosen only when the candidate count is below watermark × candidate_ratio.

[jobs]¶

Job queue leasing and retry.

lease_ttl_secs and max_attempts must be positive; a dead job after max_attempts needs telha jobs retry to re-enter the queue. backoff_base_secs_by_kind is populated internally (for example clarify:temporal inherits the clarification escalation window) and is not an operator-facing env key.

[ingest]¶

Behaviour of the JSON direct ingestion path.

json_nested is flatten (nested objects become dotted property keys like address.city) or child (nested objects become child nodes linked by HAS_<KEY> edges); either can be overridden per-request via options.nested.

[embedding]¶

Activates when both endpoint and model are set. The API key is read from an environment variable named by api_key_env, never stored in the config file.

After setting endpoint and model in TOML, register the model with telha vector register-model before ingestion will fan text out to it. See Key & secret management for the embedding credential.

[vector]¶

Partitioned HNSW index tuning (no environment overrides whitelisted; TOML file only).

[mcp]¶

The integrated MCP server. The listener starts only when enabled is true and grpc.token_key is set, because MCP sessions authenticate with the same signed-token scheme as gRPC (audience mcp).

max_rows and max_field_chars must be positive when enabled is true. mcp.addr must differ from both rest.addr and grpc.addr (unless all use port 0). specs_resource exposes .ai/specs/**/*.md as the specs:// MCP resource; specs_dir resolves relative paths against the process working directory.

[planner]¶

The evidence planner: how much source material a generation request may draw on and how it is weighted.

Default kind_priors: paragraph = 1.0, heading = 0.6, cell = 0.8, code = 0.9. Kinds absent from the map take prior 1.0. The effective token budget is min(default_budget, floor(model_ctx × 0.5)) when the provider reports a context window. max_frac_per_source is a hard per-source diversity cap that is never relaxed; stranded budget shows up in response stats instead. Every ratio is validated at load and rejected outright on an out-of-range value, never silently clamped.

[llm]¶

Generation orchestration (/v1/generate). The subsystem activates only when provider is set; there is deliberately no credential field here (see Key & secret management).

provider is anthropic or openai_compat. When provider is set, validation requires: endpoint non-empty and passing egress validation (HTTPS, or plain HTTP only to a loopback host, localhost, 127.0.0.1, or ::1, so an Authorization header never crosses the network in the clear); model_default non-empty; max_output_tokens and timeout_s positive; and at least one of api_key_env / secrets_file naming a credential source. The effective model allowlist is models_allowed ∪ {model_default}; a request naming any other model is rejected with 400. Endpoint/provider/model configuration is operator-only. tenant_caps are default per-tenant token ceilings (input + output, 0 = unlimited); see the operator handbook's reservation-model section for how reservation and settlement work against these caps.

[verify]¶

Claim verification against planned evidence spans.

beta is the geometric fusion balance for claim/span matching (match = clamp01(cos)^β · lex^(1−β)); 0 and 1 are formula fast-paths, not valid config. Band overrides are bounded to ±0.1 of the shipped defaults, and supported must remain at least partial + 0.10 after overrides, so bands can never invert or collapse. decompose_model empty uses the generation model for claim decomposition; embed_model empty uses the request's semantic model (else embedding.model) so claims and spans are embedded under exactly one space.

[clarify]¶

The temporal clarification loop (human-in-the-loop resolution of conflicting or uncertain facts). Ships disabled.

escalation_window_hours and max_candidates must be positive. quorum.critical_required_confirmations must be positive. quorum.required_roles entries must parse as viewer|editor|steward; severity.elevate values must parse as low|normal|high|critical. Enabling clarify without grpc.token_key set is a non-fatal warning (from check-config): clarifications will still be created and routed, but no clarify-bot can poll or answer them until a token key exists. See the Clarify bot page for CLARIFY_BOT_CONFIG and delivery.

[backup]¶

The in-process backup ticker. The telha backup CLI works regardless of enabled. See Backup & restore for the full procedure.

backup.enabled requires backup.dir to be set and interval_hours to be positive, or the config fails to load. keep = 0 disables pruning. pg_database_url_env names (never contains) the environment variable holding the app-layer PostgreSQL connection string for the two-surface backup capture.

[retention]¶

The in-process retention ticker. Off by default; nothing expires without an explicit policy. See Retention & archival.

retention.enabled requires a resolvable archive target: either retention.archive_dir is set, or backup.dir is set for it to default under. interval_hours must be positive when enabled. max_entities_per_run must always be positive (bounds each run; the scan resumes on the next interval).

[watch]¶

Memory-watch subscriptions (webhook/event delivery on matching writes). The CLI and REST/MCP surfaces work regardless of enabled; the flag gates only the in-process evaluator ticker. No environment overrides are whitelisted for this section (TOML file only).

[erasure]¶

GDPR erasure attestation settings. Deliberately not about mechanism (the masking, ledger, dual-approval, and verification behaviour are doctrine, not knobs), these keys capture facts the completion report attests to. No environment overrides are whitelisted (TOML file only).

Validation summary¶

telha check-config runs every rule above in one pass and reports the first failure. Common failure classes:

Related¶

• Reference › Configuration keys, the exhaustive per-key table.
• Key & secret management, API keys, grpc.token_key, the field-encryption KEK, and LLM/embedding credentials.
• Backup & restore, [backup] in practice.
• Retention & archival, [retention] in practice.
• Troubleshooting, symptom-to-cause tables including the all-digit token key gotcha.
• Deployment runbook, install and first-boot config walkthrough.