LibreFang Configuration Reference

Complete reference for config.toml, covering every configurable field in the LibreFang Agent OS.

Overview
Config Include Mechanism
Minimal Configuration
Full Example
Section Reference
- Top-Level Fields
- [default_model]
- [memory]
- [network]
- [web]
- [media]
- [links]
- [channels]
- [[mcp_servers]]
- [a2a]
- [[fallback_providers]]
- [[users]]
- Channel Overrides
- [browser]
- [reload]
- [exec_policy]
- [approval]
- [budget]
- [thinking]
- [tts]
- [docker]
- [canvas]
- [auto_reply]
- [broadcast]
- [inbox]
- [[bindings]]
- [pairing]
- [extensions]
- [vault]
- [webhook_triggers]
- [proxy]
- [[sidecar_channels]]
- [session]
- [queue]
- [external_auth]
- [vertex_ai]
- [oauth]
- [auth_profiles]
- [tool_policy]
- [proactive_memory]
- [context_engine]
- [audit]
- [health_check]
- [plugins]
Environment Variables
Validation

Overview

LibreFang reads its configuration from a single TOML file:

~/.librefang/config.toml

On Windows, ~ resolves to C:\Users\<username>. If the home directory cannot be determined, the system temp directory is used as a fallback.

Key behaviors:

Every struct in the configuration uses #[serde(default)], which means all fields are optional. Omitted fields receive their documented default values.
Channel sections ([channels.telegram], [channels.discord], etc.) are Option<T> -- when absent, the channel adapter is disabled. Including the section header (even empty) enables the adapter with defaults.
Secrets are never stored in config.toml directly. Instead, fields like api_key_env and bot_token_env hold the name of an environment variable that contains the actual secret. This prevents accidental exposure in version control.
Sensitive fields (api_key, shared_secret) are automatically redacted in debug output and logs.

LibreFang supports splitting configuration across multiple files using the include field. This enables modular configs (e.g., separate files for channels, MCP servers, or environment-specific overrides).

# ~/.librefang/config.toml
include = ["channels.toml", "mcp.toml", "overrides/prod.toml"]

Rules:

Paths are relative to the directory containing the root config file.
Absolute paths are rejected with an error at startup.
.. path traversal components are rejected for security.
Maximum include nesting depth: 10 levels.
Include files are deep-merged before the root config. Root config values always override values from included files.
Include files can themselves contain include arrays (subject to the depth limit).

This mechanism is useful for keeping secrets in a separate file with stricter filesystem permissions, or for sharing a base config across multiple environments.

Minimal Configuration

The simplest working configuration only needs an LLM provider API key set as an environment variable. With no config file at all, LibreFang boots with Anthropic as the default provider:

# ~/.librefang/config.toml
# Minimal: just override the model if you want something other than defaults.
# Set ANTHROPIC_API_KEY in your environment.

[default_model]
provider = "anthropic"
model = "claude-sonnet-4-20250514"
api_key_env = "ANTHROPIC_API_KEY"

Or to use a local Ollama instance with no API key:

[default_model]
provider = "ollama"
model = "llama3.2:latest"
base_url = "http://localhost:11434"
api_key_env = ""

Full Example

# ============================================================
# LibreFang Agent OS -- Complete Configuration Reference
# ============================================================

# --- Top-level fields ---
home_dir = "~/.librefang"             # LibreFang home directory
data_dir = "~/.librefang/data"        # SQLite databases and data files
log_level = "info"                    # trace | debug | info | warn | error
api_listen = "127.0.0.1:4545"        # HTTP/WS API bind address
network_enabled = false               # Enable OFP peer-to-peer network
api_key = ""                          # API Bearer token (empty = unauthenticated)
dashboard_user = ""                   # Dashboard login username (empty = no login required)
dashboard_pass = ""                   # Dashboard login password (supports vault:KEY syntax)
mode = "default"                      # stable | default | dev
language = "en"                       # Locale for CLI/messages
usage_footer = "full"                 # off | tokens | cost | full
prompt_caching = true                 # Enable LLM prompt caching
stable_prefix_mode = false            # Reduce prompt cache invalidation
max_cron_jobs = 500                   # Global max cron jobs
cors_origin = []                      # CORS allowed origins
include = []                          # Config file includes

[provider_urls]
# ollama = "http://192.168.1.100:11434/v1"

[provider_api_keys]
# nvidia = "NVIDIA_API_KEY"

[provider_regions]
# qwen = "intl"        # Use Qwen international endpoint (dashscope-intl)
# minimax = "china"    # Use MiniMax China endpoint (MINIMAX_CN_API_KEY)

# --- Default LLM Provider ---
[default_model]
provider = "anthropic"
model = "claude-sonnet-4-20250514"
api_key_env = "ANTHROPIC_API_KEY"
# base_url = "https://api.anthropic.com"  # Optional override

# --- Fallback Providers ---
[[fallback_providers]]
provider = "ollama"
model = "llama3.2:latest"
api_key_env = ""
# base_url = "http://localhost:11434"  # Uses catalog default if omitted

[[fallback_providers]]
provider = "groq"
model = "llama-3.3-70b-versatile"
api_key_env = "GROQ_API_KEY"

# --- Memory ---
[memory]
# sqlite_path = "~/.librefang/data/librefang.db"  # Auto-resolved if omitted
embedding_model = "all-MiniLM-L6-v2"
consolidation_threshold = 10000
decay_rate = 0.1

# --- Network (OFP Wire Protocol) ---
[network]
listen_addresses = ["/ip4/0.0.0.0/tcp/0"]
bootstrap_peers = []
mdns_enabled = true
max_peers = 50
shared_secret = ""                    # Required when network_enabled = true

# --- Web Tools ---
[web]
search_provider = "auto"              # auto | brave | tavily | perplexity | duckduckgo
cache_ttl_minutes = 15

[web.brave]
api_key_env = "BRAVE_API_KEY"
max_results = 5
country = ""
search_lang = ""
freshness = ""

[web.tavily]
api_key_env = "TAVILY_API_KEY"
search_depth = "basic"                # basic | advanced
max_results = 5
include_answer = true

[web.perplexity]
api_key_env = "PERPLEXITY_API_KEY"
model = "sonar"

[web.fetch]
max_chars = 50000
max_response_bytes = 10485760         # 10 MB
timeout_secs = 30
readability = true

# --- Media Understanding ---
[media]
image_description = true
audio_transcription = true
video_description = false
max_concurrency = 2
# image_provider = "openai"
# audio_provider = "openai"

# --- Link Understanding ---
[links]
enabled = false
max_links = 3
max_content_bytes = 102400
timeout_secs = 10

# --- MCP Servers ---
[[mcp_servers]]
name = "filesystem"
timeout_secs = 30
env = []
[mcp_servers.transport]
type = "stdio"
command = "npx"
args = ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]

[[mcp_servers]]
name = "remote-tools"
timeout_secs = 60
env = ["REMOTE_API_KEY"]
[mcp_servers.transport]
type = "sse"
url = "https://mcp.example.com/events"

[[mcp_servers]]
name = "my-http-backend"
timeout_secs = 30
[mcp_servers.transport]
type = "http_compat"
base_url = "https://tools.example.com"
headers = [{name = "Authorization", value_env = "MY_API_KEY"}]
[[mcp_servers.transport.tools]]
name = "search"
description = "Search documents"
path = "/search"
method = "post"

# --- A2A Protocol ---
[a2a]
enabled = false
name = "LibreFang Agent OS"
description = ""
listen_path = "/a2a"

[[a2a.external_agents]]
name = "research-agent"
url = "https://agent.example.com/.well-known/agent.json"

# --- RBAC Users ---
[[users]]
name = "Alice"
role = "owner"                        # owner | admin | user | viewer
api_key_hash = ""
[users.channel_bindings]
telegram = "123456"
discord = "987654321"

[[users]]
name = "Bob"
role = "user"
[users.channel_bindings]
slack = "U0123ABCDEF"

# --- Channel Adapters ---
# (See "Channels" section below for all 44 adapters)

[channels.telegram]
bot_token_env = "TELEGRAM_BOT_TOKEN"
allowed_users = []
# default_agent = "assistant"
poll_interval_secs = 1

[channels.discord]
bot_token_env = "DISCORD_BOT_TOKEN"
allowed_guilds = []
intents = 37376

[channels.slack]
app_token_env = "SLACK_APP_TOKEN"
bot_token_env = "SLACK_BOT_TOKEN"
allowed_channels = []

# [channels.qq]
# app_id = "your-app-id"
# app_secret_env = "QQ_BOT_APP_SECRET"

# [channels.wecom]
# corp_id = "your-corp-id"
# agent_id = "your-agent-id"
# secret_env = "WECOM_SECRET"
# webhook_port = 8454

# [channels.wechat]
# bot_token_env = "WECHAT_BOT_TOKEN"   # optional: skip QR login on restart
# default_agent = "assistant"
# allowed_users = []

# --- Browser Automation ---
[browser]
headless = true
viewport_width = 1280
viewport_height = 720
timeout_secs = 30
idle_timeout_secs = 300
max_sessions = 5

# --- Config Hot-Reload ---
[reload]
mode = "hybrid"                       # off | restart | hot | hybrid
debounce_ms = 500

# --- Shell Exec Policy ---
[exec_policy]
mode = "allowlist"                    # deny | allowlist | full
timeout_secs = 30
max_output_bytes = 102400
no_output_timeout_secs = 30

# --- Budget ---
[budget]
max_hourly_usd = 0.0
max_daily_usd = 0.0
max_monthly_usd = 0.0
alert_threshold = 0.8
default_max_llm_tokens_per_hour = 0

# --- Extended Thinking ---
[thinking]
budget_tokens = 10000
stream_thinking = false

# --- TTS ---
[tts]
enabled = false
max_text_length = 4096
timeout_secs = 30

[tts.openai]
voice = "alloy"
model = "tts-1"
format = "mp3"
speed = 1.0

# --- Docker Sandbox ---
[docker]
enabled = false
image = "python:3.12-slim"
network = "none"
memory_limit = "512m"
cpu_limit = 1.0
timeout_secs = 60
read_only_root = true
mode = "off"                          # off | non_main | all
scope = "session"                     # session | agent | shared
cap_add = []                          # e.g., ["NET_ADMIN"]
tmpfs = ["/tmp:size=64m"]
pids_limit = 100

# --- Vault ---
[vault]
enabled = true
# path = "~/.librefang/vault.enc"

# --- Webhook Triggers ---
[webhook_triggers]
enabled = false
token_env = "LIBREFANG_WEBHOOK_TOKEN"
max_payload_bytes = 65536
rate_limit_per_minute = 30

# --- HTTP Proxy ---
[proxy]
# http_proxy = "http://proxy.corp.example:8080"
# https_proxy = "http://proxy.corp.example:8080"
# no_proxy = "localhost,127.0.0.1,.internal.corp"

# --- Session ---
[session]
retention_days = 0
max_sessions_per_agent = 0
cleanup_interval_hours = 24

# --- Queue ---
[queue]
max_depth_per_agent = 0
max_depth_global = 0
task_ttl_secs = 3600

[queue.concurrency]
main_lane = 3
cron_lane = 2
subagent_lane = 3

# --- Audit ---
[audit]
retention_days = 90

# --- External Auth (OAuth2/OIDC) ---
[external_auth]
enabled = false
# issuer_url = "https://accounts.google.com"
# client_id = "your-client-id"
# client_secret_env = "LIBREFANG_OAUTH_CLIENT_SECRET"

# --- Vertex AI ---
[vertex_ai]
# project_id = "my-gcp-project"
# region = "us-central1"
# credentials_path = "/path/to/service-account.json"

# --- Context Engine ---
[context_engine]
engine = "default"
# plugin = "qdrant-recall"

# --- Plugins ---
[plugins]
plugin_registries = []

Section Reference

Top-Level Fields

These fields sit at the root of config.toml (not inside any [section]).

