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"

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.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.

[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

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.

[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]

The last four 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.

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.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.

[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.

[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).