Config schema reference

Full reference for talond.yaml. All top-level sections are optional — defaults apply when omitted. Validated at startup using Zod; the daemon refuses to start with an invalid config.

Root fields

Field	Type	Default	Description
`logLevel`	`trace \| debug \| info \| warn \| error \| fatal`	`info`	Pino log level
`dataDir`	string	`data`	Root directory for runtime data (DB, IPC sockets, artifacts)
`backgroundProvider`	string	—	Default provider for background agents (overrides `backgroundAgent.defaultProvider`)
`backgroundModel`	string	—	Default model for background agents
`executionEnv`	object	—	Execution environment configuration (see below)

storage

Field	Type	Default	Description
`type`	`sqlite`	`sqlite`	Database backend
`path`	string	`data/talond.sqlite`	SQLite file path (relative to cwd)

personas[]

Field	Type	Default	Description
`name`	string	required	Unique persona identifier
`model`	string	`claude-sonnet-4-6`	Model ID passed to the provider
`provider`	string	—	Override the default agent runner provider
`systemPromptFile`	string	—	Path to system prompt Markdown file
`skills`	string[]	`[]`	Skill names to attach
`subagents`	string[]	`[]`	Sub-agent names the persona can invoke
`capabilities.allow`	string[]	`[]`	Granted capability labels
`capabilities.requireApproval`	string[]	`[]`	Capability labels requiring user confirmation
`mounts`	mount[]	`[]`	Filesystem mounts for sandboxed execution
`queryTimeoutMinutes`	integer 1–480	`10`	Max minutes the agent runner waits for a single query to complete. Increase for personas running long Codex tasks or deep research
`maxConcurrent`	integer ≥ 1	—	Max parallel agent runs for this persona

mounts[]

Field	Type	Default	Description
`source`	string	required	Host path
`target`	string	required	Mount target path
`mode`	`ro \| rw`	`ro`	Mount mode

channels[]

Field	Type	Default	Description
`name`	string	required	Unique channel identifier
`type`	enum	required	`telegram`, `slack`, `discord`, `whatsappBaileys`, `email`, `terminal`
`enabled`	boolean	`true`	Enable/disable at startup
`showToolCalls`	boolean	`false`	Send tool-call status messages to the channel
`tokenRef`	string	—	Optional token reference
`config`	object	`{}`	Connector-specific config (see Channels guide)

bindings[]

Field	Type	Default	Description
`persona`	string	required	Persona name
`channel`	string	required	Channel name
`isDefault`	boolean	`false`	Mark as default binding for this channel

queue

Field	Type	Default	Description
`maxAttempts`	integer ≥ 1	`3`	Max delivery attempts before dead-letter
`backoffBaseMs`	integer	`1000`	Initial retry delay in ms
`backoffMaxMs`	integer	`60000`	Maximum retry delay in ms
`concurrencyLimit`	integer ≥ 1	`5`	Max simultaneous message processing

agentRunner

Field	Type	Default	Description
`defaultProvider`	string	`claude-code`	Default provider name
`providers`	record	see below	Provider configurations

agentRunner.providers.<name>

Field	Type	Default	Description
`enabled`	boolean	`false`	Enable this provider
`command`	string	required	CLI command (e.g. `claude`)
`contextWindowTokens`	integer	`200000`	Context window size
`options`	object	—	Provider-specific options
`contextManagement.enabled`	boolean	`false`	Enable session rotation
`contextManagement.triggerMetric`	string	—	Required when enabled. `input_tokens`, `cache_read_input_tokens`, `cache_creation_input_tokens`, or `cache_total_input_tokens`
`contextManagement.thresholdRatio`	float 0–1	—	Required when enabled. Fraction of `contextWindowTokens` that triggers rotation
`contextManagement.recentMessageCount`	integer	`10`	Verbatim messages to include after rotation
`contextManagement.summarizer`	string	—	Required when enabled. Sub-agent name for history compression (`session-summarizer` or `session-observer`)
`contextManagement.reflectionThresholdChars`	integer	`12000`	Character threshold for observational memory reflection

Default provider config:

agentRunner:
  defaultProvider: claude-code
  providers:
    claude-code:
      enabled: true
      command: claude
      contextWindowTokens: 200000
      contextManagement:
        enabled: true
        triggerMetric: cache_read_input_tokens
        thresholdRatio: 0.5
        recentMessageCount: 10
        summarizer: session-summarizer
    openai-compatible:
      enabled: false
      command: node
      contextWindowTokens: 256000
      contextManagement:
        enabled: true
        triggerMetric: input_tokens
        thresholdRatio: 0.75
        recentMessageCount: 10
        summarizer: session-observer
      options:
        baseUrl: ${OLLAMA_BASE_URL}
        defaultModel: glm-5.1
        providerId: ollama

backgroundAgent

Field	Type	Default	Description
`enabled`	boolean	`true`	Enable background workers globally
`maxConcurrent`	integer 1–10	`3`	Max simultaneous workers
`defaultTimeoutMinutes`	integer 15–480	`30`	Default wall-clock timeout
`defaultProvider`	string	`claude-code`	Provider for workers
`providers`	record	see below	Provider configs (same structure as agentRunner, no contextManagement)
`claudePath`	string	—	Explicit path to Claude Code binary