Field	Type	Default	Description
`home_dir`	path	`~/.librefang`	LibreFang home directory. Stores config, agents, skills.
`data_dir`	path	`~/.librefang/data`	Directory for SQLite databases and persistent data.
`log_level`	string	`"info"`	Log verbosity. One of: `trace`, `debug`, `info`, `warn`, `error`.
`api_listen`	string	`"127.0.0.1:4545"`	Bind address for the HTTP/WebSocket/SSE API server. Alias: `listen_addr`.
`network_enabled`	bool	`false`	Enable the OFP peer-to-peer network layer.
`api_key`	string	`""` (empty)	API authentication key. When set, all endpoints except `/api/health` require `Authorization: Bearer <key>`. Empty means unauthenticated (local development only).
`cors_origin`	list of strings	`[]`	CORS allowed origins added to the allow list (in addition to localhost). E.g., `["https://dash.example.com"]`.
`mode`	string	`"default"`	Kernel operating mode. See below.
`language`	string	`"en"`	Language/locale code for CLI output and system messages.
`usage_footer`	string	`"full"`	Controls usage info appended to responses. See below.
`prompt_caching`	bool	`true`	Enable LLM provider prompt caching. Adds cache hints to system prompts (Anthropic: `cache_control`, OpenAI: automatic prefix caching).
`stable_prefix_mode`	bool	`false`	When enabled, avoids volatile system-prompt additions (recalled memory, canonical context) that change every turn, improving provider-side prompt cache hit rates.
`max_cron_jobs`	usize	`500`	Global maximum number of cron jobs across all agents.
`workspaces_dir`	path or null	`null`	Root directory for agent workspaces. Defaults to `~/.librefang/workspaces`.
`include`	list of strings	`[]`	Config file includes (relative paths). See Config Include Mechanism.
`provider_urls`	map of string→string	`{}`	Provider base URL overrides. Maps provider ID to custom base URL (e.g., `ollama = "http://192.168.1.100:11434/v1"`). Useful for self-hosted or proxied endpoints.
`provider_api_keys`	map of string→string	`{}`	Provider API key env var overrides. Maps provider ID to the name of an environment variable holding the key (e.g., `nvidia = "NVIDIA_API_KEY"`). When not set for a provider, the convention `{PROVIDER_UPPER}_API_KEY` is used.
`provider_regions`	map of string→string	`{}`	Provider region selection. Maps provider ID to a region name defined in the provider's registry TOML (e.g., `qwen = "intl"`). Overrides the provider's base URL and optionally its API key env var. Applied before `provider_urls` (lower priority).

mode values:

Value	Behavior
`stable`	Conservative: no auto-updates, pinned models, frozen skill registry. Uses `FallbackDriver`.
`default`	Balanced: standard operation.
`dev`	Developer: experimental features enabled.

usage_footer values:

Value	Behavior
`off`	No usage information shown.
`tokens`	Show token counts only.
`cost`	Show estimated cost only.
`full`	Show both token counts and estimated cost (default).

`[default_model]`

Configures the primary LLM provider used when agents do not specify their own model.

[default_model]
provider = "anthropic"
model = "claude-sonnet-4-20250514"
api_key_env = "ANTHROPIC_API_KEY"
# base_url = "https://api.anthropic.com"

Field	Type	Default	Description
`provider`	string	`"anthropic"`	Provider name. Supported: `anthropic`, `gemini`, `openai`, `groq`, `openrouter`, `deepseek`, `together`, `mistral`, `fireworks`, `ollama`, `vllm`, `lmstudio`, `perplexity`, `cohere`, `ai21`, `cerebras`, `sambanova`, `huggingface`, `xai`, `replicate`.
`model`	string	`"claude-sonnet-4-20250514"`	Model identifier. Aliases like `sonnet`, `haiku`, `gpt-4o`, `gemini-flash` are resolved by the model catalog.
`api_key_env`	string	`"ANTHROPIC_API_KEY"`	Name of the environment variable holding the API key. The actual key is read from this env var at runtime, never stored in config.
`base_url`	string or null	`null`	Override the API base URL. Useful for proxies or self-hosted endpoints. When `null`, the provider's default URL from the model catalog is used.

`[memory]`

Configures the SQLite-backed memory substrate, including vector embeddings and memory decay.

[memory]
# sqlite_path = "/custom/path/librefang.db"
embedding_model = "all-MiniLM-L6-v2"
consolidation_threshold = 10000
decay_rate = 0.1

Field	Type	Default	Description
`sqlite_path`	path or null	`null`	Explicit path to the SQLite database file. When `null`, defaults to `{data_dir}/librefang.db`.
`embedding_model`	string	`"all-MiniLM-L6-v2"`	Model name used for generating vector embeddings for semantic memory search.
`embedding_provider`	string or null	`null`	Embedding provider (e.g., `"openai"`, `"ollama"`). Auto-detected if `null`.
`embedding_api_key_env`	string or null	`null`	Environment variable name holding the API key for the embedding provider.
`consolidation_threshold`	u64	`10000`	Number of stored memories before automatic consolidation is triggered to merge and prune old entries.
`consolidation_interval_hours`	u64	`24`	How often memory consolidation runs (hours). `0` = disabled.
`decay_rate`	f32	`0.1`	Memory confidence decay rate. `0.0` = no decay (memories never fade), `1.0` = aggressive decay. Values between 0.0 and 1.0.

`[network]`

Configures the OFP (LibreFang Protocol) peer-to-peer networking layer with HMAC-SHA256 mutual authentication.

[network]
listen_addresses = ["/ip4/0.0.0.0/tcp/0"]
bootstrap_peers = []
mdns_enabled = true
max_peers = 50
shared_secret = "my-cluster-secret"

Field	Type	Default	Description
`listen_addresses`	list of strings	`["/ip4/0.0.0.0/tcp/0"]`	libp2p multiaddresses to listen on. Port `0` means auto-assign.
`bootstrap_peers`	list of strings	`[]`	Multiaddresses of bootstrap peers for DHT discovery.
`mdns_enabled`	bool	`true`	Enable mDNS for automatic local network peer discovery.
`max_peers`	u32	`50`	Maximum number of simultaneously connected peers.
`shared_secret`	string	`""` (empty)	Pre-shared secret for OFP HMAC-SHA256 mutual authentication. Required when `network_enabled = true`. Both sides must use the same secret. Redacted in logs.

`[web]`

Configures web search and web fetch capabilities used by agent tools.

[web]
search_provider = "auto"
cache_ttl_minutes = 15

Field	Type	Default	Description
`search_provider`	string	`"auto"`	Which search engine to use. See values below.
`cache_ttl_minutes`	u64	`15`	Cache duration for search/fetch results in minutes. `0` = caching disabled.

search_provider values:

Value	Description
`auto`	Cascading fallback: tries Tavily, then Brave, then Perplexity, then DuckDuckGo, based on which API keys are available.
`brave`	Brave Search API. Requires `BRAVE_API_KEY`.
`tavily`	Tavily AI-native search. Requires `TAVILY_API_KEY`.
`perplexity`	Perplexity AI search. Requires `PERPLEXITY_API_KEY`.
`duckduckgo`	DuckDuckGo HTML scraping. No API key needed.

`[web.brave]`

[web.brave]
api_key_env = "BRAVE_API_KEY"
max_results = 5
country = ""
search_lang = ""
freshness = ""

Field	Type	Default	Description
`api_key_env`	string	`"BRAVE_API_KEY"`	Environment variable name holding the Brave Search API key.
`max_results`	usize	`5`	Maximum number of search results to return.
`country`	string	`""`	Country code for localized results (e.g., `"US"`, `"GB"`). Empty = no filter.
`search_lang`	string	`""`	Language code (e.g., `"en"`, `"fr"`). Empty = no filter.
`freshness`	string	`""`	Freshness filter. `"pd"` = past day, `"pw"` = past week, `"pm"` = past month. Empty = no filter.

`[web.tavily]`

[web.tavily]
api_key_env = "TAVILY_API_KEY"
search_depth = "basic"
max_results = 5
include_answer = true

Field	Type	Default	Description
`api_key_env`	string	`"TAVILY_API_KEY"`	Environment variable name holding the Tavily API key.
`search_depth`	string	`"basic"`	Search depth: `"basic"` for fast results, `"advanced"` for deeper analysis.
`max_results`	usize	`5`	Maximum number of search results to return.
`include_answer`	bool	`true`	Whether to include Tavily's AI-generated answer summary in results.

`[web.perplexity]`

[web.perplexity]
api_key_env = "PERPLEXITY_API_KEY"
model = "sonar"

Field	Type	Default	Description
`api_key_env`	string	`"PERPLEXITY_API_KEY"`	Environment variable name holding the Perplexity API key.
`model`	string	`"sonar"`	Perplexity model to use for search queries.

`[web.fetch]`

[web.fetch]
max_chars = 50000
max_response_bytes = 10485760
timeout_secs = 30
readability = true

Field	Type	Default	Description
`max_chars`	usize	`50000`	Maximum characters returned in fetched content. Content exceeding this is truncated.
`max_response_bytes`	usize	`10485760` (10 MB)	Maximum HTTP response body size in bytes.
`timeout_secs`	u64	`30`	HTTP request timeout in seconds.
`readability`	bool	`true`	Enable HTML-to-Markdown readability extraction. When true, fetched HTML is converted to clean Markdown.

`[media]`

Configures media understanding (image description, audio transcription, video description) for messages that include attachments.

[media]
image_description = true
audio_transcription = true
video_description = false
max_concurrency = 2
# image_provider = "openai"   # auto-detect if omitted
# audio_provider = "openai"   # auto-detect if omitted

Field	Type	Default	Description
`image_description`	bool	`true`	Enable automatic image description for incoming image attachments.
`audio_transcription`	bool	`true`	Enable automatic audio transcription for incoming audio attachments.
`video_description`	bool	`false`	Enable video description. Disabled by default (expensive and slow).
`max_concurrency`	usize	`2`	Maximum number of concurrent media processing tasks.
`image_provider`	string or null	`null`	Preferred provider for image description. Auto-detected from available providers if `null`.
`audio_provider`	string or null	`null`	Preferred provider for audio transcription. Auto-detected from available providers if `null`.

`[links]`

Configures automatic link understanding — fetching and summarizing URLs found in incoming messages.

[links]
enabled = false
max_links = 3
max_content_bytes = 102400
timeout_secs = 10

Field	Type	Default	Description
`enabled`	bool	`false`	Enable automatic link understanding. When `true`, URLs in messages are fetched and their content is summarized before the agent processes the message.
`max_links`	usize	`3`	Maximum number of links to process per message. Additional links are ignored.
`max_content_bytes`	usize	`102400` (100 KB)	Maximum content size to fetch per link in bytes. Content exceeding this is truncated.
`timeout_secs`	u64	`10`	Per-link fetch timeout in seconds.

`[channels]`

All 45 channel adapters are configured under [channels.<name>]. Each channel is Option<T> -- omitting the section disables the adapter entirely. Including the section header (even empty) enables it with default values.

Universal channel fields: Every channel adapter supports the following common fields in addition to its own specific fields:

Field	Type	Default	Description
`default_agent`	string or null	`null`	Agent name to route messages to by default.
`account_id`	string or null	`null`	Unique identifier for this bot instance. Used for multi-bot routing via `[[bindings]]` match rules.
`overrides`	object	(defaults)	Per-channel behavior overrides. See Channel Overrides.

`[channels.telegram]`

[channels.telegram]
bot_token_env = "TELEGRAM_BOT_TOKEN"
allowed_users = []
# default_agent = "assistant"
poll_interval_secs = 1
# api_url = "https://api.telegram.org"  # override for local Bot API server
# account_id = "my-telegram-bot"

Field	Type	Default	Description
`bot_token_env`	string	`"TELEGRAM_BOT_TOKEN"`	Env var holding the Telegram Bot API token.
`allowed_users`	list of i64	`[]`	Telegram user IDs allowed to interact. Empty = allow all.
`default_agent`	string or null	`null`	Agent name to route messages to.
`poll_interval_secs`	u64	`1`	Long-polling interval in seconds.
`account_id`	string or null	`null`	Unique bot instance identifier for multi-bot routing.
`api_url`	string or null	`null`	Override the Telegram Bot API base URL. Useful for local Bot API server instances. Defaults to `https://api.telegram.org`.
`overrides`	object	(defaults)	Per-channel behavior overrides. See Channel Overrides.

`[channels.discord]`

[channels.discord]
bot_token_env = "DISCORD_BOT_TOKEN"
allowed_guilds = []
# default_agent = "assistant"
intents = 37376
ignore_bots = true
# account_id = "my-discord-bot"

