Docs/Operations/Configuration reference

Configuration reference

Complete reference for Fermix configuration: the config.toml file, its sections and keys, three-layer precedence, and all environment variable overrides.

All operator-editable configuration lives in ~/.fermix/config.toml (or $FERMIX_HOME/config.toml if you override the home directory). The setup wizard writes this file; the runtime reads it on startup through FermixCore.Config and provider-specific config modules. You can edit it by hand or re-run fermix setup --reconfigure to regenerate specific sections.

Configuration precedence

Fermix resolves configuration in three layers, each overriding the one before it:

  1. Compile-time defaults (baked into the release in config/config.exs)
  2. Persisted setup snapshot from config.toml
  3. Environment variable overrides applied at runtime (config/runtime.exs)

Environment variables win over everything. This means a value set in config.toml can be silently superseded by an env var of the same semantic, so check both when debugging unexpected behavior.

FERMIX_HOME

FERMIX_HOME defaults to ~/.fermix. The setup wizard creates the following layout under it:

~/.fermix/
  config.toml          # main configuration file
  auth.json            # OAuth token store (all providers; mode 0600)
  memory.db            # durable memory (SQLite)
  daemon.sock          # socket the CLI uses to talk to the daemon (the background Fermix service)
  realtime.sock        # FermixPet voice companion socket
  bootstrap/           # prompt files (main/{IDENTITY,FERMIX,SOUL,REALTIME}.md)
  memory/              # profile files rebuilt by background memory review
  skills/              # user-installed skills
  plugins/             # installed plugin store
  browser/             # browser profile
  journals/
  realtime/
  traces/              # JSONL trace files
  logs/                # rotating daemon log
  workspace/           # default sandbox workspace root
  grants/              # sandbox grant records

Set FERMIX_HOME to a different path to run a second Fermix instance (for example, a dev install alongside a production one). Each instance must have its own config.toml and, if using Telegram, its own bot token. See auth and secrets for keychain namespacing when running multiple instances.

[fermix_core]

Top-level core settings.

Key Default Notes
profile "general" Keychain namespace prefix. Set before running fermix setup on a non-default install. Changing it after setup orphans existing keychain entries.

[fermix_core.agent]

Core agent identity settings.

Key Default Notes
name "fermix" Public-facing agent name used in prompts and channel replies.

The primary provider is selected by setting primary = true in the desired [fermix_core.providers.<name>] block, not via a key here. The legacy provider key in this section is read-only migration input (used only if no primary flag exists anywhere); setup no longer writes it.

[fermix_core.providers.<name>]

One sub-table per provider. Valid names: openai, openai_codex, anthropic, xai, openrouter, mistral, ollama.

Key Notes
primary true/false. Exactly one provider block must have primary = true; that provider handles main turns. All other configured providers become ordered fallbacks.
api_key Plaintext API key or the @keyring sentinel (reads from the OS keychain). After running fermix setup, secrets are normally in the keychain and this key is absent or set to @keyring.
default_model Model identifier. See providers and models for the full catalog.
reasoning_effort How much internal thinking the model does before answering (higher means more thorough but slower and pricier). One of "none", "low", "medium", "high", "xhigh", "max". Applies only to effort-capable providers (OpenAI, OpenAI Codex, Anthropic, xAI). OpenRouter, Mistral, and Ollama blocks reject this key at config load. Anthropic has no "none" (floor is "low").
base_url Override the default API base URL. Useful for proxies or compatible endpoints. Not accepted in the openai block (writing it there fails at config load).
auth_mode "api_key" or "oauth". Valid only in the anthropic and xai blocks. openai is always API-key; openai_codex is always OAuth — neither block accepts this key.
fast openai_codex only. true/false. When true, Codex requests run on the priority service tier.

Each provider block only accepts the keys that apply to it. An unknown or misplaced key (for example reasoning_effort in an openrouter, mistral, or ollama block) is rejected at config load and the daemon refuses to boot until it is removed. See providers and models for the full per-provider key list.

Example:

[fermix_core.providers.openai]
api_key = "@keyring"
default_model = "gpt-5.5"
reasoning_effort = "medium"

[fermix_core.providers.anthropic]
api_key = "@keyring"
default_model = "claude-opus-4-8"

