Section 00 / Docs 000
Daemon Config Reference
Complete reference for local.toml — the kaged daemon's operator-local configuration.
local.toml lives at ~/.config/kaged/local.toml (or $KAGED_CONFIG_DIR/local.toml). It stores operator preferences, provider credentials, model aliases, plugin state, and project registry.
All sections are optional. The daemon starts with sensible defaults when local.toml is absent or empty.
Provider credentials live under [providers.<name>.credentials]. Prefer credentials.*.env to reference environment variables rather than storing secrets directly in local.toml.
Section / Local Config (top-level) local-config
Local Config (top-level)
Top-level keys in local.toml — the daemon's operator-local configuration.
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
operator_name |
string |
no | — | Operator display name. |
ui |
object |
no | — | UI preferences. See §ui. |
aliases |
Record<string, string> |
no | — | Model alias → provider:model mappings (e.g. sonnet → claude:sonnet-4). |
providers |
Record<string, object> |
no | — | LLM provider configurations keyed by name. See §provider. |
plugins |
Record<string, object> |
no | — | Installed plugin entries keyed by name. See §plugin_entry. |
system_plugins |
Record<string, object> |
no | — | System plugin entries keyed by name. See §system_plugin_entry. |
projects |
object[] |
no | — | Registered project entries. See §project_entry. |
audit |
object |
no | — | Audit logging options. See §audit. |
default_tools |
Record<string, object | null> |
no | — | |
langfuse |
object |
no | — | Optional Langfuse tracing configuration. See §langfuse. |
logging |
object |
no | — | |
notifications |
object |
no | — | |
secrets |
Record<string, Record<string, string>> |
no | — | |
mcp |
Record<string, object> |
no | — | |
web |
unknown |
no | — |
Section / UI Preferences ui
UI Preferences
Frontend display settings. Uses .passthrough() — unknown keys are tolerated for forward-compat.
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
theme |
"dark" | "light" | "system" |
no | — | Color theme: "dark", "light", or "system". |
font_size |
"small" | "medium" | "large" | "x-large" |
no | — | |
timezone |
string |
no | — | IANA timezone string (e.g. America/Los_Angeles). |
locale |
string |
no | — | Locale string (e.g. en-US). |
interrupt_suffix |
string |
no | — | Suffix appended to interrupt messages. |
forward_prefix |
string |
no | — | Prefix prepended to forwarded messages. |
Section / Provider provider
Provider
An LLM provider entry under [providers.<name>]. Uses .passthrough() for driver-specific options.
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
catalog_id |
string |
no | — | Catalog ID linking the provider back to the bundled catalog snapshot. |
npm |
string |
yes | — |
AI SDK package name to dynamically load.
[min length: 1] |
name |
string |
no | — | |
base_url |
string |
no | — | Custom base URL for the provider API. |
credentials |
Record<string, object> |
no | — | Map of named credentials. Each entry has either a literal value or an env var name. |
header_mappings |
Record<string, string> |
no | — | |
discover_endpoint |
string |
no | — | |
default_options |
Record<string, unknown> |
no | — | Default request options passed to every call. |
models |
object[] |
no | — | Available models for this provider. See §model_entry. |
Section / Model Entry model_entry
Model Entry
A model available from a provider.
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
id |
string |
yes | — |
Model identifier (required).
[min length: 1] |
name |
string |
no | — | Human-readable display name. |
manual |
boolean |
no | — |
Section / Plugin Entry plugin_entry
Plugin Entry
A user-installed plugin under [plugins.<name>].
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
installed |
string |
yes | — | ISO timestamp of installation. |
local |
boolean |
yes | — | Whether this is a local (filesystem) plugin. |
projects |
string[] |
no | — | Project IDs this plugin is scoped to. Omit for all projects. |
source |
string |
no | — | Plugin source (registry URL or path). |
config |
Record<string, unknown> |
no | — | Deprecated — pre-ADR-0023 plugin configuration. Rename to system_config. |
system_config |
Record<string, unknown> |
no | — | Operator-local plugin configuration validated against the manifest's system_config_schema. |
Section / System Plugin Entry system_plugin_entry
System Plugin Entry
A system-wide plugin under [system_plugins.<name>].
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
enabled |
boolean |
yes | — | Whether this system plugin is active. |
path |
string |
no | — | Absolute path to plugin package. Defaults to ${KAGED_HOME}/system-plugins/<name>/. |
config |
Record<string, unknown> |
no | — | Arbitrary plugin configuration. |
Section / Project Entry project_entry
Project Entry
A registered project in the [[projects]] array.
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
id |
string |
yes | — |
Unique project identifier.
[min length: 1] |
path |
string |
yes | — |
Absolute filesystem path to the project root.
[min length: 1] |
last_opened_at |
integer |
no | — | Unix timestamp of last access. |
status |
"ready" | "pending" | "invalid" |
yes | — | Project state: "ready", "pending", or "invalid". |
label |
string |
no | — | Operator-set display name (shown in UI instead of id). |
nickname |
string |
no | — | Deprecated — superseded by label. |
accent_color |
string |
no | — | CSS color for project accent in the UI. |
interrupt_suffix |
string |
no | — | Per-project interrupt message suffix. |
forward_prefix |
string |
no | — | Per-project forward message prefix. |
Section / Audit audit
Audit
Audit logging toggles under [audit].
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
log_alias_use |
boolean |
no | — | Log when an alias is resolved. |
log_provider_use |
boolean |
no | — | Log when a provider is called. |
log_alias_edit |
boolean |
no | — | Log when an alias is created/edited/deleted. |
log_plugin_install |
boolean |
no | — | Log when a plugin is installed/removed. |
Section / Langfuse langfuse
Langfuse
Optional Langfuse tracing settings under [langfuse].
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
enabled |
boolean |
no | — | Enable Langfuse tracing. Defaults to on when credentials resolve. |
public_key |
string |
no | — | Langfuse public key stored directly in local.toml. |
secret_key |
string |
no | — | Langfuse secret key stored directly in local.toml. |
base_url |
url |
no | — | Langfuse base URL. Defaults to the hosted cloud endpoint. |
public_key_env |
string |
no | — | Environment variable name holding the Langfuse public key. |
secret_key_env |
string |
no | — | Environment variable name holding the Langfuse secret key. |