Configuration Reference

All configuration lives in a single TOML file. Default location: ~/.denkeeper/denkeeper.toml.

Top-level keys

[telegram]

[discord]

[llm]

[[llm.providers]]

Named provider instances. Multiple entries of the same type are allowed, enabling e.g. OpenAI + a local LM Studio endpoint simultaneously. Each instance is addressable by its unique name.

[[llm.providers]]
name = "openai"
type = "openai"
api_key = "sk-..."

[[llm.providers]]
name = "lmstudio"
type = "openai"
base_url = "http://localhost:1234/v1"
api_key = "lm-studio"

[[llm.providers]]
name = "anthropic"
type = "anthropic"
api_key = "sk-ant-..."
cost_limit_hard = 5.0

[llm.providers.model_prices."claude-opus-4-1"]
input = 15.0
output = 75.0
cached_input = 1.5

Legacy single-slot syntax ([llm.openai], [llm.anthropic], etc.) is still supported and auto-converted at startup. The two styles can coexist; an explicit [[llm.providers]] entry with the same name takes precedence.

[llm.openrouter] (legacy)

[llm.openrouter.reasoning]

Controls the reasoning parameter sent to OpenRouter.

[llm.anthropic] (legacy)

[llm.ollama] (legacy)

[llm.openai] (legacy)

Compatible with any endpoint that speaks the OpenAI Chat Completions API format.

[[llm.fallback]]

cost_limit rules consume the agent’s cost_limit_soft / cost_limit_hard (resolved via [[agents]] overrides or the global [llm] defaults). Legacy low_funds rules with a threshold field auto-migrate to cost_limit + scope = "soft" on load.

[[llm.deciders]]

Named decision models: non-generative classifiers such as typesafe/jev-1.13 that answer typed questions with probabilities instead of text. A decider cannot chat, so it is never selectable as an agent model.

Spend is taken from the provider-reported cost and counts against the calling session’s cost limits. Everything sent to a decider (tool arguments, conversation excerpts) goes to that provider’s upstream, an additional data processor.

[session]

Note that approval_timeout is the engine’s wait, distinct from the 24-hour TTL after which an unresolved approval request is expired and cleaned up.

[agent]

Defaults for agents that do not set their own directories.

[[agents]]

Supervisor

Decider spend is billed to the reviewed agent, per conversation. A decider failure (timeout, cost limit, input too large) is audited and never approves anything. See Decision Models for how to move from shadow to enforce.

A config reload applies supervisor and the five supervisor_* knobs above to running agents: adding, changing, or removing a supervisor takes effect for the next tool call, and removing a knob restores its default. Renaming an agent through the API or dashboard also updates other agents’ supervisor and any [[channels]] agent that named it.

A config reload applies every decider change: adding, removing or switching supervisor_decider, changing a decider’s provider or model, and mode and thresholds. A review already in progress finishes with the old decider. PATCH /api/v1/agents/{name} and the dashboard apply at once, without a reload.

Post-turn reviewer

A headless per-agent engine that reviews after a turn and can append persona memory or report skill improvements. Distinct from the supervisor above — it reviews after the fact rather than gating tool calls, and is capability-reduced rather than approval-gated.

[[channels]]

Named routing endpoints that decouple sessions from a 1:1 agent–adapter binding. A channel points at one agent and may bind several adapters, which lets one conversation be shared across them. When no [[channels]] are declared, Denkeeper synthesizes them from each agent’s adapters list.

Users switch channels at runtime with /session <name>; the selection is persisted. Resolution priority is: active /session override > specific binding > wildcard binding > legacy agent-adapter fallback.

[memory]

[log]

[voice]

[voice.openai]

[web]

Built-in web_search and web_fetch tools. Restart-only — [web] settings are not hot-reloaded.

[web.search]

[web.fetch]

[web.fetch.jina]

[script]

Bounds for the in-process run_javascript tool, which runs short ES5.1 snippets against a JSON input in a fresh sandboxed VM per call. There is no network, no filesystem, and no require. Disabled entirely in the restricted tier.

[decide]

Gives every agent an in-process decide tool that puts typed questions about a JSON state to a decision model and returns probabilities. Off until a decider is named.

The tool is classified read-only, so it is available in the restricted tier and in dry runs, and identical calls within one turn are served from cache. Spend is billed to the calling agent under a per-day session key and counts against its cost limits. The state an agent passes goes to the decider’s provider. Changes to the named decider apply on reload; turning [decide] on or off, or naming another decider, needs a restart, like [script].