[fermix_core.personalization]

Feeds the agent’s identity prompt section.

Key Notes
user_name Your name, used in greetings and self-reference.
timezone IANA timezone string (e.g. "America/New_York").
communication_style Free-form style hint injected into the system prompt.

[fermix_core.compaction]

Controls automatic conversation compaction: when a conversation grows too long to fit the model’s memory, Fermix summarizes the older parts to make room. The trigger uses the provider’s reported context (prompt) token count from the turn, not a local estimate. When that count reaches threshold * model_context_window (a fraction of the maximum amount of text the model can consider at once), Fermix summarizes older messages and replaces the stored history with the summary plus recent turns.

Key Default Notes
enabled true Set to false to disable automatic compaction.
threshold 0.85 Fraction of the model context window that triggers compaction.
reasoning_effort "medium" Reasoning effort the summarization call uses, separate from the main turn’s effort.

The /compact channel command triggers immediate compaction on demand. /new clears the conversation window without affecting long-term memory, scheduled jobs, or resource revisions. See prompt and compaction for details.

[fermix_core.memory]

Tuning knobs for the background memory-review (“dreaming”) pass — how often it runs, how much it reads, and how it backs off after a failure. Most installs leave this section at defaults. See memory.

Key Default Notes
review_interval_hours 24 How often background memory review (“dreaming”) consolidates facts and rebuilds the injected USER.md/MEMORY.md profiles.
review_max_messages 40 Maximum recent messages a single review pass reads.
review_input_token_budget 4000 Token budget for the input a review pass sends to the model.
review_failure_backoff_ms 300000 How long to wait before retrying after a failed review (5 minutes).

[fermix_core.jobs]

Scheduled job runtime settings. See scheduled jobs.

Key Default Notes
default_delivery_mode How to deliver job results. One of "none", "origin", "channel", "local".
default_delivery_target.platform Channel platform for delivery (e.g. "telegram").
default_delivery_target.chat_id External channel conversation id (e.g. a Telegram chat id). Not a Fermix session id.
network_readiness_enabled true When enabled, a job run that fires at host-wake time first waits on a short TCP readiness probe to the primary provider before the first model call.

Delivery settings are copied into each job at creation time. Changing the default afterward does not retarget existing jobs.

[fermix_core.jobs]
default_delivery_mode = "channel"

[fermix_core.jobs.default_delivery_target]
platform = "telegram"
chat_id = "8217352118"

[fermix_core.routing]

Model routing overrides for sub-agents and scheduled jobs. All three keys apply independently to both subagent_* and cron_* groups.

Key Notes
subagent_model Model slug (the short identifier for a model, e.g. gpt-5.4-mini) for sub-agent runs.
subagent_provider Provider for sub-agent runs. When omitted, a bare subagent_model runs on the primary provider (the model’s catalog owner is used only when no primary is configured) — set this explicitly to run sub-agents on a non-primary provider.
subagent_reasoning_effort Reasoning effort for sub-agent runs.
cron_model Model slug for scheduled job runs.
cron_provider Provider for scheduled job runs. When omitted, a bare cron_model runs on the primary provider (the model’s catalog owner is used only when no primary is configured) — set this explicitly to run jobs on a non-primary provider.
cron_reasoning_effort Reasoning effort for scheduled job runs.

These can also be set at runtime with the model_routing_config tool or via the web setup sub-agent panel on the primary provider’s configuration page.

Selects the search backend for the web_search built-in tool. When this section is absent, Fermix uses keyless DuckDuckGo, so most installs need nothing here.

Key Notes
backend One of "duckduckgo" (default, keyless), "tavily", "exa", "parallel", "brave", "perplexity", "firecrawl". An unrecognized value falls back to DuckDuckGo.
tavily_api_key / exa_api_key / parallel_api_key / brave_api_key / perplexity_api_key / firecrawl_api_key API key for the matching backend. These live in this section and nowhere else: after setup the value is the @keyring sentinel and the real secret is read from the OS keychain. Names like TAVILY_API_KEY are keychain entry names, not environment overrides — exporting them has no effect.

If a configured non-DuckDuckGo backend hard-errors (bad key, no credits, transport failure), web_search degrades once to DuckDuckGo and logs a warning — it does not silently swallow the failure.