Field	Type	Default	Description
`bot_token_env`	string	`"DISCORD_BOT_TOKEN"`	Env var holding the Discord bot token.
`allowed_guilds`	list of u64	`[]`	Guild (server) IDs allowed. Empty = allow all.
`default_agent`	string or null	`null`	Agent name to route messages to.
`allowed_users`	list of strings	`[]`	Discord user IDs allowed to interact. Empty = allow all.
`intents`	u64	`37376`	Gateway intents bitmask. Default = `GUILD_MESSAGES \| DIRECT_MESSAGES \| MESSAGE_CONTENT` (37376).
`ignore_bots`	bool	`true`	When `true`, messages from other bots are ignored.
`account_id`	string or null	`null`	Unique bot instance identifier for multi-bot routing.
`overrides`	object	(defaults)	Per-channel behavior overrides. See Channel Overrides.

`[channels.slack]`

[channels.slack]
app_token_env = "SLACK_APP_TOKEN"
bot_token_env = "SLACK_BOT_TOKEN"
allowed_channels = []
# account_id = "my-slack-bot"

Field	Type	Default	Description
`app_token_env`	string	`"SLACK_APP_TOKEN"`	Env var holding the Slack app-level token (`xapp-`) for Socket Mode.
`bot_token_env`	string	`"SLACK_BOT_TOKEN"`	Env var holding the Slack bot token (`xoxb-`) for REST API.
`allowed_channels`	list of strings	`[]`	Channel IDs allowed. Empty = allow all.
`default_agent`	string or null	`null`	Agent name to route messages to.
`account_id`	string or null	`null`	Unique bot instance identifier for multi-bot routing.
`overrides`	object	(defaults)	Per-channel behavior overrides. See Channel Overrides.

`[channels.whatsapp]`

[channels.whatsapp]
access_token_env = "WHATSAPP_ACCESS_TOKEN"
verify_token_env = "WHATSAPP_VERIFY_TOKEN"
phone_number_id = ""
webhook_port = 8443
allowed_users = []
# gateway_url_env = "WHATSAPP_WEB_GATEWAY_URL"  # for QR/Web mode
# account_id = "my-whatsapp-bot"
# owner_numbers = []   # optional admin phone numbers

Field	Type	Default	Description
`access_token_env`	string	`"WHATSAPP_ACCESS_TOKEN"`	Env var holding the WhatsApp Cloud API access token.
`verify_token_env`	string	`"WHATSAPP_VERIFY_TOKEN"`	Env var holding the webhook verification token.
`phone_number_id`	string	`""`	WhatsApp Business phone number ID.
`webhook_port`	u16	`8443`	Port to listen for incoming webhook callbacks.
`gateway_url_env`	string	`"WHATSAPP_WEB_GATEWAY_URL"`	Env var holding the WhatsApp Web gateway URL. When set, outgoing messages are routed through the QR/Web gateway instead of the Cloud API.
`allowed_users`	list of strings	`[]`	Phone numbers allowed. Empty = allow all.
`default_agent`	string or null	`null`	Agent name to route messages to.
`account_id`	string or null	`null`	Unique bot instance identifier for multi-bot routing.
`owner_numbers`	list of strings	`[]`	Phone numbers with administrative privileges for this bot instance.
`overrides`	object	(defaults)	Per-channel behavior overrides. See Channel Overrides.

`[channels.signal]`

[channels.signal]
api_url = "http://localhost:8080"
phone_number = ""
allowed_users = []

Field	Type	Default	Description
`api_url`	string	`"http://localhost:8080"`	URL of the signal-cli REST API.
`phone_number`	string	`""`	Registered phone number for the bot.
`allowed_users`	list of strings	`[]`	Allowed phone numbers. Empty = allow all.
`default_agent`	string or null	`null`	Agent name to route messages to.

`[channels.matrix]`

[channels.matrix]
homeserver_url = "https://matrix.org"
user_id = "@librefang:matrix.org"
access_token_env = "MATRIX_ACCESS_TOKEN"
allowed_rooms = []

Field	Type	Default	Description
`homeserver_url`	string	`"https://matrix.org"`	Matrix homeserver URL.
`user_id`	string	`""`	Bot user ID (e.g., `"@librefang:matrix.org"`).
`access_token_env`	string	`"MATRIX_ACCESS_TOKEN"`	Env var holding the Matrix access token.
`allowed_rooms`	list of strings	`[]`	Room IDs to listen in. Empty = all joined rooms.
`default_agent`	string or null	`null`	Agent name to route messages to.

`[channels.email]`

[channels.email]
imap_host = "imap.gmail.com"
imap_port = 993
smtp_host = "smtp.gmail.com"
smtp_port = 587
username = "bot@example.com"
password_env = "EMAIL_PASSWORD"
poll_interval_secs = 30
folders = ["INBOX"]
allowed_senders = []

Field	Type	Default	Description
`imap_host`	string	`""`	IMAP server hostname.
`imap_port`	u16	`993`	IMAP server port (993 for TLS).
`smtp_host`	string	`""`	SMTP server hostname.
`smtp_port`	u16	`587`	SMTP server port (587 for STARTTLS).
`username`	string	`""`	Email address for both IMAP and SMTP.
`password_env`	string	`"EMAIL_PASSWORD"`	Env var holding the email password or app password.
`poll_interval_secs`	u64	`30`	IMAP polling interval in seconds.
`folders`	list of strings	`["INBOX"]`	IMAP folders to monitor.
`allowed_senders`	list of strings	`[]`	Only process emails from these senders. Empty = all.
`default_agent`	string or null	`null`	Agent name to route messages to.

`[channels.teams]`

[channels.teams]
app_id = ""
app_password_env = "TEAMS_APP_PASSWORD"
webhook_port = 3978
allowed_tenants = []

Field	Type	Default	Description
`app_id`	string	`""`	Azure Bot App ID.
`app_password_env`	string	`"TEAMS_APP_PASSWORD"`	Env var holding the Azure Bot Framework app password.
`webhook_port`	u16	`3978`	Port for the Bot Framework incoming webhook.
`allowed_tenants`	list of strings	`[]`	Azure AD tenant IDs allowed. Empty = allow all.
`default_agent`	string or null	`null`	Agent name to route messages to.

`[channels.mattermost]`

[channels.mattermost]
server_url = "https://mattermost.example.com"
token_env = "MATTERMOST_TOKEN"
allowed_channels = []

Field	Type	Default	Description
`server_url`	string	`""`	Mattermost server URL.
`token_env`	string	`"MATTERMOST_TOKEN"`	Env var holding the Mattermost bot token.
`allowed_channels`	list of strings	`[]`	Channel IDs to listen in. Empty = all.
`default_agent`	string or null	`null`	Agent name to route messages to.

`[channels.irc]`

[channels.irc]
server = "irc.libera.chat"
port = 6667
nick = "librefang"
# password_env = "IRC_PASSWORD"
channels = ["#librefang"]
use_tls = false

Field	Type	Default	Description
`server`	string	`"irc.libera.chat"`	IRC server hostname.
`port`	u16	`6667`	IRC server port.
`nick`	string	`"librefang"`	Bot nickname.
`password_env`	string or null	`null`	Env var holding the server password (optional).
`channels`	list of strings	`[]`	IRC channels to join (e.g., `["#librefang", "#general"]`).
`use_tls`	bool	`false`	Use TLS for the connection.
`default_agent`	string or null	`null`	Agent name to route messages to.

`[channels.google_chat]`

[channels.google_chat]
service_account_env = "GOOGLE_CHAT_SERVICE_ACCOUNT"
space_ids = []
webhook_port = 8444

Field	Type	Default	Description
`service_account_env`	string	`"GOOGLE_CHAT_SERVICE_ACCOUNT"`	Env var holding the service account JSON key.
`space_ids`	list of strings	`[]`	Google Chat space IDs to listen in.
`webhook_port`	u16	`8444`	Port for the incoming webhook.
`default_agent`	string or null	`null`	Agent name to route messages to.

`[channels.twitch]`

[channels.twitch]
oauth_token_env = "TWITCH_OAUTH_TOKEN"
channels = ["mychannel"]
nick = "librefang"

Field	Type	Default	Description
`oauth_token_env`	string	`"TWITCH_OAUTH_TOKEN"`	Env var holding the Twitch OAuth token.
`channels`	list of strings	`[]`	Twitch channels to join (without `#` prefix).
`nick`	string	`"librefang"`	Bot nickname in Twitch chat.
`default_agent`	string or null	`null`	Agent name to route messages to.

`[channels.rocketchat]`

[channels.rocketchat]
server_url = "https://rocketchat.example.com"
token_env = "ROCKETCHAT_TOKEN"
user_id = ""
allowed_channels = []

Field	Type	Default	Description
`server_url`	string	`""`	Rocket.Chat server URL.
`token_env`	string	`"ROCKETCHAT_TOKEN"`	Env var holding the Rocket.Chat auth token.
`user_id`	string	`""`	Bot user ID.
`allowed_channels`	list of strings	`[]`	Channel IDs to listen in. Empty = all.
`default_agent`	string or null	`null`	Agent name to route messages to.

`[channels.zulip]`

[channels.zulip]
server_url = "https://zulip.example.com"
bot_email = "bot@zulip.example.com"
api_key_env = "ZULIP_API_KEY"
streams = []

Field	Type	Default	Description
`server_url`	string	`""`	Zulip server URL.
`bot_email`	string	`""`	Bot email address registered in Zulip.
`api_key_env`	string	`"ZULIP_API_KEY"`	Env var holding the Zulip API key.
`streams`	list of strings	`[]`	Stream names to listen in. Empty = all.
`default_agent`	string or null	`null`	Agent name to route messages to.

`[channels.xmpp]`

[channels.xmpp]
jid = "bot@jabber.org"
password_env = "XMPP_PASSWORD"
server = ""
port = 5222
rooms = []

Field	Type	Default	Description
`jid`	string	`""`	XMPP JID (e.g., `"bot@jabber.org"`).
`password_env`	string	`"XMPP_PASSWORD"`	Env var holding the XMPP password.
`server`	string	`""`	XMPP server hostname. Defaults to the JID domain if empty.
`port`	u16	`5222`	XMPP server port.
`rooms`	list of strings	`[]`	MUC (multi-user chat) rooms to join.
`default_agent`	string or null	`null`	Agent name to route messages to.

`[channels.line]`

[channels.line]
channel_secret_env = "LINE_CHANNEL_SECRET"
access_token_env = "LINE_CHANNEL_ACCESS_TOKEN"
webhook_port = 8450

Field	Type	Default	Description
`channel_secret_env`	string	`"LINE_CHANNEL_SECRET"`	Env var holding the LINE channel secret.
`access_token_env`	string	`"LINE_CHANNEL_ACCESS_TOKEN"`	Env var holding the LINE channel access token.
`webhook_port`	u16	`8450`	Port for the incoming webhook.
`default_agent`	string or null	`null`	Agent name to route messages to.

`[channels.viber]`

[channels.viber]
auth_token_env = "VIBER_AUTH_TOKEN"
webhook_url = ""
webhook_port = 8451

Field	Type	Default	Description
`auth_token_env`	string	`"VIBER_AUTH_TOKEN"`	Env var holding the Viber Bot auth token.
`webhook_url`	string	`""`	Public URL for the Viber webhook endpoint.
`webhook_port`	u16	`8451`	Port for the incoming webhook.
`default_agent`	string or null	`null`	Agent name to route messages to.

`[channels.messenger]`

[channels.messenger]
page_token_env = "MESSENGER_PAGE_TOKEN"
verify_token_env = "MESSENGER_VERIFY_TOKEN"
webhook_port = 8452

Field	Type	Default	Description
`page_token_env`	string	`"MESSENGER_PAGE_TOKEN"`	Env var holding the Facebook page access token.
`verify_token_env`	string	`"MESSENGER_VERIFY_TOKEN"`	Env var holding the webhook verify token.
`webhook_port`	u16	`8452`	Port for the incoming webhook.
`default_agent`	string or null	`null`	Agent name to route messages to.

`[channels.reddit]`