subagents

Field	Type	Default	Description
`enabled`	boolean	`true`	Enable sub-agent invocation globally
`profiles`	object[]	`[]`	Sub-agent profile definitions
`profiles[].name`	string	required	Unique profile identifier
`profiles[].description`	string	—	Human-readable purpose
`profiles[].model`	string	—	Model ID for this sub-agent
`profiles[].provider`	string	—	Provider name for this sub-agent

subagents:
  enabled: true
  profiles:
    - name: spark-coder
      description: Fast code generation
      model: gpt-5.4-spark
      provider: openai

auth

Field	Type	Default	Description
`mode`	`subscription \| api_key`	`subscription`	Authentication mode
`apiKey`	string	—	API key for `api_key` mode
`providers.<name>.apiKey`	string	—	Per-provider API key
`providers.<name>.baseURL`	string	—	Per-provider base URL (for Ollama, proxies)

For openai-compatible, Talon resolves credentials from auth.providers.<options.providerId> first and falls back to auth.providers.openai-compatible.

scheduler

Field	Type	Default	Description
`tickIntervalMs`	integer ≥ 1000	`5000`	Scheduler tick interval in ms

ipc

Field	Type	Default	Description
`pollIntervalMs`	integer ≥ 100	`500`	IPC poll interval in ms
`daemonSocketDir`	string	`data/ipc/daemon`	Unix socket directory

a2a

Field	Type	Default	Description
`maxConcurrentPersonaTasks`	integer	`3`	Max parallel A2A tasks per persona
`defaultTimeoutMs`	integer	`300000`	Default A2A task timeout in ms
`maxHistoryEntries`	integer	`50`	Max history entries kept per A2A task

a2a:
  maxConcurrentPersonaTasks: 3
  defaultTimeoutMs: 300000
  maxHistoryEntries: 50

sandbox

Controls agent execution sandboxing (Docker or Apple Container).

Field	Type	Default	Description
`runtime`	`docker \| apple-container`	`docker`	Container runtime
`image`	string	`talon-sandbox:latest`	Sandbox container image
`maxConcurrent`	integer ≥ 1	`3`	Max concurrent sandboxed agent processes
`networkDefault`	`off \| on`	`off`	Default network access for sandboxed agents
`idleTimeoutMs`	integer	`1800000`	Idle container timeout (30 min)
`hardTimeoutMs`	integer	`3600000`	Hard container timeout (60 min)
`resourceLimits.memoryMb`	integer	`1024`	Memory limit per container in MB
`resourceLimits.cpus`	float	`1`	CPU limit per container
`resourceLimits.pidsLimit`	integer	`256`	PID limit per container

sprites

Field	Type	Default	Description
`enabled`	boolean	`false`	Enable Sprite execution environments
`defaultImage`	string	—	Default container image for sprites
`registry`	string	—	Container registry base URL

sprites:
  enabled: false
  defaultImage: talon-sprite:latest
  registry: ghcr.io/ivo-toby

executionEnv

Field	Type	Default	Description
`enabled`	boolean	`false`	Enable isolated execution environments
`defaultProfile`	string	—	Default profile name
`profiles`	record	`{}`	Named execution profiles

executionEnv:
  enabled: true
  defaultProfile: docker
  profiles:
    docker:
      image: talon-sandbox:latest
      resourceLimits:
        memoryMb: 1024
        cpus: 1

langfuse

Field	Type	Default	Description
`enabled`	boolean	`false`	Enable Langfuse tracing
`publicKey`	string	—	Required when enabled
`secretKey`	string	—	Required when enabled
`host`	string	`https://cloud.langfuse.com`	Langfuse instance URL
`exportMode`	`batched \| immediate`	`batched`	Export strategy
`flushAt`	integer ≥ 1	`20`	Batch size before flush
`flushIntervalSeconds`	integer ≥ 1	`5`	Max seconds between flushes

governance

Runtime guardrails: spending caps, rate limiting, and loop detection. All sub-sections are optional. Omit the block to disable.

governance.spending

Field	Type	Default	Description
`daily_token_cap`	integer > 0	—	Max tokens per persona per 24h rolling window
`hourly_token_cap`	integer > 0	—	Max tokens per persona per 1h rolling window
`warn_at_percent`	number 1–100	`80`	Log a warning when usage exceeds this percentage
`per_persona`	record	—	Per-persona cap overrides (keys are persona names)
`per_persona.<name>.daily_token_cap`	integer > 0	—	Persona-specific daily cap
`per_persona.<name>.hourly_token_cap`	integer > 0	—	Persona-specific hourly cap

governance.rate_limits

Field	Type	Default	Description
`inbound_per_minute`	integer > 0	`30`	Max inbound messages per channel per minute
`inbound_per_user_per_minute`	integer > 0	`10`	Max inbound messages per sender per minute
`api_calls_per_minute`	integer > 0	`60`	Reserved for future API rate limiting

governance.loop_detection

Field	Type	Default	Description
`max_turns_per_run`	integer > 0	`50`	Hard turn limit per agent run
`duplicate_call_threshold`	integer > 0	`5`	Consecutive identical tool calls before blocking
`max_queue_depth_per_thread`	integer > 0	`100`	Max queued messages per thread before rejecting