Core Configuration Reference

Core configuration sections for LibreFang: top-level fields, default model, memory, networking, web search, media processing, and link understanding.

Top-Level Fields

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

mode values:

usage_footer values:

[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"

[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

[auto_dream]

Background memory consolidation ("dreams") — asks opt-in agents to reflect on and consolidate their own memory via a 4-phase prompt (Orient / Gather / Consolidate / Prune). Dreams are triggered event-driven (the moment an agent finishes a turn the kernel checks whether its gates are open); a sparse backstop scheduler catches opted-in agents that go long periods without taking a turn. Disabled by default; individual agents still opt in via auto_dream_enabled = true on their manifest.

[auto_dream]
enabled = false
min_hours = 24
min_sessions = 5
check_interval_secs = 86400
timeout_secs = 600
# lock_dir = ""   # defaults to <data_dir>/auto_dream/

A dream fires for an agent when all gates hold: enabled = true, the agent's manifest has auto_dream_enabled = true, min_hours have elapsed since its last dream, min_sessions have been touched since then, and the per-agent lock can be acquired.

Per-agent opt-in can be toggled at runtime without restarting the agent:

• Web dashboard: Settings → Auto-Dream card → checkbox next to each agent.
• API: PUT /api/auto-dream/agents/{id}/enabled with body {"enabled": true | false}. The new state takes effect at the next turn end (event-driven) or the next backstop tick, whichever comes first.
• Manifest: set auto_dream_enabled = true in the agent's .toml for a persistent opt-in that survives restarts.

Per-agent threshold overrides (optional) let you tune the schedule heterogeneously. Set either field on the agent's manifest to override the global [auto_dream] default — None (the default) inherits the global:

auto_dream_enabled = true
auto_dream_min_hours = 168    # weekly, for quiet agents
auto_dream_min_sessions = 1   # fire after every session, for chatty ones

The status endpoint returns the resolved effective_min_hours / effective_min_sessions per agent so the dashboard can show what is actually in force.

Runtime tool restriction: inside a dream, the kernel clamps the tool allowlist to memory_store / memory_recall / memory_list only, regardless of what the agent's manifest normally permits. This is defence-in-depth against prompt-injected dreams calling shell or network-mutating tools.

Manual controls: POST /api/auto-dream/agents/{id}/trigger bypasses the time and session gates but still respects the lock and the opt-in flag. POST /api/auto-dream/agents/{id}/abort cancels an in-flight manual dream and rolls the lock mtime back so the time gate reopens. GET /api/auto-dream/status returns live progress, including token usage and cost for completed dreams.

Audit trail: every dream lifecycle transition (start / complete / fail / abort) is recorded as a DreamConsolidation audit event. The completion entry carries input/output/cache token counts and cost_usd so spend is answerable from /api/audit.

[network]

Configures the OFP (LibreFang Protocol) peer-to-peer networking layer. Authentication has two layers: a shared_secret HMAC admission gate plus per-node Ed25519 identity with TOFU pinning (#3873). The Ed25519 keypair and trust pins live in <data_dir>/peer_keypair.json and <data_dir>/trusted_peers.json.

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

[web]

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

[web]
search_provider = "auto"
cache_ttl_minutes = 15
timeout_secs = 15

search_provider values:

[web.brave]

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

[web.tavily]

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

[web.jina]

[web.jina]
api_key_env = "JINA_API_KEY"
max_results = 5

[web.perplexity]

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

[web.searxng]

Self-hosted SearXNG provider. Disabled by default — set url to opt in. No API key is required; LibreFang talks to the instance over the public /search?format=json endpoint and discovers categories via /config.

[web.searxng]
url = "https://search.example.com"

Notes:

• Categories are validated dynamically against the instance's /config endpoint and cached for 5 minutes; an invalid category surfaces the available list back to the agent.
• Pagination uses SearXNG's 1-indexed pageno query param (pageno=0 is rejected up front).
• Public SearXNG instances reject the limit parameter, so max_results is enforced client-side after fetching.
• Results returned to the LLM are filtered to title / url / content / published_date only — engine-level scoring noise is stripped.
• When search_provider = "auto", SearXNG only runs if url is non-empty; otherwise the cascade skips it.

[web.fetch]

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

[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

[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

[parallel_tools]

Controls the agent loop's batch tool dispatcher — when a single assistant turn emits multiple tool calls, the dispatcher classifies each by parallel-safety and decides which can run concurrently and which must serialise.

[parallel_tools]
enabled = false
max_concurrent = 4
mcp_default_safety = "write_shared"
mcp_readonly_allowlist = ["mcp__github__list_issues", "mcp__notion__query_database"]

ParallelSafety classes. Every tool call is classified into one of four classes (computed from built-in heuristics, the tool's input-schema annotations, or the MCP knobs above):

Tool authors can pin a class by adding "x-parallel-safety": "<snake_case>" at the top level of a tool's input schema, or "metadata": { "parallel_safety": "<snake_case>" }. Unknown values fall through to the heuristic, so a typo never poisons the result.

When to tune which knob.

• Leave enabled = false if you want behaviour identical to historical sequential dispatch — useful while validating a new fleet of agents or while debugging tool-ordering issues.
• Lower max_concurrent if your environment is rate-limit-sensitive (small MCP servers, low API quotas). 4 is a balanced default; raise it for read-heavy workloads against fast back-ends.
• Promote mcp_default_safety to "read_only" only if every MCP server you connect is genuinely read-only or carries proper annotations. The default "write_shared" is the safe choice — unannotated MCP servers that quietly mutate state will not race.
• Use mcp_readonly_allowlist to whitelist specific safe tools from a server whose other tools mutate state. This is the surgical alternative to flipping mcp_default_safety.
• Disable batch dispatch (enabled = false) if you observe race-condition symptoms in a custom MCP server — wrong cache hits, conflicting writes, partial-state reads. File a fix or add the offending tool to a tighter classification, then re-enable.

max_history_messages

LibreFang trims an agent's stored conversation history at every turn so it does not grow without bound. The cap controls how many messages survive each trim. The mechanism cuts only at safe turn boundaries (never inside a tool_use/tool_result pair), so the surviving slice is always well-formed for strict providers like Gemini.

The cap is configurable at two levels — a top-level field in config.toml (operator-wide override) and a top-level field in agent.toml (per-agent override). Both are optional.

Resolution order (first match wins):

1. Per-agent override — max_history_messages in agent.toml (top-level, not inside any section).
2. Global override — max_history_messages at the top of config.toml.
3. Compiled-in default — DEFAULT_MAX_HISTORY_MESSAGES = 40.

Values below MIN_HISTORY_MESSAGES = 4 are silently clamped up to 4 at runtime with a warn! log carrying agent, requested, and applied. Justification: a single tool-use round trip is 4 messages (user → assistant tool_use → tool_result → assistant text); caps below 4 defeat the safe-trim heuristic.

Global override in ~/.librefang/config.toml:

# Lower the default for every agent that does not override it itself.
max_history_messages = 20

Per-agent override in any agent.toml (top-level field — sits next to name, module, etc., NOT inside [model] or [autonomous]):

name = "fast-loop"
module = "builtin:chat"
max_history_messages = 12

When to tune.

• Lower the cap (e.g. 20 or 12) for chatty agents driven by cron pings or short-message channels — each turn ships less history, so per-turn token cost drops.
• Raise the cap (e.g. 80 or 120) for long-horizon autonomous agents on long-context models, where richer history improves grounding.
• Leave it unset (null / omitted) on most agents — the 40 default is tuned for typical chat workloads.

Interaction with the token-count cap. This is a message-count cap. There is also an independent token-count cap (DEFAULT_CONTEXT_WINDOW = 200000) — whichever fires first wins. Many short messages → the message-count cap fires first; few long messages (large tool outputs) → the token cap fires first.

For deeper detail (what gets trimmed, the safe-trim algorithm, where the value flows through the runtime), see the architecture note at docs/architecture/message-history-trimming.md.

[provider_request_timeout_secs]

Per-provider HTTP request timeout for LLM driver calls. Without an entry, the driver uses its built-in default (typically 60 s for the OpenAI-compatible driver, longer for Ollama).

[provider_request_timeout_secs]
ollama = 300        # local model loading + first-token cold start
anthropic = 120
openai = 90

Per-model overrides are also possible at the agent level via agent.toml: model.request_timeout_secs for fine-grained tuning of slow long-context models.

[browser]

Browser tool configuration. By default LibreFang launches a local Chromium instance. Set cdp_endpoint to attach to an already-running browser (Browserless, headful Chrome with --remote-debugging-port, etc.) instead.

[browser]
# Default: spawn a local headless Chromium per session
# Set cdp_endpoint to attach to a remote / pre-launched browser instead
cdp_endpoint = "http://browser-host:9222"
cdp_auth_token_env = "LIBREFANG_CDP_TOKEN"   # optional bearer token env var

In attach mode the existing local-launch path is completely bypassed; Drop does not terminate the external browser.

Cron session size limits

When cron jobs share a persistent session (the default — session_mode = "persistent"), that session's history grows with each fire. Two optional caps prune the oldest messages from the front before each fire so the session does not balloon.

[kernel]
cron_session_max_tokens = 50000
cron_session_max_messages = 100

Pruning is skipped when session_mode = "new" — those fires always start fresh and never carry stale state. Both caps apply jointly (whichever fires first prunes more).

[rate_limit]

API and WebSocket rate-limiting knobs. The HTTP path uses a GCRA token bucket per IP; WebSocket paths add an idle timeout and a per-message debounce so streaming UIs don't hammer downstream consumers.

[rate_limit]
api_requests_per_minute = 500
retry_after_secs = 60
max_ws_per_ip = 5
ws_messages_per_minute = 10
ws_terminal_messages_per_minute = 3600
ws_idle_timeout_secs = 1800
ws_debounce_ms = 100
ws_debounce_chars = 200

The terminal limit is two orders of magnitude higher than the chat limit for a reason: chat ws_messages_per_minute = 10 would exhaust the budget on a single vim + :wq keystroke flurry. Don't lower ws_terminal_messages_per_minute below ~600 unless you actively want to throttle interactive PTYs.

[sanitize]

Inbound message sanitisation / prompt-injection detection. Off by default — when on, oversized or pattern-matching inbound text is blocked or warned before reaching the LLM.

[sanitize]
mode = "off"            # "off" | "warn" | "block"
max_message_length = 32768
custom_block_patterns = [
  "(?i)ignore previous instructions",
]

In block mode the channel adapter responds with a sanitiser-rejection notice and zero LLM tokens are spent. Pair with [privacy] for a defence-in-depth setup.

[privacy]

PII redaction or pseudonymisation applied to LLM prompts. Off by default. The redactor runs on every outbound prompt, including history replays.

[privacy]
mode = "off"            # "off" | "redact" | "pseudonymize"
redact_patterns = [
  "\\b[A-Z]{2}\\d{6,8}\\b",   # add custom patterns on top of built-ins
]

pseudonymize keeps a per-process mapping in memory only — restarting the daemon resets the substitution table.

[telemetry]

OpenTelemetry tracing + Prometheus metrics. The bundled Tempo/Grafana stack reads from these endpoints; external collectors work too — just point otlp_endpoint at them.

[telemetry]
enabled = true
otlp_endpoint = "http://localhost:4317"
service_name = "librefang"
sample_rate = 1.0
prometheus_enabled = true
auto_start_observability_stack = false

[heartbeat]

Heartbeat monitor for autonomous (always-on) agents. The monitor flags an agent as unresponsive when it hasn't heartbeated within default_timeout_secs.

[heartbeat]
check_interval_secs = 30
default_timeout_secs = 60
keep_recent = 10

The heartbeat path also short-circuits crash-loop prevention — an agent that emits the same error N times in a row is paused with auth_status: "crashed" rather than retried indefinitely.

[compaction]

LLM-based history summarisation. When a session crosses either the message-count threshold or the token-ratio threshold, the daemon spawns a background turn that summarises the older half of the history in the user's conversation language and replaces it with the summary plus the most recent N turns.

[compaction]
threshold_messages = 30
keep_recent = 10
max_summary_tokens = 1024
token_threshold_ratio = 0.7
max_chunk_chars = 80000
max_retries = 3

Per-agent overrides: max_history_messages in agent.toml clamps the trim cap for that agent. Compaction kicks in earlier if you set it lower than the global default.

[tool_invoke]

Direct tool-invocation REST endpoint allowlist (see POST /api/tools/{name}/invoke). Locked down by default — every request returns 403 unless both fields are populated.

[tool_invoke]
enabled = true
allowlist = ["web_search", "web_fetch", "file_read"]

Glob semantics match agent capability grants — * is the wildcard. Use this for narrow integrations (a CI worker calling web_fetch directly), not for general client API access.

[parallel_tools] (extended)

The agent-loop's parallel tool dispatcher (introduced in the catchup wave). Off by default — the runtime still serialises tool calls until the dispatcher rolls out fully.

write_shared keeps unannotated MCP tools strictly serialised, which is the safe default. Only flip individual servers to read_only after auditing them.

Resource Limits & Boundaries (top-level)

Global safety nets that cap inbound payload sizes and inter-agent recursion depth. All have built-in defaults — override only when you know what you're doing.

[kernel]
max_upload_size_bytes      = 10485760     # 10 MiB
max_request_body_bytes     = 16777216     # 16 MiB
max_concurrent_bg_llm      = 8
max_agent_call_depth       = 5
local_probe_interval_secs  = 60
strict_config              = false
update_channel             = "stable"     # "stable" | "beta" | "rc"
trusted_hosts              = []
trusted_manifest_signers   = []

Background autonomous-loop executor

Tunes the rate-limit circuit breaker that stops a continuous / periodic background loop from re-firing forever when the LLM provider is rate-limited or quota-exhausted (issue #5168). A single non-rate-limited tick resets the counter, so transient blips never permanently park a healthy agent.

[background]
max_consecutive_rate_limits = 5

Dashboard authentication (top-level)

Reach the dashboard from a non-loopback address? Set a username/password and LibreFang will hash the password to Argon2id automatically on first boot.

[kernel]
dashboard_user = "admin"
dashboard_pass = "vault:DASHBOARD_PASS"   # or plain string, or env var
# dashboard_pass_hash is auto-populated; do NOT set by hand
require_auth_for_reads = true

[skills]

User-installed skill loading and disable list. Bundled skills (the 60-or-so that ship with the daemon) are always loaded; [skills] only controls what happens with the additional skills users put under ~/.librefang/skills/ and any extra paths.

[skills]
load_user = true
extra_dirs = ["/srv/librefang/team-skills"]
disabled = ["legacy-research"]

[notification]

Where approval requests and task-state alerts are sent. Empty defaults mean approvals only show in the dashboard inbox — set channels here to also page Telegram / Slack / email / etc.

[notification]
# All approvals also fan out to Telegram and Slack
approval_channels = [
  { kind = "telegram", target = "123456789" },
  { kind = "slack", target = "C0123456" },
]
# Failure alerts only go to email
alert_channels = [
  { kind = "email", target = "ops@example.com" },
]

# Per-agent override — research-bot's approvals go to the research lead instead
[[notification.agent_rules]]
agent = "research-bot"
targets = [{ kind = "telegram", target = "987654321" }]

For per-tool routing (e.g. "shell_exec approvals go to oncall, file_write approvals go to the dev team"), use [approval] routing rather than [notification].

[triggers]

Event-driven trigger system safety knobs. Caps how often triggers fire, how many fire per event, and how deep a trigger-spawning-trigger chain can go.

[triggers]
cooldown_secs = 5
max_per_event = 10
max_depth = 5
max_workflow_secs = 3600

Cron and [[trigger]] entries on agent manifests share these caps. Lower max_depth to 1 in production setups where you don't want triggers to chain at all.

[task_board]

Shared task queue safety knobs. The task board is the durable queue agents pull pending work from; if a worker claims a task and crashes without completing it, the sweeper resets it back to pending after claim_ttl_secs so another worker can pick it up.

[task_board]
claim_ttl_secs = 600        # 10 minutes
sweep_interval_secs = 30
max_retries = 0             # 0 = retry forever

Tune claim_ttl_secs to roughly 2× your slowest task's expected runtime. Set it too low and healthy long-running tasks get yanked out from under their workers; too high and crash recovery is slow.

[registry]

Skill / plugin / template registry sync. The registry is mirrored locally in ~/.librefang/registry-cache/ and re-downloaded when the cache is stale.

[registry]
cache_ttl_secs = 86400            # 24 hours
registry_mirror = "https://ghproxy.cn"

Common mirror values: https://ghproxy.cn, https://gh-proxy.com, an internal corporate proxy. Leave empty to hit GitHub directly.

[azure_openai]

Provider-specific config block for Azure OpenAI deployments. Azure uses a different URL format and auth header than standard OpenAI, so the platform driver lives in its own config section. All three fields fall back to environment variables — set whichever style suits your secret-management story.

[azure_openai]
endpoint = "https://my-resource.openai.azure.com"
deployment = "gpt-4o"
api_version = "2024-02-01"

Auth is AZURE_OPENAI_API_KEY (header: api-key, not Authorization: Bearer). See the Azure OpenAI provider entry for full setup.

Top-level fields (operator paths and per-provider HTTP)

Five additional top-level fields that affect daemon I/O and per-provider networking. All optional, all None-by-default unless noted.

[kernel]
config_version = 1
log_dir = "/var/log/librefang"
qwen_code_path = "/home/user/.local/bin/qwen"

# Per-provider HTTP knobs (not under any subsection)
[provider_proxy_urls]
openai = "http://corp-proxy.local:8080"
anthropic = "http://corp-proxy.local:8080"
ollama = ""    # explicit "no proxy" override

Additional config sections (appendix)

These sections have schemas in code but are typically left at their defaults. Settings here only need to be touched for advanced operator scenarios — listing them so you can find the field name when you do.

# Tool timeouts — global default + per-tool overrides
tool_timeout_secs = 60
[tool_timeouts]
"shell_exec" = 300
"web_*"      = 30

# Fallback LLM providers (tried in order on primary failure)
[[fallback_providers]]
provider = "groq"
model    = "llama-3.3-70b-versatile"

# Static MCP servers loaded at boot
[[mcp_servers]]
name = "github"
url  = "https://api.example.com/mcp"

# Webhook triggers — external systems pushing events into LibreFang
[webhook_triggers]
enabled = true
secret_env = "WEBHOOK_TRIGGERS_SECRET"

# Extensions / MCP integrations — auto-reconnect knobs
[extensions]
auto_reconnect = true
reconnect_max_attempts = 10
reconnect_max_backoff_secs = 300
health_check_interval_secs = 60

# Config hot-reload (file watcher)
[reload]
enabled = true
debounce_ms = 500

# Auto-reply background engine for inbound messages
[auto_reply]
enabled = false
# (provider-specific tuning — see librefang-runtime::auto_reply)

# Broadcast routing (multi-recipient delivery)
[broadcast]
enabled = false
max_fanout = 100

# A2UI canvas tool
[canvas]
enabled = false
max_html_bytes = 524288
allowed_tags = []   # empty = all safe tags

# A2A protocol config (agent-to-agent across instances)
[a2a]
listen_path = "/a2a"
trust_anchors = []

# Device pairing
[pairing]
enabled = true
ttl_secs = 600

# Global exec policy (overrideable per-agent or per-tool)
[exec_policy]
allow_shell = true
shell_allowlist = ["git", "cargo", "npm"]