[channels.reddit]
client_id = ""
client_secret_env = "REDDIT_CLIENT_SECRET"
username = ""
password_env = "REDDIT_PASSWORD"
subreddits = []

Field	Type	Default	Description
`client_id`	string	`""`	Reddit app client ID.
`client_secret_env`	string	`"REDDIT_CLIENT_SECRET"`	Env var holding the Reddit client secret.
`username`	string	`""`	Reddit bot username.
`password_env`	string	`"REDDIT_PASSWORD"`	Env var holding the Reddit bot password.
`subreddits`	list of strings	`[]`	Subreddit names to monitor.
`default_agent`	string or null	`null`	Agent name to route messages to.

`[channels.mastodon]`

[channels.mastodon]
instance_url = "https://mastodon.social"
access_token_env = "MASTODON_ACCESS_TOKEN"

Field	Type	Default	Description
`instance_url`	string	`""`	Mastodon instance URL (e.g., `"https://mastodon.social"`).
`access_token_env`	string	`"MASTODON_ACCESS_TOKEN"`	Env var holding the Mastodon access token.
`default_agent`	string or null	`null`	Agent name to route messages to.

`[channels.bluesky]`

[channels.bluesky]
identifier = "mybot.bsky.social"
app_password_env = "BLUESKY_APP_PASSWORD"
service_url = "https://bsky.social"

Field	Type	Default	Description
`identifier`	string	`""`	Bluesky handle or DID.
`app_password_env`	string	`"BLUESKY_APP_PASSWORD"`	Env var holding the Bluesky app password.
`service_url`	string	`"https://bsky.social"`	PDS (Personal Data Server) URL.
`default_agent`	string or null	`null`	Agent name to route messages to.

`[channels.feishu]`

[channels.feishu]
app_id = ""
app_secret_env = "FEISHU_APP_SECRET"
webhook_port = 8453

Field	Type	Default	Description
`app_id`	string	`""`	Feishu/Lark app ID.
`app_secret_env`	string	`"FEISHU_APP_SECRET"`	Env var holding the Feishu app secret.
`webhook_port`	u16	`8453`	Port for the incoming webhook.
`default_agent`	string or null	`null`	Agent name to route messages to.

`[channels.revolt]`

[channels.revolt]
bot_token_env = "REVOLT_BOT_TOKEN"
api_url = "https://api.revolt.chat"

Field	Type	Default	Description
`bot_token_env`	string	`"REVOLT_BOT_TOKEN"`	Env var holding the Revolt bot token.
`api_url`	string	`"https://api.revolt.chat"`	Revolt API base URL.
`default_agent`	string or null	`null`	Agent name to route messages to.

`[channels.nextcloud]`

[channels.nextcloud]
server_url = "https://nextcloud.example.com"
token_env = "NEXTCLOUD_TOKEN"
allowed_rooms = []

Field	Type	Default	Description
`server_url`	string	`""`	Nextcloud server URL.
`token_env`	string	`"NEXTCLOUD_TOKEN"`	Env var holding the Nextcloud Talk auth token.
`allowed_rooms`	list of strings	`[]`	Room tokens to listen in. Empty = all.
`default_agent`	string or null	`null`	Agent name to route messages to.

`[channels.guilded]`

[channels.guilded]
bot_token_env = "GUILDED_BOT_TOKEN"
server_ids = []

Field	Type	Default	Description
`bot_token_env`	string	`"GUILDED_BOT_TOKEN"`	Env var holding the Guilded bot token.
`server_ids`	list of strings	`[]`	Server IDs to listen in. Empty = all.
`default_agent`	string or null	`null`	Agent name to route messages to.

`[channels.keybase]`

[channels.keybase]
username = ""
paperkey_env = "KEYBASE_PAPERKEY"
allowed_teams = []

Field	Type	Default	Description
`username`	string	`""`	Keybase username.
`paperkey_env`	string	`"KEYBASE_PAPERKEY"`	Env var holding the Keybase paper key.
`allowed_teams`	list of strings	`[]`	Team names to listen in. Empty = all DMs.
`default_agent`	string or null	`null`	Agent name to route messages to.

`[channels.threema]`

[channels.threema]
threema_id = ""
secret_env = "THREEMA_SECRET"
webhook_port = 8454

Field	Type	Default	Description
`threema_id`	string	`""`	Threema Gateway ID.
`secret_env`	string	`"THREEMA_SECRET"`	Env var holding the Threema API secret.
`webhook_port`	u16	`8454`	Port for the incoming webhook.
`default_agent`	string or null	`null`	Agent name to route messages to.

`[channels.nostr]`

[channels.nostr]
private_key_env = "NOSTR_PRIVATE_KEY"
relays = ["wss://relay.damus.io"]

Field	Type	Default	Description
`private_key_env`	string	`"NOSTR_PRIVATE_KEY"`	Env var holding the Nostr private key (nsec or hex format).
`relays`	list of strings	`["wss://relay.damus.io"]`	Nostr relay WebSocket URLs to connect to.
`default_agent`	string or null	`null`	Agent name to route messages to.

`[channels.webex]`

[channels.webex]
bot_token_env = "WEBEX_BOT_TOKEN"
allowed_rooms = []

Field	Type	Default	Description
`bot_token_env`	string	`"WEBEX_BOT_TOKEN"`	Env var holding the Webex bot token.
`allowed_rooms`	list of strings	`[]`	Room IDs to listen in. Empty = all.
`default_agent`	string or null	`null`	Agent name to route messages to.

`[channels.pumble]`

[channels.pumble]
bot_token_env = "PUMBLE_BOT_TOKEN"
webhook_port = 8455

Field	Type	Default	Description
`bot_token_env`	string	`"PUMBLE_BOT_TOKEN"`	Env var holding the Pumble bot token.
`webhook_port`	u16	`8455`	Port for the incoming webhook.
`default_agent`	string or null	`null`	Agent name to route messages to.

`[channels.flock]`

[channels.flock]
bot_token_env = "FLOCK_BOT_TOKEN"
webhook_port = 8456

Field	Type	Default	Description
`bot_token_env`	string	`"FLOCK_BOT_TOKEN"`	Env var holding the Flock bot token.
`webhook_port`	u16	`8456`	Port for the incoming webhook.
`default_agent`	string or null	`null`	Agent name to route messages to.

`[channels.twist]`

[channels.twist]
token_env = "TWIST_TOKEN"
workspace_id = ""
allowed_channels = []

Field	Type	Default	Description
`token_env`	string	`"TWIST_TOKEN"`	Env var holding the Twist API token.
`workspace_id`	string	`""`	Twist workspace ID.
`allowed_channels`	list of strings	`[]`	Channel IDs to listen in. Empty = all.
`default_agent`	string or null	`null`	Agent name to route messages to.

`[channels.mumble]`

[channels.mumble]
host = "mumble.example.com"
port = 64738
username = "librefang"
password_env = "MUMBLE_PASSWORD"
channel = ""

Field	Type	Default	Description
`host`	string	`""`	Mumble server hostname.
`port`	u16	`64738`	Mumble server port.
`username`	string	`"librefang"`	Bot username in Mumble.
`password_env`	string	`"MUMBLE_PASSWORD"`	Env var holding the Mumble server password.
`channel`	string	`""`	Mumble channel to join.
`default_agent`	string or null	`null`	Agent name to route messages to.

`[channels.dingtalk]`

[channels.dingtalk]
access_token_env = "DINGTALK_ACCESS_TOKEN"
secret_env = "DINGTALK_SECRET"
webhook_port = 8457

Field	Type	Default	Description
`access_token_env`	string	`"DINGTALK_ACCESS_TOKEN"`	Env var holding the DingTalk webhook access token.
`secret_env`	string	`"DINGTALK_SECRET"`	Env var holding the DingTalk signing secret.
`webhook_port`	u16	`8457`	Port for the incoming webhook.
`default_agent`	string or null	`null`	Agent name to route messages to.

`[channels.discourse]`

[channels.discourse]
base_url = "https://forum.example.com"
api_key_env = "DISCOURSE_API_KEY"
api_username = "system"
categories = []

Field	Type	Default	Description
`base_url`	string	`""`	Discourse forum base URL.
`api_key_env`	string	`"DISCOURSE_API_KEY"`	Env var holding the Discourse API key.
`api_username`	string	`"system"`	Discourse API username.
`categories`	list of strings	`[]`	Category slugs to monitor.
`default_agent`	string or null	`null`	Agent name to route messages to.

`[channels.gitter]`

[channels.gitter]
token_env = "GITTER_TOKEN"
room_id = ""

Field	Type	Default	Description
`token_env`	string	`"GITTER_TOKEN"`	Env var holding the Gitter auth token.
`room_id`	string	`""`	Gitter room ID to listen in.
`default_agent`	string or null	`null`	Agent name to route messages to.

`[channels.ntfy]`

[channels.ntfy]
server_url = "https://ntfy.sh"
topic = "my-agent-topic"
token_env = "NTFY_TOKEN"

Field	Type	Default	Description
`server_url`	string	`"https://ntfy.sh"`	ntfy server URL. Can be self-hosted.
`topic`	string	`""`	Topic to subscribe/publish to.
`token_env`	string	`"NTFY_TOKEN"`	Env var holding the auth token. Optional for public topics.
`default_agent`	string or null	`null`	Agent name to route messages to.

`[channels.gotify]`

[channels.gotify]
server_url = "https://gotify.example.com"
app_token_env = "GOTIFY_APP_TOKEN"
client_token_env = "GOTIFY_CLIENT_TOKEN"

Field	Type	Default	Description
`server_url`	string	`""`	Gotify server URL.
`app_token_env`	string	`"GOTIFY_APP_TOKEN"`	Env var holding the Gotify app token (for sending messages).
`client_token_env`	string	`"GOTIFY_CLIENT_TOKEN"`	Env var holding the Gotify client token (for receiving messages via WebSocket).
`default_agent`	string or null	`null`	Agent name to route messages to.

`[channels.webhook]`

[channels.webhook]
secret_env = "WEBHOOK_SECRET"
listen_port = 8460
# callback_url = "https://example.com/webhook"

Field	Type	Default	Description
`secret_env`	string	`"WEBHOOK_SECRET"`	Env var holding the HMAC signing secret for verifying incoming webhooks.
`listen_port`	u16	`8460`	Port to listen for incoming webhook requests.
`callback_url`	string or null	`null`	URL to POST outgoing messages to.
`default_agent`	string or null	`null`	Agent name to route messages to.

`[channels.linkedin]`

[channels.linkedin]
access_token_env = "LINKEDIN_ACCESS_TOKEN"
organization_id = ""

Field	Type	Default	Description
`access_token_env`	string	`"LINKEDIN_ACCESS_TOKEN"`	Env var holding the LinkedIn OAuth2 access token.
`organization_id`	string	`""`	LinkedIn organization ID for messaging.
`default_agent`	string or null	`null`	Agent name to route messages to.

`[channels.qq]`

QQ Bot channel adapter using the official QQ Bot Open Platform API.

[channels.qq]
app_id = "your-app-id"
app_secret_env = "QQ_BOT_APP_SECRET"
allowed_users = []
# default_agent = "assistant"
# account_id = "my-qq-bot"

Field	Type	Default	Description
`app_id`	string	`""`	QQ Bot application ID registered on the QQ Open Platform.
`app_secret_env`	string	`"QQ_BOT_APP_SECRET"`	Env var holding the QQ Bot application secret. The actual secret is never stored in config.
`allowed_users`	list of strings	`[]`	QQ user IDs allowed to interact. Empty = allow all.
`default_agent`	string or null	`null`	Agent name to route messages to.
`account_id`	string or null	`null`	Unique bot instance identifier for multi-bot routing.
`overrides`	object	(defaults)	Per-channel behavior overrides. See Channel Overrides.

`[channels.wecom]`

WeCom (formerly WeChat Work / Enterprise WeChat) channel adapter.

[channels.wecom]
corp_id = "your-corp-id"
agent_id = "your-agent-id"
secret_env = "WECOM_SECRET"
webhook_port = 8454
# token_env = "WECOM_TOKEN"
# encoding_aes_key_env = "WECOM_AES_KEY"
# default_agent = "assistant"
# account_id = "my-wecom-bot"

