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.

Secrets (api_key) should use api_key_env to reference environment variables rather than storing keys directly.

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

# 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".
`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.

# Provider

An LLM provider entry under [providers.<name>]. Uses .passthrough() for driver-specific options.

Field	Type	Required	Default	Description
`driver`	`string`	no	—	API driver name from @kaged/llm. Falls back to provider key if omitted.
`api_key_env`	`string`	no	—	Environment variable name holding the API key.
`api_key`	`string`	no	—	Direct API key (prefer api_key_env for security).
`base_url`	`url`	no	—	Custom base URL for the provider API.
`default_options`	`Record<string, unknown>`	no	—	Default request options passed to every call.
`models`	`object[]`	no	—	Available models for this provider. See §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.

# 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	—	Arbitrary plugin configuration.

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

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

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