Controls tool-schema deferral, which is on by default. Deferral means the model is not given the full definition of every tool up front; it looks them up as needed, saving tokens. When enabled, plugin and MCP tool schemas (the detailed input descriptions) are left out of requests to the provider (names stay listed in the prompt) and three bridge tools are registered: tool_search (keyword search over deferred schemas), tool_describe (fetch one schema on demand), and tool_call (invoke a deferred tool by name).

Key Default Notes
enabled true Set to false to send all tool schemas inline and remove the bridge tools.

[fermix_core.tools.generate_image]

Configuration for the generate_image built-in tool.

Key Notes
backend Image generation provider. One of "openai", "openai_codex", "xai", "google".
model Model identifier for the chosen backend.
size Default image size (backend-specific format).
google_api_key API key for the Google backend, stored in the OS keychain as @keyring after setup. The OpenAI and xAI backends reuse that provider’s chat key, and openai_codex needs no key at all.

The openai_codex backend runs on a connected ChatGPT/Codex login instead of an image API key — billed to that subscription. It is opt-in and fails loudly if the login is missing or not entitled; it never silently falls back to another backend. The keys in the table above are the only ones this section accepts; any other key stops the daemon from booting.

[fermix_core.transcription]

Speech-to-text settings for inbound voice notes and audio attachments. An unknown key, an unknown backend, or a non-positive max_file_mb fails config load loudly.

Key Default Notes
backend "openai" Speech-to-text provider. One of "openai", "xai", "deepgram". The on-device "local" backend is reserved for a later phase; naming it errors clearly.
model "gpt-4o-mini-transcribe" Transcription model, a single key shared across backends — switching backend in setup snaps it to the new backend’s default (OpenAI gpt-4o-mini-transcribe, Deepgram nova-3; the xAI backend is modelless and sends no model).
openai_api_key / xai_api_key Per-backend API-key override, set in this block. When unset, the OpenAI and xAI backends reuse that provider’s chat key — which OPENAI_API_KEY or XAI_API_KEY can supply. The xAI (SpaceXAI) speech-to-text endpoint requires an API key — a Grok-subscription OAuth token does not work for transcription.
deepgram_api_key Required for the Deepgram backend, which has no chat provider to reuse. Set it in this block.
max_file_mb 20 Audio size cap, enforced against the declared size before download when the attachment carries one, otherwise against the downloaded file.

Keys are stored in the OS keychain as @keyring after setup. Configure from the web setup Transcription tab or with fermix setup --transcription-backend/--transcription-model/--transcription-api-key (the generic key flag stores under the selected backend’s slot). fermix doctor has a transcription row reporting the active backend and whether its credential resolves.

[fermix_core.computer_use]

Experimental and off by default. Computer use lets the agent drive your real desktop by taking screenshots and moving the mouse and keyboard. It is the most dangerous capability Fermix has — ambient control of your live logged-in session with no undo, and screenshots the model must treat as untrusted content — so it ships off and must be turned on deliberately. See capabilities and tools for the full safety model.

Turning it on is one operator step: set enabled = true in this section and restart the daemon. Computer use needs a small native helper alongside the daemon, but you do not install it by hand. On a real daemon boot, if computer use is enabled and the helper matching your build is missing, Fermix fetches it before the readiness gates run: the helper comes from the compux project’s own signed release and is verified against a SHA-256 checksum baked into your Fermix build, then cached under ~/.fermix/plugins/compux/. That is what keeps computer use working across an upgrade that changes the helper version. It happens on daemon boot only (not during fermix setup), is bounded to about 30 seconds, and is fail-soft — a failed fetch leaves computer use off until the next restart or the setup card.

The setup Plugins page (the Computer Use card) is the interactive route: it installs the helper on demand and reports install and permission status. Computer use is supported only on Apple Silicon (M-series) macOS and Linux x86_64; Intel Macs are unsupported and the install fails loudly.

The capability is offered to the model only once it is enabled and the helper binary is installed. Operating-system permissions (macOS Screen Recording and Accessibility, or X11 versus the unsupported Wayland on Linux) are checked separately by fermix doctor’s computer use check, not by this flag — without Accessibility granted, clicks and keystrokes are silently dropped while screenshots still work.