Field	Type	Default	Description
`corp_id`	string	`""`	WeCom corporation ID.
`agent_id`	string	`""`	WeCom application agent ID.
`secret_env`	string	`"WECOM_SECRET"`	Env var holding the WeCom application secret.
`webhook_port`	u16	`8454`	Port for the incoming webhook.
`token_env`	string or null	`null`	Env var holding the callback verification token. Required for verifying incoming messages.
`encoding_aes_key_env`	string or null	`null`	Env var holding the encoding AES key for message encryption/decryption.
`default_agent`	string or null	`null`	Agent name to route messages to.
`account_id`	string or null	`null`	Unique bot instance identifier for multi-bot routing.
`overrides`	object	(defaults)	Per-channel behavior overrides. See Channel Overrides.

`[channels.wechat]`

WeChat personal account channel adapter using Tencent's iLink Bot API. Connects via QR code scan — no API keys or developer accounts required.

[channels.wechat]
# bot_token_env = "WECHAT_BOT_TOKEN"  # optional: persisted token from previous session
allowed_users = []
# default_agent = "assistant"
# account_id = "my-wechat-bot"

Field	Type	Default	Description
`bot_token_env`	string	`"WECHAT_BOT_TOKEN"`	Env var holding a persisted bot token from a previous QR login session. When set, skips QR login on restart.
`allowed_users`	list of strings	`[]`	WeChat user IDs allowed to interact (format: `hash@im.wechat`). Empty = allow all.
`default_agent`	string or null	`null`	Agent name to route messages to.
`account_id`	string or null	`null`	Unique bot instance identifier for multi-bot routing.
`overrides`	object	(defaults)	Per-channel behavior overrides. See Channel Overrides.

`[[mcp_servers]]`

MCP (Model Context Protocol) server connections provide external tool integration. Each entry is a separate [[mcp_servers]] array element.

[[mcp_servers]]
name = "filesystem"
timeout_secs = 30
env = []

[mcp_servers.transport]
type = "stdio"
command = "npx"
args = ["-y", "@modelcontextprotocol/server-filesystem", "/home/user/docs"]

[[mcp_servers]]
name = "remote-api"
timeout_secs = 60
env = ["GITHUB_PERSONAL_ACCESS_TOKEN"]

[mcp_servers.transport]
type = "sse"
url = "https://mcp.example.com/sse"

[[mcp_servers]]
name = "my-http-backend"
timeout_secs = 30

[mcp_servers.transport]
type = "http_compat"
base_url = "https://tools.example.com"
headers = [{name = "Authorization", value_env = "MY_API_KEY"}]

[[mcp_servers.transport.tools]]
name = "search"
description = "Search documents"
path = "/search"
method = "post"

Field	Type	Default	Description
`name`	string	required	Display name for this MCP server. Tools are namespaced as `mcp_{name}_{tool}`.
`timeout_secs`	u64	`30`	Request timeout in seconds.
`env`	list of strings	`[]`	Environment variable names to pass through to the subprocess (stdio transport only).

Transport variants (tagged union on type):

`type`	Fields	Description
`stdio`	`command` (string), `args` (list of strings, default `[]`)	Spawn a subprocess, communicate via JSON-RPC over stdin/stdout.
`sse`	`url` (string)	Connect to an HTTP Server-Sent Events endpoint.
`http_compat`	`base_url` (string), `headers` (list of header configs), `tools` (list of tool configs)	Built-in compatibility adapter for plain HTTP/JSON tool backends without a native MCP server. Each tool maps to an HTTP endpoint.

http_compat header config:

Field	Type	Description
`name`	string	HTTP header name (e.g., `"Authorization"`).
`value`	string or null	Static header value.
`value_env`	string or null	Env var name whose value is used as the header value (preferred for secrets).

http_compat tool config:

Field	Type	Default	Description
`name`	string	required	Tool name exposed to the LLM.
`description`	string	`""`	Tool description shown to the LLM.
`path`	string	required	HTTP path (e.g., `"/search"`).
`method`	string	`"post"`	HTTP method: `get`, `post`, `put`, `patch`, `delete`.
`request_mode`	string	`"json_body"`	How arguments are sent: `json_body`, `query`, `none`.
`response_mode`	string	`"json"`	Response parsing: `json`, `text`.
`input_schema`	object	`{"type":"object"}`	JSON Schema for the tool's input parameters.

`[a2a]`

Agent-to-Agent protocol configuration, enabling inter-agent communication across LibreFang instances.

[a2a]
enabled = true
name = "LibreFang Agent OS"
description = "My production agent OS"
listen_path = "/a2a"

[[a2a.external_agents]]
name = "research-agent"
url = "https://agent.example.com/.well-known/agent.json"

[[a2a.external_agents]]
name = "code-reviewer"
url = "https://reviewer.example.com/.well-known/agent.json"

Field	Type	Default	Description
`enabled`	bool	`false`	Whether A2A protocol is enabled.
`name`	string	`"LibreFang Agent OS"`	Service-level display name shown in the well-known agent card.
`description`	string	`""`	Service-level description shown in the well-known agent card.
`listen_path`	string	`"/a2a"`	URL path prefix for A2A endpoints.
`external_agents`	list of objects	`[]`	External A2A agents to discover and interact with.

external_agents entries:

Field	Type	Description
`name`	string	Display name for the external agent.
`url`	string	Agent card endpoint URL (typically `/.well-known/agent.json`).

`[[fallback_providers]]`

Fallback provider chain. When the primary LLM provider ([default_model]) fails, these are tried in order.

[[fallback_providers]]
provider = "ollama"
model = "llama3.2:latest"
api_key_env = ""
# base_url = "http://localhost:11434"

[[fallback_providers]]
provider = "groq"
model = "llama-3.3-70b-versatile"
api_key_env = "GROQ_API_KEY"

Field	Type	Default	Description
`provider`	string	`""`	Provider name (e.g., `"ollama"`, `"groq"`, `"openai"`).
`model`	string	`""`	Model identifier for this provider.
`api_key_env`	string	`""`	Env var name for the API key. Empty for local providers (ollama, vllm, lmstudio).
`base_url`	string or null	`null`	Base URL override. Uses catalog default if null.

`[[users]]`

RBAC multi-user configuration. Users can be assigned roles and bound to channel platform identities.

[[users]]
name = "Alice"
role = "owner"
api_key_hash = "sha256_hash_of_api_key"

[users.channel_bindings]
telegram = "123456"
discord = "987654321"
slack = "U0ABCDEFG"

Field	Type	Default	Description
`name`	string	required	User display name.
`role`	string	`"user"`	User role in the RBAC hierarchy.
`channel_bindings`	map of string to string	`{}`	Maps channel platform names to platform-specific user IDs, binding this user identity across channels.
`api_key_hash`	string or null	`null`	SHA256 hash of the user's personal API key for authenticated API access.

Role hierarchy (highest to lowest privilege):

Role	Description
`owner`	Full administrative access. Can manage all agents, users, and configuration.
`admin`	Can manage agents and most settings. Cannot modify owner accounts.
`user`	Can interact with agents. Limited management capabilities.
`viewer`	Read-only access. Can view agent responses but cannot send messages.

Channel Overrides

Every channel adapter supports an [channels.<name>.overrides] sub-table that customizes agent behavior per-channel.

[channels.telegram.overrides]
model = "claude-haiku-4-5-20251001"
system_prompt = "You are a concise Telegram assistant."
dm_policy = "respond"
group_policy = "mention_only"
rate_limit_per_minute = 0
rate_limit_per_user = 10
threading = true
output_format = "telegram_html"
usage_footer = "tokens"
typing_mode = "instant"

Field	Type	Default	Description
`model`	string or null	`null`	Model override for this channel. Uses the agent's default model when null.
`system_prompt`	string or null	`null`	System prompt override for this channel.
`dm_policy`	string	`"respond"`	How the bot handles direct messages. See below.
`group_policy`	string	`"mention_only"`	How the bot handles group messages. See below.
`rate_limit_per_minute`	u32	`0`	Global rate limit for this channel (messages per minute). `0` = unlimited.
`rate_limit_per_user`	u32	`0`	Maximum messages per user per minute. `0` = unlimited.
`threading`	bool	`false`	Enable thread replies (where supported by the platform).
`output_format`	string or null	`null`	Override output formatting. See below.
`usage_footer`	string or null	`null`	Override usage footer mode for this channel. Values: `off`, `tokens`, `cost`, `full`.
`typing_mode`	string or null	`null`	Typing indicator behavior. See below. Defaults to `instant`.

dm_policy values:

Value	Description
`respond`	Respond to all direct messages (default).
`allowed_only`	Only respond to DMs from users in the allowed list.
`ignore`	Ignore all direct messages.

group_policy values:

Value	Description
`all`	Respond to all messages in group chats.
`mention_only`	Only respond when the bot is @mentioned (default).
`commands_only`	Only respond to slash commands.
`ignore`	Ignore all group messages.

output_format values:

Value	Description
`markdown`	Standard Markdown (default).
`telegram_html`	Telegram HTML subset (`<b>`, `<i>`, `<code>`, etc.).
`slack_mrkdwn`	Slack mrkdwn format (`bold`, `_italic_`, `code`).
`plain_text`	No formatting markup.

typing_mode values:

Value	Description
`instant`	Send typing indicator immediately on message receipt (default).
`message`	Send typing indicator only when the first text delta arrives from the LLM.
`thinking`	Send typing indicator only during LLM reasoning/thinking phase.
`never`	Never send typing indicators.

`[browser]`

Configures the headless browser automation engine used by the browser_* agent tools.

[browser]
headless = true
viewport_width = 1280
viewport_height = 720
timeout_secs = 30
idle_timeout_secs = 300
max_sessions = 5
# chromium_path = "/usr/bin/chromium"

Field	Type	Default	Description
`headless`	bool	`true`	Run browser in headless mode (no visible window).
`viewport_width`	u32	`1280`	Browser viewport width in pixels.
`viewport_height`	u32	`720`	Browser viewport height in pixels.
`timeout_secs`	u64	`30`	Per-action timeout in seconds.
`idle_timeout_secs`	u64	`300`	Auto-close browser session after this many seconds of inactivity.
`max_sessions`	usize	`5`	Maximum concurrent browser sessions.
`chromium_path`	string or null	`null`	Path to the Chromium/Chrome binary. Auto-detected if null.

`[reload]`

Controls automatic config file watching and hot-reloading.

[reload]
mode = "hybrid"
debounce_ms = 500

Field	Type	Default	Description
`mode`	string	`"hybrid"`	Reload mode. See below.
`debounce_ms`	u64	`500`	Debounce window in milliseconds before reloading after a file change is detected.

mode values:

Value	Description
`off`	No automatic reloading. Changes require a manual restart.
`restart`	Full daemon restart on any config change.
`hot`	Hot-reload safe sections only (channels, skills, heartbeat).
`hybrid`	Hot-reload where possible; flag restart-required for sections that need it (default).

`[exec_policy]`

Controls which shell commands agents are allowed to execute via the exec and shell tools.

[exec_policy]
mode = "allowlist"
allowed_commands = ["git", "python3", "node"]
timeout_secs = 30
max_output_bytes = 102400
no_output_timeout_secs = 30

Field	Type	Default	Description
`mode`	string	`"allowlist"`	Security mode. See below.
`safe_bins`	list of strings	`["sleep","true","false","cat","sort","uniq","cut","tr","head","tail","wc","date","echo","printf","basename","dirname","pwd","env"]`	Commands that always bypass the allowlist check (stdin-only POSIX utilities).
`allowed_commands`	list of strings	`[]`	Additional commands permitted when `mode = "allowlist"`.
`timeout_secs`	u64	`30`	Maximum wall-clock execution time per command in seconds.
`max_output_bytes`	usize	`102400`	Maximum combined stdout+stderr output size in bytes (100 KB default).
`no_output_timeout_secs`	u64	`30`	Kill processes that produce no output for this many seconds. `0` = disabled.

mode values:

Value	Aliases	Description
`deny`	`none`, `disabled`	Block all shell execution.
`allowlist`	`restricted`	Only allow commands in `safe_bins` or `allowed_commands` (default).
`full`	`allow`, `all`, `unrestricted`	Allow all commands. Unsafe -- development use only.

`[approval]`

Configures which tools require explicit human approval before execution. References the ApprovalPolicy type.