[skills]

Skill content is written verbatim, so without a bound an authorized caller could exhaust disk. The cap is enforced on every write surface (REST, config MCP, external MCP).

[browser]

Containerized browser automation. Off by default.

[browser.url_allowlist]

Individual agents can narrow this further with browser_url_allowlist on [[agents]].

[costs]

Denkeeper ships a pricing registry covering roughly 70 models. Lookup priority is: provider-reported cost > registry exact match > registry longest-prefix match > default_rate_per_1k_tokens > $0 with a warning. The winning source is recorded as the pricing_source telemetry attribute, so you can tell a real price from a fallback.

[costs.model_prices.<model>]

Override or add pricing for a model. Rates are USD per million tokens.

[costs.model_prices."my-org/custom-model"]
input = 3.0
output = 15.0
cached_input = 0.3

[audit]

Events are queryable via GET /api/v1/audit and the dashboard’s Audit Log page.

[eval]

win_threshold and the three gate_* keys are the decision rule, and it is deliberately asymmetric: the three gates can declare a downgrade on their own (a failed gate needs no judge to reject a candidate) or report that nothing regressed, but calling a candidate an upgrade also requires the judge win-rate to reach win_threshold. A judge’s preference can never override an objective regression. GET /api/v1/eval/runs/{id}/summary returns the gate table with each value, delta, threshold and pass/fail alongside a one-line reason, plus a per-category breakdown so a candidate that wins on chat while regressing on tool-heavy tasks is visible rather than averaged away.

An eval run is bounded twice, by spend (max_cost_per_run) and by rate (max_concurrent); both are always in force. Writing 0 for any of these keys is indistinguishable from omitting it and yields the default — set a real value to change one. A run that hits its cost cap stops dispatching new samples, lets the in-flight ones finish, and keeps its partial results rather than discarding them.

Setting judge_model turns on the internal judge: POST /api/v1/eval/runs/{id}/judge works the same pending queue server-side, so a run can be judged unattended instead of only from Claude Code over MCP. It is capability-reduced by construction — one completion per item with no tool definitions in the request, reading only the same blinded payload eval_get_pair returns — so it can no more unblind its own queue than the MCP judge can. Its verdicts are ordinary verdicts under judge_ident judge_model, stamped with the rubric version, and they feed the same win rate. Judging spend is capped by judge_max_cost_per_run and recorded on the run as judge_cost, kept apart from the sample spend in cost_spent because the two are separate budgets. judge_model, judge_provider and judge_max_cost_per_run are re-read on config reload, so turning the judge on or moving its cap takes effect on the next pass; max_concurrent bounds judging process-wide and is fixed at start-up. Judging spend is attributed to the pseudo-agent {agent}#eval:judge, so it never lands in a real agent’s totals.

Setting judge_decider puts a decision model in front of the judge model. Each item is first put to the decider as five a/b/tie choice questions, the overall call plus one per rubric dimension, in one call. When the winning option’s probability reaches judge_decider_record_at the verdict is recorded under judge_ident judge_decider; otherwise, and on an oversized item, a timeout or an error, the item goes to judge_model when set, or stays pending for the MCP judge. judge_decider works alone too. judge_decider, judge_decider_record_at and judge_decider_timeout all apply on reload.

capture, max_trace_bytes and retention_days are the turn-trace knobs. A trace records what a turn actually saw: the system prompt as it was assembled after skill injection, the history window as it went on the wire, every tool call with its arguments and the result the model read, the final response, timings and usage. The dashboard’s Turn inspector renders them, which is what answers “why did it do that” — the audit log carries rounds and outcomes but never the payloads.

Live capture is off by default and should stay off unless you want that record: a trace is the most sensitive data Denkeeper stores. Eval samples are traced regardless of the switch, because the judge reads the trace and a verdict has to stay re-checkable; those turns never touch a live conversation. Traces get their own retention_days rather than riding on [memory]’s for the same reason.