Key Default Notes
enabled false Turn the feature on. Requires a daemon restart.
display 0 Which display to capture, by index.
screenshot_after true Return a fresh screenshot after every mutating action so the model can verify the result.
max_actions 80 Per-session action budget — halts a runaway loop.
max_retained_screenshots 3 How many recent screenshots to keep in the model’s context.
courtesy "yield" Whether the agent steps aside for a present human before an action that would move the pointer or type. "off" disables it. Idle detection is macOS-only. Where it is unavailable the action proceeds, so this is a courtesy that keeps the agent from fighting you for the cursor, not a safety boundary.
courtesy_idle_ms 1000 How much input quiet counts as you being idle.

There is no mode key: computer use is host-desktop control only, so a legacy mode entry in an old config is ignored. There is also no separate posture key — the tool’s access posture (whether it can only look, must confirm before irreversible actions, or acts autonomously) is derived 1:1 from [sandbox] mode: strict looks only, standard acts but confirms irreversible actions conversationally, open acts autonomously. Computer use is operator-only, never delegated to sub-agents, and a host session starts only from an attended origin (an interactive chat, fermix ask, or the voice companion) — scheduled and cron runs cannot start it.

[fermix_core.plugins]

Key Notes
enabled Array of plugin names that are turned on. Managed by fermix plugins enable/disable and the setup Plugins page rather than edited by hand.
dev_local Path to a local plugin checkout directory (e.g. a fermix-plugins repo’s plugins/ subdirectory). Subdirectories load as plugins without an install step. For development use only.

Per-plugin configuration lives under [fermix_core.plugins.<name>] (manifest-declared values in UPPER_SNAKE form, set with fermix plugins config set NAME KEY VALUE and injected into an MCP plugin’s process environment).

[fermix_core.plugin_secrets]

Per-plugin static api_key credentials, keyed by plugin name. After fermix plugins auth set NAME VALUE, the secret is stored in the OS keychain and the entry here holds the @keyring sentinel rather than plaintext. A plugin that authenticates with a static key reports needs_secret until one is set. The Slack, Discord, and AgentMail plugins use this path. See auth and secrets.

[fermix_core.oauth.<provider>]

OAuth client credentials for plugin OAuth providers. Valid provider names: google, github, notion, x, slack.

Key Notes
client_id OAuth application client ID.
client_secret OAuth application client secret. Stored in the OS keychain as @keyring after setup.

Logging and traces

The daemon log (~/.fermix/logs/fermix.log, rotated) and the JSONL trace directory (~/.fermix/traces, written as YYYY-MM-DD/<type>.jsonl) are not configured through config.toml. Their paths are set by the release defaults and can be overridden only with the FERMIX_LOG_FILE and FERMIX_TRACE_DIR environment variables (see the environment variables table below). See traces and telemetry.

[fermix_core.realtime]

Local Realtime voice companion configuration. The keys below correspond to flags accepted by fermix setup --reconfigure --realtime-enabled .... Removed keys that will raise on startup: tool_policy, allow_network_tools, turn_detection, activation, max_buffer_chunks, idle_timeout_ms, max_input_audio_seconds_per_session.

Key Notes
enabled true/false. When true, the daemon opens a 0600 Unix-domain socket at ~/.fermix/realtime.sock on startup.
provider Only "openai" is supported.
model OpenAI Realtime model identifier.
voice Voice name (e.g. "marin").
reasoning_effort Reasoning effort for the voice agent, sent on the OpenAI Realtime session.update (nested under reasoning). One of "minimal", "low", "medium", "high", "xhigh". Defaults to "low". Also selectable in the web setup Realtime pane; there is no fermix setup flag for it.
max_session_minutes Per-session duration cap.
max_estimated_cost_cents_per_session Per-session estimated cost cap in cents.
persist_transcripts When true, stores final spoken text as voice_turn memory rows with source_type = "realtime". Defaults to false. 
[fermix_core.realtime]
enabled = true
provider = "openai"
model = "gpt-realtime-2"
voice = "marin"
max_session_minutes = 15
max_estimated_cost_cents_per_session = 100
persist_transcripts = false