[approval]
require_approval = ["shell_exec"]
timeout_secs = 60
auto_approve_autonomous = false
auto_approve = false

Field	Type	Default	Description
`require_approval`	list of strings	`["shell_exec"]`	List of tool names that pause execution and wait for human approval before proceeding.
`timeout_secs`	u64	`60`	Timeout for approval requests in seconds.
`auto_approve_autonomous`	bool	`false`	Auto-approve tools when agent is in autonomous mode.
`auto_approve`	bool	`false`	Auto-approve all tool executions (unsafe, dev only).

`[budget]`

Sets global spending limits for LLM API costs. All limits default to 0.0 (unlimited).

[budget]
max_hourly_usd = 1.00
max_daily_usd = 10.00
max_monthly_usd = 50.00
alert_threshold = 0.8
default_max_llm_tokens_per_hour = 0

Field	Type	Default	Description
`max_hourly_usd`	f64	`0.0`	Maximum total LLM cost in USD per hour across all agents. `0.0` = unlimited.
`max_daily_usd`	f64	`0.0`	Maximum total LLM cost in USD per day across all agents. `0.0` = unlimited.
`max_monthly_usd`	f64	`0.0`	Maximum total LLM cost in USD per month across all agents. `0.0` = unlimited.
`alert_threshold`	f64	`0.8`	Warning threshold as a fraction of each limit (0.0–1.0). At 0.8, warnings are logged when 80% of a limit is reached.
`default_max_llm_tokens_per_hour`	u64	`0`	Global override for per-agent hourly token budget. When `> 0`, overrides all agents' own token limits. `0` = keep each agent's own limit.

`[thinking]`

Configures extended thinking (chain-of-thought reasoning) for models that support it (e.g., Claude 3.7 Sonnet with thinking mode).

[thinking]
budget_tokens = 10000
stream_thinking = false

Field	Type	Default	Description
`budget_tokens`	u32	`10000`	Maximum tokens allocated for the thinking/reasoning phase.
`stream_thinking`	bool	`false`	Whether to stream thinking tokens to the client (visible in the API response stream).

`[tts]`

Configures text-to-speech synthesis for voice output.

[tts]
enabled = false
provider = "openai"          # openai | elevenlabs
max_text_length = 4096
timeout_secs = 30

[tts.openai]
voice = "alloy"
model = "tts-1"
format = "mp3"
speed = 1.0

[tts.elevenlabs]
voice_id = "21m00Tcm4TlvDq8ikWAM"
model_id = "eleven_monolingual_v1"
stability = 0.5
similarity_boost = 0.75

[tts] fields:

Field	Type	Default	Description
`enabled`	bool	`false`	Enable TTS synthesis.
`provider`	string or null	`null`	Default TTS provider: `"openai"` or `"elevenlabs"`.
`max_text_length`	usize	`4096`	Maximum text length in characters for a single TTS request.
`timeout_secs`	u64	`30`	Request timeout per TTS call in seconds.

[tts.openai] fields:

Field	Type	Default	Description
`voice`	string	`"alloy"`	Voice name. Options: `alloy`, `echo`, `fable`, `onyx`, `nova`, `shimmer`.
`model`	string	`"tts-1"`	TTS model: `"tts-1"` (fast) or `"tts-1-hd"` (high quality).
`format`	string	`"mp3"`	Output format: `mp3`, `opus`, `aac`, `flac`.
`speed`	f32	`1.0`	Speech speed multiplier (0.25 to 4.0).

[tts.elevenlabs] fields:

Field	Type	Default	Description
`voice_id`	string	`"21m00Tcm4TlvDq8ikWAM"`	ElevenLabs voice ID (default: Rachel).
`model_id`	string	`"eleven_monolingual_v1"`	ElevenLabs model ID.
`stability`	f32	`0.5`	Voice stability (0.0–1.0). Higher = more consistent, less expressive.
`similarity_boost`	f32	`0.75`	Voice similarity boost (0.0–1.0).

`[docker]`

Configures the Docker container sandbox for isolated code execution.

[docker]
enabled = false
image = "python:3.12-slim"
container_prefix = "librefang-sandbox"
workdir = "/workspace"
network = "none"
memory_limit = "512m"
cpu_limit = 1.0
timeout_secs = 60
read_only_root = true
mode = "off"
scope = "session"
reuse_cool_secs = 300
idle_timeout_secs = 86400
max_age_secs = 604800
blocked_mounts = []

Field	Type	Default	Description
`enabled`	bool	`false`	Enable Docker sandbox for code execution.
`image`	string	`"python:3.12-slim"`	Docker image to use for the sandbox container.
`container_prefix`	string	`"librefang-sandbox"`	Prefix for container names.
`workdir`	string	`"/workspace"`	Working directory inside the container.
`network`	string	`"none"`	Network mode: `"none"` (isolated), `"bridge"`, or a custom network name.
`memory_limit`	string	`"512m"`	Memory limit (e.g., `"256m"`, `"1g"`).
`cpu_limit`	f64	`1.0`	CPU limit (e.g., `0.5`, `1.0`, `2.0`).
`timeout_secs`	u64	`60`	Maximum execution time per command in seconds.
`read_only_root`	bool	`true`	Mount the root filesystem as read-only.
`mode`	string	`"off"`	Activation mode. See below.
`scope`	string	`"session"`	Container lifecycle scope. See below.
`reuse_cool_secs`	u64	`300`	Cooldown in seconds before a released container can be reused.
`idle_timeout_secs`	u64	`86400`	Destroy containers after this many seconds of inactivity (24 hours default).
`max_age_secs`	u64	`604800`	Maximum container age before forced destruction (7 days default).
`blocked_mounts`	list of strings	`[]`	Host paths blocked from bind mounting into containers.
`cap_add`	list of strings	`[]`	Linux capabilities to add to the container (e.g., `["NET_ADMIN"]`). Use with caution.
`tmpfs`	list of strings	`["/tmp:size=64m"]`	tmpfs mounts inside the container. Each entry is `"path:options"` (e.g., `"/tmp:size=128m"`).
`pids_limit`	u32	`100`	Maximum number of processes inside the container. Prevents fork bombs.

mode values:

Value	Description
`off`	Docker sandbox disabled (default).
`non_main`	Use Docker only for non-main (sub) agents.
`all`	Use Docker for all agents.

scope values:

Value	Description
`session`	One container per session, destroyed when the session ends (default).
`agent`	One container per agent, reused across sessions.
`shared`	Shared container pool across all agents.

`[canvas]`

Configures the Canvas (Agent-to-UI) tool that allows agents to render HTML in the dashboard.

[canvas]
enabled = false
max_html_bytes = 524288
allowed_tags = []

Field	Type	Default	Description
`enabled`	bool	`false`	Enable the canvas tool.
`max_html_bytes`	usize	`524288`	Maximum HTML payload size in bytes (512 KB default).
`allowed_tags`	list of strings	`[]`	Allowed HTML tag names for sanitization. Empty = all safe tags permitted.

`[auto_reply]`

Configures the background auto-reply engine that can automatically respond to incoming messages without waiting for human interaction.

[auto_reply]
enabled = false
max_concurrent = 3
timeout_secs = 120
suppress_patterns = ["/stop", "/pause"]

Field	Type	Default	Description
`enabled`	bool	`false`	Enable the auto-reply engine.
`max_concurrent`	usize	`3`	Maximum number of concurrent auto-reply tasks.
`timeout_secs`	u64	`120`	Default timeout per auto-reply task in seconds.
`suppress_patterns`	list of strings	`["/stop", "/pause"]`	Incoming message patterns that suppress auto-reply.

`[broadcast]`

Configures message broadcasting to route a single incoming message to multiple agents simultaneously.

[broadcast]
strategy = "parallel"
routes = { "announcement-channel" = ["agent-a", "agent-b", "agent-c"] }

Field	Type	Default	Description
`strategy`	string	`"parallel"`	Delivery strategy. `"parallel"` = send to all agents simultaneously; `"sequential"` = send one at a time in order.
`routes`	map of string to list of strings	`{}`	Maps peer/channel identifiers to lists of agent names that receive the message.

`[inbox]`

File-based input inbox for async external commands. Drop text files into a watched directory and they are dispatched as messages to agents. Processed files are moved to a processed/ subdirectory to avoid redelivery.

[inbox]
enabled = true
directory = "~/.librefang/inbox/"
poll_interval_secs = 5
default_agent = "assistant"

Field	Type	Default	Description
`enabled`	bool	`false`	Enable the inbox directory watcher.
`directory`	string or null	`null`	Directory to watch. Defaults to `$HOME_DIR/inbox/`. Supports `~` expansion.
`poll_interval_secs`	u64	`5`	How often (in seconds) to scan the directory for new files. Minimum 1.
`default_agent`	string or null	`null`	Agent name to route files to when no `agent:` directive is found in the file.

File format: Plain text files (.txt, .md, .json, .py, etc.). The first line may contain an agent:<name> directive to target a specific agent; the rest is sent as the message body. Files without the directive use default_agent.

Safety limits: Files larger than 1 MB are skipped. Binary files (non-text extensions) are skipped. Empty files are moved to processed/ without sending.

Usage examples:

Target a specific agent:

cat > ~/.librefang/inbox/task.txt << 'EOF'
agent:code-reviewer
Please review this code for security issues:

def login(user, password):
    query = f"SELECT * FROM users WHERE name='{user}' AND pass='{password}'"
    return db.execute(query)
EOF

Send to the default agent:

echo "Summarize today's system logs" > ~/.librefang/inbox/summarize.txt

Cron job:

# crontab -e
0 9 * * * grep ERROR /var/log/app.log > ~/.librefang/inbox/daily_errors.txt

CI/CD post-build:

echo "agent:devops
Build failed, please analyze:
$(tail -100 build.log)" > ~/.librefang/inbox/build_$(date +%s).txt

Batch processing:

