# 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](/docs/setup) 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](/docs/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](/docs/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](/docs/providers-and-models) for the full per-provider key list.

Example:

```toml
[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](/docs/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](/docs/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](/docs/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.

```toml
[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.

## `[fermix_core.tools.web_search]`

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.

## `[fermix_core.tools.tool_search]`

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](/docs/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](/docs/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](#environment-variables) table below). See [traces and telemetry](/docs/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`. |

```toml
[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](/docs/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](/docs/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](/docs/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](/docs/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](/docs/auth-and-secrets) and [ingress and trust](/docs/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.

```toml
[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](/docs/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.

## Related pages

- [Setup](/docs/setup): first-run wizard, flags, and idempotent re-runs.
- [Auth and secrets](/docs/auth-and-secrets): keychain storage, `@keyring` sentinel, and the OAuth token store.
- [Providers and models](/docs/providers-and-models): model catalog, routing, and fallback chain.
- [Sandbox](/docs/sandbox): filesystem modes, command profiles, and env source resolvers.
- [Channels](/docs/channels): per-channel setup and ingress trust model.
- [Realtime voice](/docs/realtime-voice): voice companion setup and companion app.
- [Traces and telemetry](/docs/traces-and-telemetry): JSONL trace format and telemetry events.
- [Scheduled jobs](/docs/scheduled-jobs): job delivery targets and expiry.