See realtime voice.

[sandbox]

Controls the sandbox (the walled-off environment that limits which files and commands a tool can touch) applied to shell tool calls. See sandbox.

Key Default Notes
mode "standard" Sandbox strictness. One of "standard", "strict", "open".
workspace_root ~/.fermix/workspace Primary workspace root inside the sandbox.
allowed_roots [] Additional filesystem roots to allow beyond the mode defaults. Approved grants persist here — fermix grant path PATH and an owner-confirmed request_directory_access request append the granted root; fermix sandbox explain labels these roots (granted).
blocked_roots [] Roots to block regardless of mode.

Fermix’s own home directory is not a key here — it is derived from FERMIX_HOME and is always refused as a grant root. It also does not control what open mode exposes or what the credential blocklist protects; those key off the real OS home ($HOME), which is detected separately.

The shell command allow-set (bare, assistant, or extended) is configured in its own [sandbox.commands] sub-table via the profile key (default "bare"), not here. See sandbox for command profiles and per-command tool definitions.

[sandbox.env]

Controls which environment variables are visible to sandboxed processes.

Key Notes
mode "selected" exposes only explicitly listed vars; "all" passes the full environment.
allow Array of variable names to allow (used with "selected" mode).
deny Array of variable names to deny (used with "all" mode).

Sub-blocks [sandbox.env.<NAME>] declare per-key resolvers (each names a source of "env" or "command"). See sandbox for the full env source reference.

[fermix_channels.<platform>]

One sub-table per channel. Valid platform names: telegram, whatsapp, slack, discord, signal.

Key Notes
enabled true/false.
owner_user_id The operator’s external user id on this platform. Required for operator-level trust. Also serves as the ingress allowlist when no explicit allowed_user_ids is set.
allowed_user_ids / allowed_sender_ids Guest list. Users listed here receive :guest (read-only chat) trust.
command_allowlist Ids permitted to run slash commands without full ingress allowlist membership.
streaming Whether replies appear bit by bit as the model writes them, instead of all at once when finished. Off by default. "draft" edits a single draft message in place as it grows (Telegram only; fermix doctor warns on unsupported channels). "block" sends each completed chunk of the model’s output as its own message (works on every channel). Both require a streaming-capable provider.

Per-platform credential keys:

Platform Keys
Telegram bot_token
WhatsApp app_secret, verify_token (webhook); access token and phone number id via env vars
Slack bot_token, signing_secret
Discord bot_token, bot_user_id
Signal account, cli_path

After a normal fermix setup, channel secrets are stored in the OS keychain and these keys hold the @keyring sentinel or are absent. See auth and secrets and ingress and trust.

The Telegram bot_token is deliberately not read from the environment: a single exported TELEGRAM_BOT_TOKEN would collide across instances, so the token lives only in each install’s config.toml (keychain-backed). Run a second instance under its own FERMIX_HOME with its own bot token.

[fermix_channels.telegram]
enabled = true
owner_user_id = "123456789"
command_allowlist = ["987654321"]

Use /whoami from the target account to discover the platform user id to place in owner_user_id or allowed_user_ids.

[mcp.servers.<name>]

Outbound MCP server definitions. Each named sub-table configures one MCP server that Fermix can invoke as an external tool source.

Key Notes
command Executable to run.
args Argument list.
env Static environment variables for the subprocess.
pass_env List of host env var names to forward to the subprocess.

Per-tool policy sub-blocks: [mcp.servers.<name>.tools.<tool_name>] accepts policy_class and hidden_from_agent to control sandbox policy and visibility per tool.

[mcp.inbound]

Inbound MCP surface configuration. Currently not wired into the supervision tree. See MCP.

Environment variables

Secrets are normally stored in the OS keychain after fermix setup completes. The API-key and channel-token variables below are for headless or container deployments that inject secrets through the environment. The FERMIX_* operational variables are always environment-only knobs.