for doc in ~/reports/*.md; do
  cp "$doc" ~/.librefang/inbox/
done

Check inbox status:

curl -s http://127.0.0.1:4545/api/inbox/status
# {"enabled":true,"pending_count":3,"processed_count":12,...}

`[[bindings]]`

Agent bindings route specific channel/account/peer combinations to specific agents. More specific bindings (more non-null fields) take priority over less specific ones.

[[bindings]]
agent = "support-agent"
[bindings.match_rule]
channel = "telegram"
guild_id = "123456"

[[bindings]]
agent = "vip-agent"
[bindings.match_rule]
channel = "discord"
peer_id = "987654321"
roles = ["premium"]

Top-level fields:

Field	Type	Description
`agent`	string	Target agent name or ID to route matched messages to.
`match_rule`	object	Match criteria. All specified (non-null) fields must match.

match_rule fields:

Field	Type	Default	Description
`channel`	string or null	`null`	Channel type to match (e.g., `"discord"`, `"telegram"`, `"slack"`).
`account_id`	string or null	`null`	Specific bot account ID within the channel (for multi-bot setups).
`peer_id`	string or null	`null`	User/peer ID for DM routing.
`guild_id`	string or null	`null`	Guild or server ID (Discord/Slack).
`roles`	list of strings	`[]`	Role-based routing; user must have at least one of these roles.

Specificity scoring (higher = matched first): peer_id (+8) > guild_id (+4) > roles (+2) = account_id (+2) > channel (+1).

`[pairing]`

Configures device pairing for the LibreFang mobile companion app and push notifications.

[pairing]
enabled = false
max_devices = 10
token_expiry_secs = 300
push_provider = "ntfy"
ntfy_url = "https://ntfy.sh"
ntfy_topic = "my-librefang-notifications"

Field	Type	Default	Description
`enabled`	bool	`false`	Enable device pairing.
`max_devices`	usize	`10`	Maximum number of paired devices.
`token_expiry_secs`	u64	`300`	Pairing token validity in seconds (5 minutes default).
`push_provider`	string	`"none"`	Push notification provider: `"none"`, `"ntfy"`, or `"gotify"`.
`ntfy_url`	string or null	`null`	ntfy server URL (when `push_provider = "ntfy"`).
`ntfy_topic`	string or null	`null`	ntfy topic for push notifications.

`[extensions]`

Configures MCP server reconnection behavior and health monitoring.

[extensions]
auto_reconnect = true
reconnect_max_attempts = 10
reconnect_max_backoff_secs = 300
health_check_interval_secs = 60

Field	Type	Default	Description
`auto_reconnect`	bool	`true`	Automatically reconnect to MCP servers when they disconnect.
`reconnect_max_attempts`	u32	`10`	Maximum reconnect attempts before giving up permanently.
`reconnect_max_backoff_secs`	u64	`300`	Maximum backoff duration in seconds between reconnect attempts.
`health_check_interval_secs`	u64	`60`	Interval in seconds between health checks for connected extensions.

`[vault]`

Configures the encrypted credential vault for storing sensitive secrets.

[vault]
enabled = true
# path = "~/.librefang/vault.enc"

Field	Type	Default	Description
`enabled`	bool	`true`	Enable the credential vault. Auto-detected if `vault.enc` already exists.
`path`	path or null	`null`	Custom vault file path. Defaults to `~/.librefang/vault.enc`.

`[webhook_triggers]`

Enables external systems to trigger agent actions via authenticated HTTP webhooks at /hooks/wake and /hooks/agent.

[webhook_triggers]
enabled = true
token_env = "LIBREFANG_WEBHOOK_TOKEN"
max_payload_bytes = 65536
rate_limit_per_minute = 30

Field	Type	Default	Description
`enabled`	bool	`false`	Enable webhook trigger endpoints.
`token_env`	string	`"LIBREFANG_WEBHOOK_TOKEN"`	Env var name holding the bearer token (NOT the token itself). Token must be ≥ 32 characters. Required when `enabled = true`.
`max_payload_bytes`	usize	`65536`	Maximum incoming payload size in bytes (64 KB default).
`rate_limit_per_minute`	u32	`30`	Maximum webhook requests per minute per source IP.

`[proxy]`

Configures HTTP proxy for all outbound connections (LLM APIs, web search, MCP servers, etc.). Environment variables HTTP_PROXY, HTTPS_PROXY, and NO_PROXY are also respected as fallbacks.

[proxy]
http_proxy = "http://proxy.corp.example:8080"
https_proxy = "http://proxy.corp.example:8080"
no_proxy = "localhost,127.0.0.1,.internal.corp"

Field	Type	Default	Description
`http_proxy`	string or null	`null`	HTTP proxy URL. Falls back to `HTTP_PROXY` / `http_proxy` env var. Credentials in URLs are redacted in logs.
`https_proxy`	string or null	`null`	HTTPS proxy URL. Falls back to `HTTPS_PROXY` / `https_proxy` env var.
`no_proxy`	string or null	`null`	Comma-separated list of hosts/domains that bypass the proxy. Falls back to `NO_PROXY` / `no_proxy` env var.

`[[sidecar_channels]]`

Sidecar channel adapters allow external processes (written in any language) to act as channel adapters. Communication uses newline-delimited JSON over stdin/stdout.

[[sidecar_channels]]
name = "my-custom-channel"
command = "python3"
args = ["adapters/my_adapter.py"]
channel_type = "custom_platform"
[sidecar_channels.env]
MY_API_TOKEN = "secret"

Field	Type	Default	Description
`name`	string	required	Display name for this adapter.
`command`	string	required	Executable to run (e.g., `"python3"`, `"/usr/local/bin/my-adapter"`).
`args`	list of strings	`[]`	Arguments to pass to the command.
`env`	map of string to string	`{}`	Extra environment variables to pass to the subprocess.
`channel_type`	string or null	`null`	Channel type identifier. Defaults to `Custom(<name>)` if null.

`[session]`

Configures automatic cleanup of idle or excess sessions.

[session]
retention_days = 30
max_sessions_per_agent = 100
cleanup_interval_hours = 24

Field	Type	Default	Description
`retention_days`	u32	`0`	Maximum age in days for idle sessions before automatic cleanup. `0` = unlimited.
`max_sessions_per_agent`	u32	`0`	Maximum number of sessions per agent (oldest pruned first). `0` = unlimited.
`cleanup_interval_hours`	u32	`24`	How often the background cleanup job runs in hours.

`[queue]`

Configures the agent command queue, including depth limits, TTL, and per-lane concurrency.

[queue]
max_depth_per_agent = 100
max_depth_global = 1000
task_ttl_secs = 3600

[queue.concurrency]
main_lane = 3
cron_lane = 2
subagent_lane = 3

[queue] fields:

Field	Type	Default	Description
`max_depth_per_agent`	u32	`0`	Maximum queued tasks per agent. New tasks are rejected when full. `0` = unlimited.
`max_depth_global`	u32	`0`	Maximum total queued tasks across all agents. `0` = unlimited.
`task_ttl_secs`	u64	`3600`	Unprocessed tasks expire after this many seconds. `0` = unlimited.

[queue.concurrency] fields:

Field	Type	Default	Description
`main_lane`	usize	`3`	Concurrent user message tasks.
`cron_lane`	usize	`2`	Concurrent scheduled cron job tasks.
`subagent_lane`	usize	`3`	Concurrent subagent invocation tasks.

`[external_auth]`

Configures OAuth2/OIDC external authentication, allowing users to log in via identity providers like Google, GitHub, Okta, Auth0, or Keycloak.

[external_auth]
enabled = true
issuer_url = "https://accounts.google.com"
client_id = "your-client-id.apps.googleusercontent.com"
client_secret_env = "LIBREFANG_OAUTH_CLIENT_SECRET"
redirect_url = "http://127.0.0.1:4545/api/auth/callback"
scopes = ["openid", "profile", "email"]
allowed_domains = ["example.com"]
session_ttl_secs = 86400

Field	Type	Default	Description
`enabled`	bool	`false`	Enable external authentication.
`issuer_url`	string	`""`	OIDC issuer URL for provider discovery at `{issuer_url}/.well-known/openid-configuration`.
`client_id`	string	`""`	OAuth2 client ID registered with the identity provider.
`client_secret_env`	string	`"LIBREFANG_OAUTH_CLIENT_SECRET"`	Env var name holding the OAuth2 client secret.
`redirect_url`	string	`"http://127.0.0.1:4545/api/auth/callback"`	OAuth2 authorization code flow callback URL.
`scopes`	list of strings	`["openid","profile","email"]`	OAuth2 scopes to request.
`allowed_domains`	list of strings	`[]`	Restrict login to these email domains. Empty = allow all.
`audience`	string	`""`	JWT audience claim to validate. Defaults to `client_id` if empty.
`session_ttl_secs`	u64	`86400`	Session token lifetime in seconds (24 hours default).
`providers`	list of objects	`[]`	Multiple OIDC/OAuth2 providers. When configured, takes precedence over the single-provider fields above.

For multi-provider setups, use [[external_auth.providers]] with fields: id, display_name, issuer_url, auth_url, token_url, userinfo_url, jwks_uri, client_id, client_secret_env, redirect_url, scopes, allowed_domains, audience.

`[vertex_ai]`

Configures Google Cloud Vertex AI as an LLM provider.

[vertex_ai]
project_id = "my-gcp-project"
region = "us-central1"
credentials_path = "/path/to/service-account.json"

Credentials are resolved in this order:

credentials_path in config (JSON string or file path)
VERTEX_AI_SERVICE_ACCOUNT_JSON env var
GOOGLE_APPLICATION_CREDENTIALS env var (file path)
gcloud auth print-access-token CLI fallback

Field	Type	Default	Description
`project_id`	string or null	`null`	GCP project ID. Falls back to `VERTEX_AI_PROJECT_ID`, `GOOGLE_CLOUD_PROJECT`, or the `project_id` field in the service account JSON.
`region`	string or null	`null`	GCP region for the Vertex AI endpoint. Falls back to `VERTEX_AI_REGION` or `GOOGLE_CLOUD_REGION` env var. Default: `"us-central1"`.
`credentials_path`	string or null	`null`	Path to a GCP service account JSON key file, or the raw JSON string.

`[oauth]`

Configures OAuth client IDs for PKCE (Proof Key for Code Exchange) flows used by the dashboard.

[oauth]
google_client_id = "your-google-client-id.apps.googleusercontent.com"
github_client_id = "your-github-app-client-id"
microsoft_client_id = "your-azure-app-client-id"
slack_client_id = "your-slack-app-client-id"

Field	Type	Default	Description
`google_client_id`	string or null	`null`	Google OAuth2 client ID for PKCE flow.
`github_client_id`	string or null	`null`	GitHub OAuth app client ID for PKCE flow.
`microsoft_client_id`	string or null	`null`	Microsoft (Entra ID / Azure AD) OAuth application client ID.
`slack_client_id`	string or null	`null`	Slack OAuth app client ID.

`[auth_profiles]`

Configures multiple API key profiles per provider to enable key rotation when one key is rate-limited or exhausted.

[auth_profiles]
anthropic = [
  {name = "primary", api_key_env = "ANTHROPIC_API_KEY_1", priority = 0},
  {name = "secondary", api_key_env = "ANTHROPIC_API_KEY_2", priority = 1},
]
openai = [
  {name = "main", api_key_env = "OPENAI_API_KEY", priority = 0},
]

The value is a map from provider name to a list of AuthProfile objects:

Field	Type	Default	Description
`name`	string	required	Profile name (e.g., `"primary"`, `"secondary"`).
`api_key_env`	string	required	Env var name holding the API key for this profile.
`priority`	u32	`0`	Priority for key selection. Lower value = preferred.

`[tool_policy]`

Configures global tool access rules, groups, and recursion depth limits. References the ToolPolicy type.

[tool_policy]
subagent_max_depth = 10
subagent_max_concurrent = 5

[[tool_policy.global_rules]]
pattern = "shell_*"
effect = "deny"

[[tool_policy.groups]]
name = "web_tools"
tools = ["web_search", "web_fetch"]

Field	Type	Default	Description
`agent_rules`	list of ToolPolicyRule	`[]`	Per-agent tool rules (highest priority, checked first).
`global_rules`	list of ToolPolicyRule	`[]`	Global tool rules applied to all agents (checked after agent rules).
`groups`	list of ToolGroup	`[]`	Named tool groups for reuse in rules.
`subagent_max_depth`	u32	`10`	Maximum subagent spawning depth.
`subagent_max_concurrent`	u32	`5`	Maximum concurrent subagents.

ToolPolicyRule fields:

Field	Type	Description
`pattern`	string	Glob pattern to match tool names (e.g., `"shell_"`, `"web_"`, `"mcp_github_*"`).
`effect`	string	`"allow"` or `"deny"`. Deny-wins: if any deny rule matches, the tool is blocked regardless of allow rules.

ToolGroup fields:

Field	Type	Description
`name`	string	Group name (e.g., `"web_tools"`, `"code_tools"`).
`tools`	list of strings	Tool name patterns included in this group.

`[proactive_memory]`

Configures proactive memory extraction (mem0-style automatic memory management). References the ProactiveMemoryConfig type.

[proactive_memory]
enabled = true
auto_memorize = true
auto_retrieve = true
max_retrieve = 10
extraction_threshold = 0.7
# extraction_model = "gpt-4o-mini"  # optional, enables LLM-powered extraction
extract_categories = ["user_preference", "important_fact", "task_context", "relationship"]
session_ttl_hours = 24
duplicate_threshold = 0.5
confidence_decay_rate = 0.01
max_memories_per_agent = 1000

Field	Type	Default	Description
`enabled`	bool	`true`	Master toggle — when `false`, the entire proactive memory subsystem is disabled.
`auto_memorize`	bool	`true`	Automatically extract and store memories after each agent execution.
`auto_retrieve`	bool	`true`	Automatically retrieve relevant memories before each agent execution.
`max_retrieve`	usize	`10`	Maximum number of memories to retrieve per query.
`extraction_threshold`	f32	`0.7`	Confidence threshold for near-duplicate detection (0.0–1.0).
`extraction_model`	string or null	`null`	LLM model to use for extraction. If `null`, uses rule-based extraction.
`extract_categories`	list of strings	`["user_preference", "important_fact", "task_context", "relationship"]`	Categories to extract from conversations.
`session_ttl_hours`	u32	`24`	Session memory TTL in hours. Memories older than this are cleaned up before each agent execution.
`duplicate_threshold`	f32	`0.5`	Similarity threshold for duplicate detection (0.0–1.0). Uses vector cosine similarity when embeddings are available, otherwise falls back to Jaccard word overlap.
`confidence_decay_rate`	f64	`0.01`	Confidence decay rate per day. Follows exponential decay: `conf × e^(−rate × days)`. Default of `0.01` takes ~70 days to halve.
`max_memories_per_agent`	usize	`1000`	Maximum memories per agent. When exceeded, oldest/lowest-confidence entries are evicted. `0` = no cap.

`[context_engine]`

Configures the pluggable context assembly engine that controls how agent memory is recalled and assembled into prompts.

[context_engine]
engine = "default"
# plugin = "qdrant-recall"    # resolves to ~/.librefang/plugins/qdrant-recall/

[context_engine.hooks]
# ingest = "~/.librefang/scripts/my_recall.py"
# after_turn = "~/.librefang/scripts/my_indexer.py"

[[context_engine.plugin_registries]]
name = "Official"
github_repo = "librefang/librefang-registry"

Field	Type	Default	Description
`engine`	string	`"default"`	Built-in engine name. Currently only `"default"` is supported.
`plugin`	string or null	`null`	Plugin name. Resolves to `~/.librefang/plugins/<name>/plugin.toml`. Takes precedence over manual `hooks` if set.
`hooks.ingest`	string or null	`null`	Python script path for the `ingest` hook (called on new user message).
`hooks.after_turn`	string or null	`null`	Python script path for the `after_turn` hook (called after each completed turn).
`plugin_registries`	list of objects	Official registry	Plugin registries (GitHub `owner/repo`) to browse for installable plugins.

`[audit]`

Configures audit log retention.

[audit]
retention_days = 90

Field	Type	Default	Description
`retention_days`	u32	`90`	Number of days to retain audit log entries. `0` = unlimited retention.

`[health_check]`

Configures periodic health checks for LLM providers.

[health_check]
health_check_interval_secs = 60

Field	Type	Default	Description
`health_check_interval_secs`	u64	`60`	Interval in seconds between provider health checks.

`[plugins]`

Configures additional plugin registries to search for installable context engine plugins.

[plugins]
plugin_registries = ["acme-corp/librefang-plugins"]

Field	Type	Default	Description
`plugin_registries`	list of strings	`[]`	Additional GitHub `owner/repo` plugin registries. Merged with `context_engine.plugin_registries`.

Environment Variables

Complete table of all environment variables referenced by the configuration. None of these are read by the config file itself -- they are read at runtime by the kernel and channel adapters.

LLM Provider Keys

Variable	Used By	Description
`ANTHROPIC_API_KEY`	`[default_model]`	Anthropic API key (Claude models).
`GEMINI_API_KEY`	Gemini driver	Google Gemini API key. Alias: `GOOGLE_API_KEY`.
`OPENAI_API_KEY`	OpenAI-compat driver	OpenAI API key.
`GROQ_API_KEY`	Groq provider	Groq API key (fast Llama inference).
`DEEPSEEK_API_KEY`	DeepSeek provider	DeepSeek API key.
`PERPLEXITY_API_KEY`	Perplexity provider / web search	Perplexity API key.
`OPENROUTER_API_KEY`	OpenRouter provider	OpenRouter API key.
`TOGETHER_API_KEY`	Together AI provider	Together AI API key.
`MISTRAL_API_KEY`	Mistral provider	Mistral AI API key.
`FIREWORKS_API_KEY`	Fireworks provider	Fireworks AI API key.
`COHERE_API_KEY`	Cohere provider	Cohere API key.
`AI21_API_KEY`	AI21 provider	AI21 Labs API key.
`CEREBRAS_API_KEY`	Cerebras provider	Cerebras API key.
`SAMBANOVA_API_KEY`	SambaNova provider	SambaNova API key.
`HUGGINGFACE_API_KEY`	Hugging Face provider	Hugging Face Inference API key.
`XAI_API_KEY`	xAI provider	xAI (Grok) API key.
`REPLICATE_API_KEY`	Replicate provider	Replicate API key.

Web Search Keys

Variable	Used By	Description
`BRAVE_API_KEY`	`[web.brave]`	Brave Search API key.
`TAVILY_API_KEY`	`[web.tavily]`	Tavily Search API key.
`PERPLEXITY_API_KEY`	`[web.perplexity]`	Perplexity Search API key (shared with LLM provider).

Channel Tokens

Variable	Channel	Description
`TELEGRAM_BOT_TOKEN`	Telegram	Bot API token from @BotFather.
`DISCORD_BOT_TOKEN`	Discord	Discord bot token.
`SLACK_APP_TOKEN`	Slack	Slack app-level token (`xapp-`) for Socket Mode.
`SLACK_BOT_TOKEN`	Slack	Slack bot token (`xoxb-`) for REST API.
`WHATSAPP_ACCESS_TOKEN`	WhatsApp	WhatsApp Cloud API access token.
`WHATSAPP_VERIFY_TOKEN`	WhatsApp	Webhook verification token.
`MATRIX_ACCESS_TOKEN`	Matrix	Matrix homeserver access token.
`EMAIL_PASSWORD`	Email	Email account password or app password.
`TEAMS_APP_PASSWORD`	Teams	Azure Bot Framework app password.
`MATTERMOST_TOKEN`	Mattermost	Mattermost bot token.
`TWITCH_OAUTH_TOKEN`	Twitch	Twitch OAuth token.
`ROCKETCHAT_TOKEN`	Rocket.Chat	Rocket.Chat auth token.
`ZULIP_API_KEY`	Zulip	Zulip bot API key.
`XMPP_PASSWORD`	XMPP	XMPP account password.
`GOOGLE_CHAT_SERVICE_ACCOUNT`	Google Chat	Service account JSON key.
`LINE_CHANNEL_SECRET`	LINE	LINE channel secret.
`LINE_CHANNEL_ACCESS_TOKEN`	LINE	LINE channel access token.
`VIBER_AUTH_TOKEN`	Viber	Viber Bot auth token.
`MESSENGER_PAGE_TOKEN`	Messenger	Facebook page access token.
`MESSENGER_VERIFY_TOKEN`	Messenger	Webhook verification token.
`REDDIT_CLIENT_SECRET`	Reddit	Reddit app client secret.
`REDDIT_PASSWORD`	Reddit	Reddit bot account password.
`MASTODON_ACCESS_TOKEN`	Mastodon	Mastodon access token.
`BLUESKY_APP_PASSWORD`	Bluesky	Bluesky app password.
`FEISHU_APP_SECRET`	Feishu	Feishu/Lark app secret.
`REVOLT_BOT_TOKEN`	Revolt	Revolt bot token.
`NEXTCLOUD_TOKEN`	Nextcloud	Nextcloud Talk auth token.
`GUILDED_BOT_TOKEN`	Guilded	Guilded bot token.
`KEYBASE_PAPERKEY`	Keybase	Keybase paper key.
`THREEMA_SECRET`	Threema	Threema Gateway API secret.
`NOSTR_PRIVATE_KEY`	Nostr	Nostr private key (nsec or hex).
`WEBEX_BOT_TOKEN`	Webex	Webex bot token.
`PUMBLE_BOT_TOKEN`	Pumble	Pumble bot token.
`FLOCK_BOT_TOKEN`	Flock	Flock bot token.
`TWIST_TOKEN`	Twist	Twist API token.
`MUMBLE_PASSWORD`	Mumble	Mumble server password.
`DINGTALK_ACCESS_TOKEN`	DingTalk	DingTalk webhook access token.
`DINGTALK_SECRET`	DingTalk	DingTalk signing secret.
`DISCOURSE_API_KEY`	Discourse	Discourse API key.
`GITTER_TOKEN`	Gitter	Gitter auth token.
`NTFY_TOKEN`	ntfy	ntfy auth token (optional for public topics).
`GOTIFY_APP_TOKEN`	Gotify	Gotify app token (sending).
`GOTIFY_CLIENT_TOKEN`	Gotify	Gotify client token (receiving).
`WEBHOOK_SECRET`	Webhook	HMAC signing secret for webhook verification.
`LINKEDIN_ACCESS_TOKEN`	LinkedIn	LinkedIn OAuth2 access token.

Validation

KernelConfig::validate() runs at boot time and returns a list of warnings (non-fatal). The kernel still starts, but logs each warning.

What is validated

For every enabled channel (i.e., its config section is present in the TOML), the validator checks that the corresponding environment variable(s) are set and non-empty:

Channel	Env vars checked
Telegram	`bot_token_env`
Discord	`bot_token_env`
Slack	`app_token_env`, `bot_token_env` (both checked)
WhatsApp	`access_token_env`
Matrix	`access_token_env`
Email	`password_env`
Teams	`app_password_env`
Mattermost	`token_env`
Zulip	`api_key_env`
Twitch	`oauth_token_env`
Rocket.Chat	`token_env`
Google Chat	`service_account_env`
XMPP	`password_env`
LINE	`access_token_env`
Viber	`auth_token_env`
Messenger	`page_token_env`
Reddit	`client_secret_env`
Mastodon	`access_token_env`
Bluesky	`app_password_env`
Feishu	`app_secret_env`
Revolt	`bot_token_env`
Nextcloud	`token_env`
Guilded	`bot_token_env`
Keybase	`paperkey_env`
Threema	`secret_env`
Nostr	`private_key_env`
Webex	`bot_token_env`
Pumble	`bot_token_env`
Flock	`bot_token_env`
Twist	`token_env`
Mumble	`password_env`
DingTalk	`access_token_env`
Discourse	`api_key_env`
Gitter	`token_env`
ntfy	`token_env` (only if `token_env` is non-empty; public topics are OK without auth)
Gotify	`app_token_env`
Webhook	`secret_env`
LinkedIn	`access_token_env`

For web search providers, the validator checks:

Provider	Env var checked
`brave`	`web.brave.api_key_env`
`tavily`	`web.tavily.api_key_env`
`perplexity`	`web.perplexity.api_key_env`
`duckduckgo`	(no check -- no API key needed)
`auto`	(no check -- cascading fallback handles missing keys)

What is NOT validated

The api_key_env in [default_model] is not checked by validate(). Missing LLM keys cause errors at runtime when the driver is first used.
The shared_secret in [network] is not validated against network_enabled. If networking is enabled with an empty secret, authentication will fail at connection time.
MCP server configurations are not validated at config load time. Connection errors surface during the background MCP connect phase.
Agent manifests have their own separate validation.

Some subsystems have their own configuration that is not part of config.toml but is worth noting:

Session Compaction (runtime)

Configured internally via CompactionConfig (not currently exposed in config.toml):

Field	Default	Description
`threshold`	`80`	Compact when session message count exceeds this.
`keep_recent`	`20`	Number of recent messages preserved verbatim after compaction.
`max_summary_tokens`	`1024`	Maximum tokens for the LLM summary of compacted messages.

WASM Sandbox (runtime)

Configured internally via SandboxConfig (not currently exposed in config.toml):

Field	Default	Description
`fuel_limit`	`1000000`	Maximum CPU instruction budget. `0` = unlimited.
`max_memory_bytes`	`16777216` (16 MB)	Maximum WASM linear memory.
`timeout_secs`	`null` (30s fallback)	Wall-clock timeout for epoch-based interruption.

Model Routing (per-agent manifest)

Configured in agent manifests via ModelRoutingConfig:

Field	Default	Description
`simple_model`	`"claude-haiku-4-5-20251001"`	Model for simple queries.
`medium_model`	`"claude-sonnet-4-20250514"`	Model for medium-complexity queries.
`complex_model`	`"claude-sonnet-4-20250514"`	Model for complex queries.
`simple_threshold`	`100`	Token count below which a query is classified as simple.
`complex_threshold`	`500`	Token count above which a query is classified as complex.

Autonomous Guardrails (per-agent manifest)

Configured in agent manifests via AutonomousConfig:

Field	Default	Description
`quiet_hours`	`null`	Cron expression for quiet hours (agent pauses during this window).
`max_iterations`	`50`	Maximum tool-use iterations per invocation.
`max_restarts`	`10`	Maximum automatic restarts before permanent stop.
`heartbeat_interval_secs`	`30`	Seconds between heartbeat health checks.
`heartbeat_channel`	`null`	Channel to send heartbeat status to (e.g., `"telegram"`).