Dry-run turns persist nothing — no messages, telemetry, or memory — and execute only idempotent tools; everything else returns a suppressed marker. "full" is the default because a preview that is audited like a live turn is easier to trust; the resulting noise is handled by marking rather than by recording less. Preview events are attributed to a pseudo-agent ({name}#dryrun / {name}#eval:{variant}) and carry source = dryrun/eval, so the Audit Log page’s “Previews” toggle can filter them out of both the event list and the statistics.

[api]

[[api.keys]]

Static API keys, in addition to any created at runtime via the Keys CLI, the keys REST endpoints, or first-run setup. All keys — static and runtime — are stored and checked the same way.

[[api.keys]]
name = "ci"
key = "dk_..."
scopes = ["chat", "sessions:read"]

Valid scopes: admin, chat, health, sessions:read, sessions:write, costs:read, agents:read, agents:write, skills:read, skills:write, schedules:read, schedules:write, approvals:read, approvals:write, tools:read, tools:write, browser:read, browser:write, kv:read, kv:write, audit:read, channels:read, channels:write, eval:read, eval:write. admin implies every other scope.

[api.mcp_server]

Exposes this Denkeeper instance as an MCP server, so an external MCP client (another agent, an IDE) can drive its agents, skills, schedules, and audit log. Opt-in.

Note the direction: [tools.*] is Denkeeper connecting outward to MCP servers; this section is Denkeeper being one.

[[schedules]]

[plugins.*]

Subprocess plugins run as child processes with direct MCP stdio. Docker plugins run in hardened containers with --cap-drop ALL, --read-only, --security-opt no-new-privileges, and --network none by default.

[security]

When allow_unsigned = false, all subprocess plugin binaries must have a valid Ed25519 signature from one of the trusted keys.

[safety.reply_guard]

Runtime guardrail that holds back an obviously broken final reply on schedule-driven turns — a live user reacts to a bad reply, a schedule fires unattended. Distinct from [security], which covers plugin signing. The turn is still stored in full and an audit event lands under category safety, action reply_guard; what changes is the delivered text, replaced by a one-line notice. Dry runs and evals evaluate the guard and report the verdict on the transcript, but never substitute the text.

Each signal takes "withhold", "warn" (audit but deliver anyway), or "off".

[kv]

Per-agent key-value storage with optional TTL. Exposed as Config MCP tools (kv_get, kv_set, kv_delete, kv_list, kv_set_nx). Useful for locks, counters, caches, and cross-session coordination.

list_max_bytes and list_value_head_bytes are sized for model context, not disk: a kv_list over a busy namespace can otherwise return tens of thousands of tokens in one tool result. Keys are always returned in full; values are what gets dropped once the budget is spent. Both must be positive, and list_value_head_bytes must not exceed list_max_bytes.

[sandbox]

Selects the runtime backend for sandboxed (Docker-type) plugins.

[sandbox.kubernetes]

The Kubernetes backend creates ephemeral Pods with init-container network isolation, dropped capabilities, read-only root filesystem, and Pod Security Admission labels. Supports both in-cluster (ServiceAccount) and out-of-cluster (kubeconfig) authentication.

[mcp]

Global settings that apply to all MCP tool servers.

Removing, disabling, restarting or reconfiguring a tool server tears it down in two phases. The server stops being offered immediately — its tools leave the advertised set and new calls are refused — and only then does Denkeeper wait for the calls already running to finish, up to drain_timeout, before closing the transport. The server reports status draining while it waits. A window that expires forces the close and records a forced_close event in the audit log with the number of calls that were still running. The default sits just above the 30s per-tool-call timeout, so a call that was going to succeed gets to.

[tools.*]

SSE security: SSRF protection blocks localhost, link-local (169.254.x.x), and cloud metadata endpoints. ${NAME} placeholders in url and headers are resolved from environment but secrets matching DENKEEPER_*_SECRET, DENKEEPER_*_PASSWORD*, and related patterns are denied. URL and header values are redacted in API responses.

Tools can also be added and removed at runtime via the REST API (tools:write scope) or the Config MCP server (tool_add/tool_remove). Runtime changes are persisted to the TOML config file.

[otel]

Env overrides: DENKEEPER_OTEL_ENABLED sets enabled, DENKEEPER_OTEL_TRACES_ENDPOINT sets traces_endpoint.

When enabled, Prometheus metrics are exposed at GET /metrics (no auth required). Traces are only exported when traces_endpoint is set.

[api.auth]

Env override: DENKEEPER_API_AUTH_SESSION_SECRET sets session_secret.

[api.auth.oidc]

Env overrides: DENKEEPER_OIDC_CLIENT_ID sets client_id, DENKEEPER_OIDC_CLIENT_SECRET sets client_secret.

Requires email_verified: true claim from the OIDC provider. Uses Authorization Code flow with PKCE (S256).