Variable Required Description
OPENAI_API_KEY When the openai provider is configured, or for Realtime voice OpenAI API key. Realtime voice reuses this key. openai_codex uses OAuth, not this key.
ANTHROPIC_API_KEY When the Anthropic provider is configured Anthropic API key.
XAI_API_KEY When the xAI provider is configured xAI (Grok) API key.
OPENROUTER_API_KEY When the OpenRouter provider is configured OpenRouter API key.
MISTRAL_API_KEY When the Mistral provider is configured Mistral API key.
OLLAMA_BASE_URL When the Ollama provider is configured Base URL of the Ollama OpenAI-compatible endpoint (default http://localhost:11434/v1).
XAI_BASE_URL No Override the xAI API base URL.
FERMIX_ANTHROPIC_AUTH_MODE No Overlay the Anthropic auth mode (api_key or oauth).
FERMIX_XAI_AUTH_MODE No Overlay the xAI auth mode (api_key or oauth).
WHATSAPP_ACCESS_TOKEN If WhatsApp is enabled WhatsApp Cloud API access token.
WHATSAPP_PHONE_NUMBER_ID If WhatsApp is enabled WhatsApp phone number id.
WHATSAPP_VERIFY_TOKEN If WhatsApp is enabled Webhook verification token.
WHATSAPP_APP_SECRET If WhatsApp is enabled Webhook HMAC signing secret.
DISCORD_BOT_TOKEN If Discord is enabled Discord bot token.
DISCORD_BOT_USER_ID If Discord is enabled Discord bot user id.
SLACK_BOT_TOKEN If Slack is enabled Slack bot token.
SLACK_SIGNING_SECRET If Slack is enabled Slack request signing secret.
SIGNAL_ACCOUNT If Signal is enabled Signal phone number or account identifier.
SIGNAL_CLI_PATH No Override the signal-cli executable path (also settable via config.toml).
FERMIX_HOME No Override the config and workspace root directory. Default: ~/.fermix.
FERMIX_TRACE_DIR No Override the trace output directory. Default: $FERMIX_HOME/traces.
FERMIX_LOG_FILE No Override the log file path. Default: $FERMIX_HOME/logs/fermix.log.
FERMIX_HTTP_BIND No Phoenix endpoint bind address. Default: 127.0.0.1 (loopback only). Set to 0.0.0.0 to accept network connections; doing so also exposes the setup surface, so place it behind a trusted network.
FERMIX_REALTIME_ENABLED No Enable the Realtime voice companion mode.
FERMIX_REALTIME_PROVIDER No Realtime provider. Only openai is supported.
FERMIX_REALTIME_MODEL No Override the OpenAI Realtime model.
FERMIX_REALTIME_VOICE No Override the Realtime voice name.
FERMIX_REALTIME_MAX_SESSION_MINUTES No Per-session voice duration cap.
FERMIX_REALTIME_MAX_COST_CENTS No Per-session estimated cost cap in cents. Short alias.
FERMIX_REALTIME_MAX_ESTIMATED_COST_CENTS_PER_SESSION No Long-form alias for FERMIX_REALTIME_MAX_COST_CENTS.
FERMIX_REALTIME_PERSIST_TRANSCRIPTS No Persist final voice transcripts as local memory text.
PORT No Phoenix HTTP port. Default: 4030.
PHX_HOST No Public hostname for generated URLs. Default: localhost.
FERMIX_TRACE_CONTENT No Force trace content (prompt/response bodies) capture on (1) or off (0), independent of Opik. Off by default.
FERMIX_OPIK_ENABLED No Enable Opik trace export (also turns on trace content capture unless FERMIX_TRACE_CONTENT=0).
FERMIX_OPIK_BASE_URL No Opik server base URL.
FERMIX_OPIK_PROJECT No Opik project name. Default: fermix.
FERMIX_OPIK_API_KEY No Opik API key (never written into an installed service unit).

Provider selection, model, reasoning effort, and the primary flag are deliberately not environment-settable — they are owned by config.toml. Environment variables override config.toml values at runtime (layer 3 of the precedence chain). In development and test runs, credential variables default to empty strings.

Next steps

Auth and secrets How Fermix stores OAuth tokens and API keys, resolves channel secrets from the OS keychain, and verifies plugin signatures with cosign.Quickstart Install Fermix, connect a channel, and send your first message in a few minutes.Channels How Fermix handles messages from Telegram, WhatsApp, Slack, Discord, Signal, and the local CLI through one common path to the agent, and the slash commands available in every channel.