LibreFang Configuration Reference
Complete reference for config.toml, covering every configurable field in the LibreFang Agent OS.
LibreFang reads its configuration from a single TOML file:
~ /.librefang/config.toml Copied! 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.
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" Copied! 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 = "" Copied! # ============================================================ # 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:50051" # HTTP/WS API bind address network_enabled = false # Enable OFP peer-to-peer network api_key = "" # API Bearer token (empty = unauthenticated) mode = "default" # stable | default | dev language = "en" # Locale for CLI/messages usage_footer = "full" # off | tokens | cost | full # --- 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 # --- 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" # --- A2A Protocol --- [ a2a ] enabled = false 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 40 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 = 33280 [ channels . slack ] app_token_env = "SLACK_APP_TOKEN" bot_token_env = "SLACK_BOT_TOKEN" allowed_channels = [] Copied! Top-Level Fields
These fields sit at the root of config.toml (not inside any [section]).
Field Type Default Description home_dirpath ~/.librefangLibreFang home directory. Stores config, agents, skills. data_dirpath ~/.librefang/dataDirectory for SQLite databases and persistent data. log_levelstring "info"Log verbosity. One of: trace, debug, info, warn, error. api_listenstring "127.0.0.1:50051"Bind address for the HTTP/WebSocket/SSE API server. network_enabledbool falseEnable the OFP peer-to-peer network layer. api_keystring "" (empty)API authentication key. When set, all endpoints except /api/health require Authorization: Bearer <key>. Empty means unauthenticated (local development only). modestring "default"Kernel operating mode. See below. languagestring "en"Language/locale code for CLI output and system messages. usage_footerstring "full"Controls usage info appended to responses. See below.
mode values:
Value Behavior stableConservative: no auto-updates, pinned models, frozen skill registry. Uses FallbackDriver. defaultBalanced: standard operation. devDeveloper: experimental features enabled.
usage_footer values:
Value Behavior offNo usage information shown. tokensShow token counts only. costShow estimated cost only. fullShow 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" Copied! Field Type Default Description providerstring "anthropic"Provider name. Supported: anthropic, gemini, openai, groq, openrouter, deepseek, together, mistral, fireworks, ollama, vllm, lmstudio, perplexity, cohere, ai21, cerebras, sambanova, huggingface, xai, replicate. modelstring "claude-sonnet-4-20250514"Model identifier. Aliases like sonnet, haiku, gpt-4o, gemini-flash are resolved by the model catalog. api_key_envstring "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_urlstring or null nullOverride 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 Copied! Field Type Default Description sqlite_pathpath or null nullExplicit path to the SQLite database file. When null, defaults to {data_dir}/librefang.db. embedding_modelstring "all-MiniLM-L6-v2"Model name used for generating vector embeddings for semantic memory search. consolidation_thresholdu64 10000Number of stored memories before automatic consolidation is triggered to merge and prune old entries. decay_ratef32 0.1Memory 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" Copied! Field Type Default Description listen_addresseslist of strings ["/ip4/0.0.0.0/tcp/0"]libp2p multiaddresses to listen on. Port 0 means auto-assign. bootstrap_peerslist of strings []Multiaddresses of bootstrap peers for DHT discovery. mdns_enabledbool trueEnable mDNS for automatic local network peer discovery. max_peersu32 50Maximum number of simultaneously connected peers. shared_secretstring "" (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 Copied! Field Type Default Description search_providerstring "auto"Which search engine to use. See values below. cache_ttl_minutesu64 15Cache duration for search/fetch results in minutes. 0 = caching disabled.
search_provider values:
Value Description autoCascading fallback: tries Tavily, then Brave, then Perplexity, then DuckDuckGo, based on which API keys are available. braveBrave Search API. Requires BRAVE_API_KEY. tavilyTavily AI-native search. Requires TAVILY_API_KEY. perplexityPerplexity AI search. Requires PERPLEXITY_API_KEY. duckduckgoDuckDuckGo HTML scraping. No API key needed.
[web.brave][ web . brave ] api_key_env = "BRAVE_API_KEY" max_results = 5 country = "" search_lang = "" freshness = "" Copied! Field Type Default Description api_key_envstring "BRAVE_API_KEY"Environment variable name holding the Brave Search API key. max_resultsusize 5Maximum number of search results to return. countrystring ""Country code for localized results (e.g., "US", "GB"). Empty = no filter. search_langstring ""Language code (e.g., "en", "fr"). Empty = no filter. freshnessstring ""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 Copied! Field Type Default Description api_key_envstring "TAVILY_API_KEY"Environment variable name holding the Tavily API key. search_depthstring "basic"Search depth: "basic" for fast results, "advanced" for deeper analysis. max_resultsusize 5Maximum number of search results to return. include_answerbool trueWhether to include Tavily's AI-generated answer summary in results.
[web.perplexity][ web . perplexity ] api_key_env = "PERPLEXITY_API_KEY" model = "sonar" Copied! Field Type Default Description api_key_envstring "PERPLEXITY_API_KEY"Environment variable name holding the Perplexity API key. modelstring "sonar"Perplexity model to use for search queries.
[web.fetch][ web . fetch ] max_chars = 50000 max_response_bytes = 10485760 timeout_secs = 30 readability = true Copied! Field Type Default Description max_charsusize 50000Maximum characters returned in fetched content. Content exceeding this is truncated. max_response_bytesusize 10485760 (10 MB)Maximum HTTP response body size in bytes. timeout_secsu64 30HTTP request timeout in seconds. readabilitybool trueEnable HTML-to-Markdown readability extraction. When true, fetched HTML is converted to clean Markdown.
[channels]All 40 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.
Every channel config includes a default_agent field (optional agent name to route messages to) and an overrides sub-table (see Channel Overrides ).
[channels.telegram][ channels . telegram ] bot_token_env = "TELEGRAM_BOT_TOKEN" allowed_users = [] # default_agent = "assistant" poll_interval_secs = 1 Copied! Field Type Default Description bot_token_envstring "TELEGRAM_BOT_TOKEN"Env var holding the Telegram Bot API token. allowed_userslist of i64 []Telegram user IDs allowed to interact. Empty = allow all. default_agentstring or null nullAgent name to route messages to. poll_interval_secsu64 1Long-polling interval in seconds.
[channels.discord][ channels . discord ] bot_token_env = "DISCORD_BOT_TOKEN" allowed_guilds = [] # default_agent = "assistant" intents = 33280 Copied! Field Type Default Description bot_token_envstring "DISCORD_BOT_TOKEN"Env var holding the Discord bot token. allowed_guildslist of u64 []Guild (server) IDs allowed. Empty = allow all. default_agentstring or null nullAgent name to route messages to. intentsu64 33280Gateway intents bitmask. Default = GUILD_MESSAGES | MESSAGE_CONTENT.
[channels.slack][ channels . slack ] app_token_env = "SLACK_APP_TOKEN" bot_token_env = "SLACK_BOT_TOKEN" allowed_channels = [] Copied! Field Type Default Description app_token_envstring "SLACK_APP_TOKEN"Env var holding the Slack app-level token (xapp-) for Socket Mode. bot_token_envstring "SLACK_BOT_TOKEN"Env var holding the Slack bot token (xoxb-) for REST API. allowed_channelslist of strings []Channel IDs allowed. Empty = allow all. default_agentstring or null nullAgent name to route messages to.
[channels.whatsapp][ channels . whatsapp ] access_token_env = "WHATSAPP_ACCESS_TOKEN" verify_token_env = "WHATSAPP_VERIFY_TOKEN" phone_number_id = "" webhook_port = 8443 allowed_users = [] Copied! Field Type Default Description access_token_envstring "WHATSAPP_ACCESS_TOKEN"Env var holding the WhatsApp Cloud API access token. verify_token_envstring "WHATSAPP_VERIFY_TOKEN"Env var holding the webhook verification token. phone_number_idstring ""WhatsApp Business phone number ID. webhook_portu16 8443Port to listen for incoming webhook callbacks. allowed_userslist of strings []Phone numbers allowed. Empty = allow all. default_agentstring or null nullAgent name to route messages to.
[channels.signal][ channels . signal ] api_url = "http://localhost:8080" phone_number = "" allowed_users = [] Copied! Field Type Default Description api_urlstring "http://localhost:8080"URL of the signal-cli REST API. phone_numberstring ""Registered phone number for the bot. allowed_userslist of strings []Allowed phone numbers. Empty = allow all. default_agentstring or null nullAgent 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 = [] Copied! Field Type Default Description homeserver_urlstring "https://matrix.org"Matrix homeserver URL. user_idstring ""Bot user ID (e.g., "@librefang:matrix.org"). access_token_envstring "MATRIX_ACCESS_TOKEN"Env var holding the Matrix access token. allowed_roomslist of strings []Room IDs to listen in. Empty = all joined rooms. default_agentstring or null nullAgent 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 = [] Copied! Field Type Default Description imap_hoststring ""IMAP server hostname. imap_portu16 993IMAP server port (993 for TLS). smtp_hoststring ""SMTP server hostname. smtp_portu16 587SMTP server port (587 for STARTTLS). usernamestring ""Email address for both IMAP and SMTP. password_envstring "EMAIL_PASSWORD"Env var holding the email password or app password. poll_interval_secsu64 30IMAP polling interval in seconds. folderslist of strings ["INBOX"]IMAP folders to monitor. allowed_senderslist of strings []Only process emails from these senders. Empty = all. default_agentstring or null nullAgent name to route messages to.
[channels.teams][ channels . teams ] app_id = "" app_password_env = "TEAMS_APP_PASSWORD" webhook_port = 3978 allowed_tenants = [] Copied! Field Type Default Description app_idstring ""Azure Bot App ID. app_password_envstring "TEAMS_APP_PASSWORD"Env var holding the Azure Bot Framework app password. webhook_portu16 3978Port for the Bot Framework incoming webhook. allowed_tenantslist of strings []Azure AD tenant IDs allowed. Empty = allow all. default_agentstring or null nullAgent name to route messages to.
[channels.mattermost][ channels . mattermost ] server_url = "https://mattermost.example.com" token_env = "MATTERMOST_TOKEN" allowed_channels = [] Copied! Field Type Default Description server_urlstring ""Mattermost server URL. token_envstring "MATTERMOST_TOKEN"Env var holding the Mattermost bot token. allowed_channelslist of strings []Channel IDs to listen in. Empty = all. default_agentstring or null nullAgent 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 Copied! Field Type Default Description serverstring "irc.libera.chat"IRC server hostname. portu16 6667IRC server port. nickstring "librefang"Bot nickname. password_envstring or null nullEnv var holding the server password (optional). channelslist of strings []IRC channels to join (e.g., ["#librefang", "#general"]). use_tlsbool falseUse TLS for the connection. default_agentstring or null nullAgent name to route messages to.
[channels.google_chat][ channels . google_chat ] service_account_env = "GOOGLE_CHAT_SERVICE_ACCOUNT" space_ids = [] webhook_port = 8444 Copied! Field Type Default Description service_account_envstring "GOOGLE_CHAT_SERVICE_ACCOUNT"Env var holding the service account JSON key. space_idslist of strings []Google Chat space IDs to listen in. webhook_portu16 8444Port for the incoming webhook. default_agentstring or null nullAgent name to route messages to.
[channels.twitch][ channels . twitch ] oauth_token_env = "TWITCH_OAUTH_TOKEN" channels = [ "mychannel" ] nick = "librefang" Copied! Field Type Default Description oauth_token_envstring "TWITCH_OAUTH_TOKEN"Env var holding the Twitch OAuth token. channelslist of strings []Twitch channels to join (without # prefix). nickstring "librefang"Bot nickname in Twitch chat. default_agentstring or null nullAgent name to route messages to.
[channels.rocketchat][ channels . rocketchat ] server_url = "https://rocketchat.example.com" token_env = "ROCKETCHAT_TOKEN" user_id = "" allowed_channels = [] Copied! Field Type Default Description server_urlstring ""Rocket.Chat server URL. token_envstring "ROCKETCHAT_TOKEN"Env var holding the Rocket.Chat auth token. user_idstring ""Bot user ID. allowed_channelslist of strings []Channel IDs to listen in. Empty = all. default_agentstring or null nullAgent 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 = [] Copied! Field Type Default Description server_urlstring ""Zulip server URL. bot_emailstring ""Bot email address registered in Zulip. api_key_envstring "ZULIP_API_KEY"Env var holding the Zulip API key. streamslist of strings []Stream names to listen in. Empty = all. default_agentstring or null nullAgent name to route messages to.
[channels.xmpp][ channels . xmpp ] jid = "bot@jabber.org" password_env = "XMPP_PASSWORD" server = "" port = 5222 rooms = [] Copied! Field Type Default Description jidstring ""XMPP JID (e.g., "bot@jabber.org"). password_envstring "XMPP_PASSWORD"Env var holding the XMPP password. serverstring ""XMPP server hostname. Defaults to the JID domain if empty. portu16 5222XMPP server port. roomslist of strings []MUC (multi-user chat) rooms to join. default_agentstring or null nullAgent 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 Copied! Field Type Default Description channel_secret_envstring "LINE_CHANNEL_SECRET"Env var holding the LINE channel secret. access_token_envstring "LINE_CHANNEL_ACCESS_TOKEN"Env var holding the LINE channel access token. webhook_portu16 8450Port for the incoming webhook. default_agentstring or null nullAgent name to route messages to.
[channels.viber][ channels . viber ] auth_token_env = "VIBER_AUTH_TOKEN" webhook_url = "" webhook_port = 8451 Copied! Field Type Default Description auth_token_envstring "VIBER_AUTH_TOKEN"Env var holding the Viber Bot auth token. webhook_urlstring ""Public URL for the Viber webhook endpoint. webhook_portu16 8451Port for the incoming webhook. default_agentstring or null nullAgent name to route messages to.
[channels.messenger][ channels . messenger ] page_token_env = "MESSENGER_PAGE_TOKEN" verify_token_env = "MESSENGER_VERIFY_TOKEN" webhook_port = 8452 Copied! Field Type Default Description page_token_envstring "MESSENGER_PAGE_TOKEN"Env var holding the Facebook page access token. verify_token_envstring "MESSENGER_VERIFY_TOKEN"Env var holding the webhook verify token. webhook_portu16 8452Port for the incoming webhook. default_agentstring or null nullAgent name to route messages to.
[channels.reddit][ channels . reddit ] client_id = "" client_secret_env = "REDDIT_CLIENT_SECRET" username = "" password_env = "REDDIT_PASSWORD" subreddits = [] Copied! Field Type Default Description client_idstring ""Reddit app client ID. client_secret_envstring "REDDIT_CLIENT_SECRET"Env var holding the Reddit client secret. usernamestring ""Reddit bot username. password_envstring "REDDIT_PASSWORD"Env var holding the Reddit bot password. subredditslist of strings []Subreddit names to monitor. default_agentstring or null nullAgent name to route messages to.
[channels.mastodon][ channels . mastodon ] instance_url = "https://mastodon.social" access_token_env = "MASTODON_ACCESS_TOKEN" Copied! Field Type Default Description instance_urlstring ""Mastodon instance URL (e.g., "https://mastodon.social"). access_token_envstring "MASTODON_ACCESS_TOKEN"Env var holding the Mastodon access token. default_agentstring or null nullAgent name to route messages to.
[channels.bluesky][ channels . bluesky ] identifier = "mybot.bsky.social" app_password_env = "BLUESKY_APP_PASSWORD" service_url = "https://bsky.social" Copied! Field Type Default Description identifierstring ""Bluesky handle or DID. app_password_envstring "BLUESKY_APP_PASSWORD"Env var holding the Bluesky app password. service_urlstring "https://bsky.social"PDS (Personal Data Server) URL. default_agentstring or null nullAgent name to route messages to.
[channels.feishu][ channels . feishu ] app_id = "" app_secret_env = "FEISHU_APP_SECRET" webhook_port = 8453 Copied! Field Type Default Description app_idstring ""Feishu/Lark app ID. app_secret_envstring "FEISHU_APP_SECRET"Env var holding the Feishu app secret. webhook_portu16 8453Port for the incoming webhook. default_agentstring or null nullAgent name to route messages to.
[channels.revolt][ channels . revolt ] bot_token_env = "REVOLT_BOT_TOKEN" api_url = "https://api.revolt.chat" Copied! Field Type Default Description bot_token_envstring "REVOLT_BOT_TOKEN"Env var holding the Revolt bot token. api_urlstring "https://api.revolt.chat"Revolt API base URL. default_agentstring or null nullAgent name to route messages to.
[channels.nextcloud][ channels . nextcloud ] server_url = "https://nextcloud.example.com" token_env = "NEXTCLOUD_TOKEN" allowed_rooms = [] Copied! Field Type Default Description server_urlstring ""Nextcloud server URL. token_envstring "NEXTCLOUD_TOKEN"Env var holding the Nextcloud Talk auth token. allowed_roomslist of strings []Room tokens to listen in. Empty = all. default_agentstring or null nullAgent name to route messages to.
[channels.guilded][ channels . guilded ] bot_token_env = "GUILDED_BOT_TOKEN" server_ids = [] Copied! Field Type Default Description bot_token_envstring "GUILDED_BOT_TOKEN"Env var holding the Guilded bot token. server_idslist of strings []Server IDs to listen in. Empty = all. default_agentstring or null nullAgent name to route messages to.
[channels.keybase][ channels . keybase ] username = "" paperkey_env = "KEYBASE_PAPERKEY" allowed_teams = [] Copied! Field Type Default Description usernamestring ""Keybase username. paperkey_envstring "KEYBASE_PAPERKEY"Env var holding the Keybase paper key. allowed_teamslist of strings []Team names to listen in. Empty = all DMs. default_agentstring or null nullAgent name to route messages to.
[channels.threema][ channels . threema ] threema_id = "" secret_env = "THREEMA_SECRET" webhook_port = 8454 Copied! Field Type Default Description threema_idstring ""Threema Gateway ID. secret_envstring "THREEMA_SECRET"Env var holding the Threema API secret. webhook_portu16 8454Port for the incoming webhook. default_agentstring or null nullAgent name to route messages to.
[channels.nostr][ channels . nostr ] private_key_env = "NOSTR_PRIVATE_KEY" relays = [ "wss://relay.damus.io" ] Copied! Field Type Default Description private_key_envstring "NOSTR_PRIVATE_KEY"Env var holding the Nostr private key (nsec or hex format). relayslist of strings ["wss://relay.damus.io"]Nostr relay WebSocket URLs to connect to. default_agentstring or null nullAgent name to route messages to.
[channels.webex][ channels . webex ] bot_token_env = "WEBEX_BOT_TOKEN" allowed_rooms = [] Copied! Field Type Default Description bot_token_envstring "WEBEX_BOT_TOKEN"Env var holding the Webex bot token. allowed_roomslist of strings []Room IDs to listen in. Empty = all. default_agentstring or null nullAgent name to route messages to.
[channels.pumble][ channels . pumble ] bot_token_env = "PUMBLE_BOT_TOKEN" webhook_port = 8455 Copied! Field Type Default Description bot_token_envstring "PUMBLE_BOT_TOKEN"Env var holding the Pumble bot token. webhook_portu16 8455Port for the incoming webhook. default_agentstring or null nullAgent name to route messages to.
[channels.flock][ channels . flock ] bot_token_env = "FLOCK_BOT_TOKEN" webhook_port = 8456 Copied! Field Type Default Description bot_token_envstring "FLOCK_BOT_TOKEN"Env var holding the Flock bot token. webhook_portu16 8456Port for the incoming webhook. default_agentstring or null nullAgent name to route messages to.
[channels.twist][ channels . twist ] token_env = "TWIST_TOKEN" workspace_id = "" allowed_channels = [] Copied! Field Type Default Description token_envstring "TWIST_TOKEN"Env var holding the Twist API token. workspace_idstring ""Twist workspace ID. allowed_channelslist of strings []Channel IDs to listen in. Empty = all. default_agentstring or null nullAgent name to route messages to.
[channels.mumble][ channels . mumble ] host = "mumble.example.com" port = 64738 username = "librefang" password_env = "MUMBLE_PASSWORD" channel = "" Copied! Field Type Default Description hoststring ""Mumble server hostname. portu16 64738Mumble server port. usernamestring "librefang"Bot username in Mumble. password_envstring "MUMBLE_PASSWORD"Env var holding the Mumble server password. channelstring ""Mumble channel to join. default_agentstring or null nullAgent name to route messages to.
[channels.dingtalk][ channels . dingtalk ] access_token_env = "DINGTALK_ACCESS_TOKEN" secret_env = "DINGTALK_SECRET" webhook_port = 8457 Copied! Field Type Default Description access_token_envstring "DINGTALK_ACCESS_TOKEN"Env var holding the DingTalk webhook access token. secret_envstring "DINGTALK_SECRET"Env var holding the DingTalk signing secret. webhook_portu16 8457Port for the incoming webhook. default_agentstring or null nullAgent 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 = [] Copied! Field Type Default Description base_urlstring ""Discourse forum base URL. api_key_envstring "DISCOURSE_API_KEY"Env var holding the Discourse API key. api_usernamestring "system"Discourse API username. categorieslist of strings []Category slugs to monitor. default_agentstring or null nullAgent name to route messages to.
[channels.gitter][ channels . gitter ] token_env = "GITTER_TOKEN" room_id = "" Copied! Field Type Default Description token_envstring "GITTER_TOKEN"Env var holding the Gitter auth token. room_idstring ""Gitter room ID to listen in. default_agentstring or null nullAgent name to route messages to.
[channels.ntfy][ channels . ntfy ] server_url = "https://ntfy.sh" topic = "my-agent-topic" token_env = "NTFY_TOKEN" Copied! Field Type Default Description server_urlstring "https://ntfy.sh"ntfy server URL. Can be self-hosted. topicstring ""Topic to subscribe/publish to. token_envstring "NTFY_TOKEN"Env var holding the auth token. Optional for public topics. default_agentstring or null nullAgent 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" Copied! Field Type Default Description server_urlstring ""Gotify server URL. app_token_envstring "GOTIFY_APP_TOKEN"Env var holding the Gotify app token (for sending messages). client_token_envstring "GOTIFY_CLIENT_TOKEN"Env var holding the Gotify client token (for receiving messages via WebSocket). default_agentstring or null nullAgent name to route messages to.
[channels.webhook][ channels . webhook ] secret_env = "WEBHOOK_SECRET" listen_port = 8460 # callback_url = "https://example.com/webhook" Copied! Field Type Default Description secret_envstring "WEBHOOK_SECRET"Env var holding the HMAC signing secret for verifying incoming webhooks. listen_portu16 8460Port to listen for incoming webhook requests. callback_urlstring or null nullURL to POST outgoing messages to. default_agentstring or null nullAgent name to route messages to.
[channels.linkedin][ channels . linkedin ] access_token_env = "LINKEDIN_ACCESS_TOKEN" organization_id = "" Copied! Field Type Default Description access_token_envstring "LINKEDIN_ACCESS_TOKEN"Env var holding the LinkedIn OAuth2 access token. organization_idstring ""LinkedIn organization ID for messaging. default_agentstring or null nullAgent name to route messages to.
[[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" ] Copied! [[ mcp_servers ]] name = "remote-api" timeout_secs = 60 env = [ "GITHUB_PERSONAL_ACCESS_TOKEN" ] [ mcp_servers . transport ] type = "sse" url = "https://mcp.example.com/sse" Copied! Field Type Default Description namestring required Display name for this MCP server. Tools are namespaced as mcp_{name}_{tool}. timeout_secsu64 30Request timeout in seconds. envlist of strings []Environment variable names to pass through to the subprocess (stdio transport only).
Transport variants (tagged union on type):
typeFields Description stdiocommand (string), args (list of strings, default [])Spawn a subprocess, communicate via JSON-RPC over stdin/stdout. sseurl (string)Connect to an HTTP Server-Sent Events endpoint.
[a2a]Agent-to-Agent protocol configuration, enabling inter-agent communication across LibreFang instances.
[ a2a ] enabled = true 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" Copied! Field Type Default Description enabledbool falseWhether A2A protocol is enabled. listen_pathstring "/a2a"URL path prefix for A2A endpoints. external_agentslist of objects []External A2A agents to discover and interact with.
external_agents entries:
Field Type Description namestring Display name for the external agent. urlstring 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" Copied! Field Type Default Description providerstring ""Provider name (e.g., "ollama", "groq", "openai"). modelstring ""Model identifier for this provider. api_key_envstring ""Env var name for the API key. Empty for local providers (ollama, vllm, lmstudio). base_urlstring or null nullBase 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" Copied! Field Type Default Description namestring required User display name. rolestring "user"User role in the RBAC hierarchy. channel_bindingsmap of string to string {}Maps channel platform names to platform-specific user IDs, binding this user identity across channels. api_key_hashstring or null nullSHA256 hash of the user's personal API key for authenticated API access.
Role hierarchy (highest to lowest privilege):
Role Description ownerFull administrative access. Can manage all agents, users, and configuration. adminCan manage agents and most settings. Cannot modify owner accounts. userCan interact with agents. Limited management capabilities. viewerRead-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_user = 10 threading = true output_format = "telegram_html" usage_footer = "tokens" Copied! Field Type Default Description modelstring or null nullModel override for this channel. Uses the agent's default model when null. system_promptstring or null nullSystem prompt override for this channel. dm_policystring "respond"How the bot handles direct messages. See below. group_policystring "mention_only"How the bot handles group messages. See below. rate_limit_per_useru32 0Maximum messages per user per minute. 0 = unlimited. threadingbool falseEnable thread replies (where supported by the platform). output_formatstring or null nullOverride output formatting. See below. usage_footerstring or null nullOverride usage footer mode for this channel. Values: off, tokens, cost, full.
dm_policy values:
Value Description respondRespond to all direct messages (default). allowed_onlyOnly respond to DMs from users in the allowed list. ignoreIgnore all direct messages.
group_policy values:
Value Description allRespond to all messages in group chats. mention_onlyOnly respond when the bot is @mentioned (default). commands_onlyOnly respond to slash commands. ignoreIgnore all group messages.
output_format values:
Value Description markdownStandard Markdown (default). telegram_htmlTelegram HTML subset (<b>, <i>, <code>, etc.). slack_mrkdwnSlack mrkdwn format (*bold*, _italic_, `code`). plain_textNo formatting markup.
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_KEYGemini driver Google Gemini API key. Alias: GOOGLE_API_KEY. OPENAI_API_KEYOpenAI-compat driver OpenAI API key. GROQ_API_KEYGroq provider Groq API key (fast Llama inference). DEEPSEEK_API_KEYDeepSeek provider DeepSeek API key. PERPLEXITY_API_KEYPerplexity provider / web search Perplexity API key. OPENROUTER_API_KEYOpenRouter provider OpenRouter API key. TOGETHER_API_KEYTogether AI provider Together AI API key. MISTRAL_API_KEYMistral provider Mistral AI API key. FIREWORKS_API_KEYFireworks provider Fireworks AI API key. COHERE_API_KEYCohere provider Cohere API key. AI21_API_KEYAI21 provider AI21 Labs API key. CEREBRAS_API_KEYCerebras provider Cerebras API key. SAMBANOVA_API_KEYSambaNova provider SambaNova API key. HUGGINGFACE_API_KEYHugging Face provider Hugging Face Inference API key. XAI_API_KEYxAI provider xAI (Grok) API key. REPLICATE_API_KEYReplicate 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_TOKENTelegram Bot API token from @BotFather. DISCORD_BOT_TOKENDiscord Discord bot token. SLACK_APP_TOKENSlack Slack app-level token (xapp-) for Socket Mode. SLACK_BOT_TOKENSlack Slack bot token (xoxb-) for REST API. WHATSAPP_ACCESS_TOKENWhatsApp WhatsApp Cloud API access token. WHATSAPP_VERIFY_TOKENWhatsApp Webhook verification token. MATRIX_ACCESS_TOKENMatrix Matrix homeserver access token. EMAIL_PASSWORDEmail Email account password or app password. TEAMS_APP_PASSWORDTeams Azure Bot Framework app password. MATTERMOST_TOKENMattermost Mattermost bot token. TWITCH_OAUTH_TOKENTwitch Twitch OAuth token. ROCKETCHAT_TOKENRocket.Chat Rocket.Chat auth token. ZULIP_API_KEYZulip Zulip bot API key. XMPP_PASSWORDXMPP XMPP account password. GOOGLE_CHAT_SERVICE_ACCOUNTGoogle Chat Service account JSON key. LINE_CHANNEL_SECRETLINE LINE channel secret. LINE_CHANNEL_ACCESS_TOKENLINE LINE channel access token. VIBER_AUTH_TOKENViber Viber Bot auth token. MESSENGER_PAGE_TOKENMessenger Facebook page access token. MESSENGER_VERIFY_TOKENMessenger Webhook verification token. REDDIT_CLIENT_SECRETReddit Reddit app client secret. REDDIT_PASSWORDReddit Reddit bot account password. MASTODON_ACCESS_TOKENMastodon Mastodon access token. BLUESKY_APP_PASSWORDBluesky Bluesky app password. FEISHU_APP_SECRETFeishu Feishu/Lark app secret. REVOLT_BOT_TOKENRevolt Revolt bot token. NEXTCLOUD_TOKENNextcloud Nextcloud Talk auth token. GUILDED_BOT_TOKENGuilded Guilded bot token. KEYBASE_PAPERKEYKeybase Keybase paper key. THREEMA_SECRETThreema Threema Gateway API secret. NOSTR_PRIVATE_KEYNostr Nostr private key (nsec or hex). WEBEX_BOT_TOKENWebex Webex bot token. PUMBLE_BOT_TOKENPumble Pumble bot token. FLOCK_BOT_TOKENFlock Flock bot token. TWIST_TOKENTwist Twist API token. MUMBLE_PASSWORDMumble Mumble server password. DINGTALK_ACCESS_TOKENDingTalk DingTalk webhook access token. DINGTALK_SECRETDingTalk DingTalk signing secret. DISCOURSE_API_KEYDiscourse Discourse API key. GITTER_TOKENGitter Gitter auth token. NTFY_TOKENntfy ntfy auth token (optional for public topics). GOTIFY_APP_TOKENGotify Gotify app token (sending). GOTIFY_CLIENT_TOKENGotify Gotify client token (receiving). WEBHOOK_SECRETWebhook HMAC signing secret for webhook verification. LINKEDIN_ACCESS_TOKENLinkedIn LinkedIn OAuth2 access token.
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_envDiscord bot_token_envSlack app_token_env, bot_token_env (both checked)WhatsApp access_token_envMatrix access_token_envEmail password_envTeams app_password_envMattermost token_envZulip api_key_envTwitch oauth_token_envRocket.Chat token_envGoogle Chat service_account_envXMPP password_envLINE access_token_envViber auth_token_envMessenger page_token_envReddit client_secret_envMastodon access_token_envBluesky app_password_envFeishu app_secret_envRevolt bot_token_envNextcloud token_envGuilded bot_token_envKeybase paperkey_envThreema secret_envNostr private_key_envWebex bot_token_envPumble bot_token_envFlock bot_token_envTwist token_envMumble password_envDingTalk access_token_envDiscourse api_key_envGitter token_envntfy token_env (only if token_env is non-empty; public topics are OK without auth)Gotify app_token_envWebhook secret_envLinkedIn access_token_env
For web search providers , the validator checks:
Provider Env var checked braveweb.brave.api_key_envtavilyweb.tavily.api_key_envperplexityweb.perplexity.api_key_envduckduckgo(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 threshold80Compact when session message count exceeds this. keep_recent20Number of recent messages preserved verbatim after compaction. max_summary_tokens1024Maximum 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_limit1000000Maximum CPU instruction budget. 0 = unlimited. max_memory_bytes16777216 (16 MB)Maximum WASM linear memory. timeout_secsnull (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_threshold100Token count below which a query is classified as simple. complex_threshold500Token count above which a query is classified as complex.
Autonomous Guardrails (per-agent manifest)
Configured in agent manifests via AutonomousConfig:
Field Default Description quiet_hoursnullCron expression for quiet hours (agent pauses during this window). max_iterations50Maximum tool-use iterations per invocation. max_restarts10Maximum automatic restarts before permanent stop. heartbeat_interval_secs30Seconds between heartbeat health checks. heartbeat_channelnullChannel to send heartbeat status to (e.g., "telegram").