Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Configuration

Fontaine reads TOML settings from several places and merges them into one configuration. Every key is documented below with its meaning, its default and the scopes that may set it.

A key marked “accepted and validated; not yet active” is parsed and checked at load, and a bad value is a configuration error, but nothing consults it yet.

Where files live

WhatLinuxmacOSWindows
Config dir~/.config/fontaine~/Library/Application Support/fontaine%APPDATA%\fontaine
Data dir~/.local/share/fontaine~/Library/Application Support/fontaine%APPDATA%\fontaine

The platform defaults come from the dirs crate. Two environment variables override them, and tests use them to stay inside temporary directories:

  • FONTAINE_CONFIG_DIR replaces the config dir.
  • FONTAINE_DATA_DIR replaces the data dir.

If a directory has no platform default and no override, Fontaine exits with code 2 and names the variable to set.

Files in these directories:

FilePurpose
<config dir>/config.tomlThe user settings file.
<config dir>/mcp-local.tomlThe local-scope MCP servers, keyed by workspace root, written by fontaine mcp add. Readable by the current user only; the agent’s file tools cannot write it unprompted. It is not a settings file.
<config dir>/plugins.tomlThe plugin and marketplace registry, written by the fontaine plugin CLI and by the plugin auto-update pass. It is not a settings file.
<config dir>/skill-trust.tomlThe skills whose allowed-tools you trusted, each pinned to a digest of the skill file (see Skill trust). Written by fontaine plugin trust and /skills trust; not a settings file, and not the workspace trust.toml.
<data dir>/trust.tomlWorkspace trust record (see Workspace trust).
<data dir>/credentials.tomlStored API keys (see Credentials).
<data dir>/claude-cache-verdicts.jsonThe Claude CLI versions, each with the reminder wording it replayed, that a claude-subscription account’s cache self-check found not reading the replayed context back, so a restart keeps the fallback layout; entries expire after 7 days, and a new wording starts clean. Readable by the current user only; safe to delete.
<data dir>/claude-capture/Only with FONTAINE_CLAUDE_CAPTURE set: one <session>-<token>.jsonl per connection (request indices restart per file) holding the frames a claude-subscription account sent to the CLI and the results it returned, unredacted, and a .bodies/ directory for the CLI’s own raw API bodies (see Capturing traffic). The directory and .bodies/ are readable by the current user only (0700) and the files 0600; safe to delete.
<data dir>/auto_mode/<project>/environment.jsonThe project facts fontaine auto-mode setup collected for the guardian (setup also writes [guardian.composition] to the user settings file when you accept its offer). Readable by the current user only; the agent’s file tools cannot write it unprompted.
<config dir>/config.lock, <config dir>/plugins.lock, <config dir>/skill-trust.lock, <config dir>/fontaine-receipt.lock, <data dir>/trust.lock, <data dir>/credentials.lock, <data dir>/claude-cache-verdicts.lock, <data dir>/update-state.lockEmpty lock files beside the files they guard. Sessions hold one while they edit that file, so concurrent edits do not overwrite each other, and briefly while they read the settings or trust file, so a read waits for an edit in progress; safe to delete when no session is running.
<data dir>/history.jsonlWhat you submitted in the terminal UI, for Up and Ctrl-R recall (see History). Readable by the current user only.
<data dir>/update.stampWhen the automatic self-update pass last ran, so it runs at most once a day.
<data dir>/update.lockHeld by the pass while it checks, so two sessions starting together check once.
<data dir>/updates.jsonlOne JSON line for each automatic update check or update (timestamp, channel, installed and candidate version, outcome, reason). Readable by the current user only.
<data dir>/update-applied.jsonThe build a background update installed, so the next start can announce it once; deleted after.
<data dir>/update-state.jsonWhich failed update was already shown, so a warning appears once.
<data dir>/update-skipThe build fontaine update --rollback rolled back from, which the automatic update does not reinstall.
<data dir>/update-staged/Windows only: a verified archive waiting for the update helper.
<data dir>/update-helper/, <data dir>/update-helper.lockWindows only: the helper’s copy of the executable and its one-helper lock.
<data dir>/plugin-update.stampWhen the plugin auto-update pass last ran, so it runs at most once a day.
<data dir>/plugin-updates.jsonlOne JSON line for each plugin or marketplace update the pass staged, held or failed. Readable by the current user only.
<data dir>/recent_models.jsonThe models you last switched to with /model and /guardian-model, for the picker’s Recent group (see Choosing a model). Readable by the current user only.

Files that hold secrets or trust decisions are created readable by the current user only: mode 0600 on Unix, a current-user-only ACL on Windows.

The settings scope stack

Settings come from up to five scopes. Higher scopes win, listed here highest first. MCP servers have two more sources, covered below the list:

  1. managed: a reserved slot. It is empty and no file is read for it.
  2. CLI: the file named by --settings <file>. It applies to one session and has user trust.
  3. project-local: <workspace>/.fontaine/settings.local.toml. It has user trust only while Fontaine can show it is a personal file (see Workspace trust); otherwise it loads as project scope.
  4. project: <workspace>/.fontaine/settings.toml. It is shared with the repository and may only tighten.
  5. user: <config dir>/config.toml. It may set every key.

MCP servers also come from <config dir>/mcp-local.toml (local scope: the entries for this workspace, with user trust, between the CLI and project-local scopes) and from the repository’s .mcp.json (project scope, under .fontaine/settings.toml, which wins a name collision with a warning). Neither holds any other setting. The scope stack that fontaine doctor and the debug file list shows them as local and a second project entry when the files exist.

The workspace is the project directory (the launch directory, or --cd), after symlinks are resolved. Project files are read only from it: there is no search through parent directories and no nested settings files. A missing project, project-local or user file is treated as empty. A file that exists but cannot be read, such as a directory in its place, is a configuration error that names the path. A missing or unreadable --settings file is also an error.

--settings takes the path of a TOML file. It does not accept inline text.

In the terminal UI, /config shows each key’s effective value and the scope that supplied it, and edits a few preferences in the user file; it never writes a project file. See the settings panel. fontaine doctor shows the same provenance without a session, reports every layer that fails to load (including a project key the scope policy refused) instead of stopping at the first, and checks trust, models and MCP servers; see fontaine doctor.

Merge rules

  • Scalars: the highest scope that sets the key wins.
  • Lists (deny, ask, allow, additional_directories, [auto_mode] lists, allow_extra, hooks): the union across scopes. A scope can add only to the lists its column below allows.
  • Named table entries ([accounts.<name>], [mcp.servers.<name>], [agents.types.<name>]): the highest scope that defines the name replaces the whole entry. Entries are never merged field by field.
  • [network]: merged per key, with --settings over the user file. An account’s own network keys are then laid over it key by key for that account (see [network]).
  • Map-valued keys ([telemetry] resource_attributes, [env]): merged per key, and the higher scope wins a shared key.
  • [[hooks.*]] arrays: the union.

Strictness

  • An unknown key or section in any scope is an error, so a misspelled [permisions] cannot silently drop deny rules.
  • A key that a scope may not set is an error at load, naming the key and the scope.
  • A permission rule that does not parse, or that names a tool that is neither built in nor an mcp__ name, is an error.

All configuration errors exit with code 2.

Per-key scope table

The user file may set every key. Every key has a declared policy for the other scopes, and a key without one is refused from project and project-local files. For those scopes:

KeyProjectProject-local (user trust)CLI
[accounts.*], including their network keysnonoyes
[network]nonoyes
[websearch]nonoyes
[models.roles]nonoyes
[model] model, effort, max_output_tokensnoyesyes
[guardian] model, profile, timeout_secs, confidence_threshold, cachenoyesyes
[guardian] scanner, scanner_command, scanner_model_path, scanner_hf_token_envnonono
[feedback]nonoyes
[remote]nonoyes
[guardian.composition]shadow = true onlyshadow = true onlyshadow = true only
[permissions] default_modemanual or dontAsk onlymanual or dontAsk onlyyes
[permissions] deny, askadd onlyadd onlyadd only
[permissions] allownoyesyes
[permissions] additional_directoriesnoyesyes
[permissions] auto_tracked_edits, auto_scratch_writes, auto_shell_editsfalse onlyfalse onlyyes
[auto_mode] environment, allow, setup_remindernoyesyes
[auto_mode] soft_deny, hard_denyadd onlyadd onlyadd only
[agents] keys and [agents.types]noyesyes
[context] autocompact_windownoyesyes
[schedule] enablednonoyes
[memory] autononoyes
[goal] keysnonoyes
[retry] keysnonoyes
[headless] max_usage_wait_secsnonoyes
[headless] require_trustnonoyes
[headless] on_usage_limitexit onlyexit onlyyes
[afk] temperature_ceilinglower only, positive and finitelower only, positive and finiteyes
[shell] max_timeout_secsnonoyes
[statusline]nonono
[checkpoints] keysnonono
[plugins] auto_updatenonono
[updates] auto_updatenonono
[shell_preclassifier] allow_extranoyesyes
Agent files agents/*.mdnarrowing onlyn/an/a
[[hooks.*]]yes, after workspace trust; allow ignoredyes, after workspace trustyes
[mcp.servers.*]yes, after workspace trust and your approval of each serveryes, after workspace trustyes
[mcp] tool_searchyesyesyes
[mcp] native_tool_searchyesyesyes
[lsp.servers.*]nonoyes
[telemetry]enabled = false onlyenabled = false onlyyes
[tui]nonoyes
[keybindings]nonoyes
[env]noyesyes

A project-local file that has not earned user trust is validated against the project column.

Trust asymmetry

Shared project settings can add deny and ask rules and [auto_mode] soft_deny and hard_deny entries, because those can only make Fontaine stricter. They cannot add allow rules, choose a model or an endpoint, widen the workspace, or change anything that loosens a decision. Project hooks and MCP servers may be declared; a project-declared executable can tighten a permission decision (a hook’s deny or ask, an MCP tool’s requiresUserInteraction marker) but never loosen one.

[env] can put a different PATH in front of the system’s or point tools at a proxy, so it comes only from user-trust scopes: your user file, --settings and a project-local file that has earned user trust. A shared project file with an [env] table is an error.

[guardian] profile is a loosening knob, so it is settable from user-trust scopes only. No key in any scope turns the guardian off.

Key reference

[accounts.<name>]

Named model accounts; the provider guide compares the kinds and gives a minimal example of each. Several accounts of one kind are allowed, and each keeps its own endpoint and credential. A model is addressed as <account>/<model>, split at the first /, so a model id may contain slashes of its own (router/anthropic/claude-sonnet-4-6).

KeyMeaningDefault
kindanthropic, openai, gemini, openai-compatible, kimi, ollama, opencode-go, databricks, openrouter or claude-subscription; the provider guide compares them. Required.none
api_key_envThe name of the environment variable that holds the key. Omit it to use the stored credential. Raw keys are never accepted inline. Refused for opencode-go, which signs in instead.unset
base_urlEndpoint override. Required for openai-compatible and databricks (the workspace origin, with no path).the provider’s public endpoint
modelsExplicit model list. Without it the provider is asked which models it offers.unset
wiresopencode-go and databricks only: a table from model id to the wire it is served on (chat, responses, messages or gemini), for a model the built-in routing gets wrong.unset
model_factsanthropic and databricks only: a table from a model id this account serves under a name of its own (an Azure Foundry deployment, a custom serving endpoint, a proxy’s alias) to the catalog model it serves (a Claude model on anthropic; a Claude, GPT or Gemini model on databricks), so the name takes that model’s context window, output limit and tool-choice behavior. The name is not renamed anywhere else. A mapping on anthropic stays unpriced, because it is meant for limits and tool behavior; on databricks the mapped name takes its target’s list price, which is the only way a custom endpoint there can be priced at all. A value the catalog does not resolve, or a key the catalog already lists, is refused. User scope only. See model discovery.unset
context_tokensollama only: the context window requested with every call (options.num_ctx), at least 2048.16384
prompt_cachinganthropic, openrouter, opencode-go and databricks only: whether requests carry cache breakpoints, so the provider reuses the unchanged prefix at a fraction of the input price. On anthropic they sit on the tools, the system prompt and the latest message. On openrouter the conversation carries one top-level marker for every model except the self-caching openai/, deepseek/, x-ai/ and groq/ upstreams, which are sent none, and the guardian marks its system prompt. On opencode-go and databricks it affects only models served on the Messages wire (Claude, on databricks); the other wires cache by prefix on their own. User scope only, because it changes spend and what the provider stores.true for anthropic, openrouter and databricks, false for opencode-go
cache_ttlanthropic, openrouter, opencode-go and databricks only: how long a cached prefix lives, "5m" or "1h". The one-hour lifetime costs more per cache write, and is not offered to the self-caching openrouter upstreams, which keep their own lifetime. Has no effect when prompt_caching is off. User scope only."5m"
context_editinganthropic only: a table that turns on Anthropic’s server-side clearing of old tool results, so a long session stops resending them on every request. The stored conversation is untouched; only what the model reads is trimmed. Keys: enabled (default false); trigger_tokens (the input size that starts a clearing, default 100000); keep (the newest tool uses that stay, at least 1, default 3); clear_at_least_tokens (a clearing that would free fewer input tokens is skipped, below trigger_tokens, default 20000); exclude_tools (tools whose results are never cleared; unset keeps board_show, board_update, memory, todo_write and tool_search, [] keeps none, an MCP tool is named by its cleaned name, mcp__<server>__<tool>, where characters outside [A-Za-z0-9_-] become _). Each clearing invalidates the cached prefix from the cleared point on, so a clearing costs one cache rewrite. The session’s own compaction still estimates the full stored history, so it may fire earlier than trigger_tokens alone suggests. Only the main agent and its subagents send the context_management field, but the beta header goes on every request from the account, guardian and side calls included; a host that rejects the beta makes the guardian fail closed, so do not enable this on an account used only for the guardian. User scope only.off
thinkollama only: false asks a thinking model to answer without reasoning, which is much faster. true and unset leave the model’s default. An explicit effort wins over it, and effort = "off" equals think = false for the main agent.unset
thinking_offdatabricks and openrouter: whether the guardian’s and the scanner’s forced-call requests carry the Chat wire’s reasoning-off parameter ({"reasoning_effort": "none"}, the value Databricks documents for turning a hybrid reasoning model’s thinking off), so a model that thinks by default can give a verdict. On databricks unset sends it; false leaves it out, for a workspace that refuses it. Only models served on the Chat wire get it. A workspace that refuses it anyway costs the first attempt: Fontaine retries without the parameter and does not send it again for the rest of the session. The gateway’s thinking field belongs to the Claude models it also serves, and is accepted and ignored for the others. openrouter is opt-in: true sends {"reasoning": {"enabled": false}}, which OpenRouter normalizes across upstreams and drops for a model that does not support reasoning; unset or false sends nothing. The main agent’s requests never carry it: the agent reasons at its own default, or as effort sets it where the endpoint takes a level.databricks: sent; openrouter: not sent
quotaopenai-compatible only (a kimi account shows its subscription quota with no quota key, like claude-subscription): "kimi" shows the account’s subscription quota in the status bar and in headless result.account_usage, read from Kimi for Coding’s GET <base_url>/usages. User scope only, because it sends the account’s key in extra requests.unset
authanthropic only: how the key is sent. "bearer" sends Authorization: Bearer <key> instead of x-api-key, which OpenRouter’s Anthropic endpoint, LiteLLM and similar gateways require (a Databricks workspace has its own databricks kind); it applies to requests and to model discovery alike. User scope only."x-api-key"
cli_pathclaude-subscription only: the absolute path of the official claude executable.claude on PATH
claude_config_dirclaude-subscription only: the absolute path of the CLI’s own config directory, handed to it as CLAUDE_CONFIG_DIR for this account only, so two accounts can keep separate logins.unset
https_proxy, http_proxy, no_proxy, ca_bundle, client_cert, client_keyOverride the same key of [network] for this account only.the [network] value

Account names are not empty and contain no /. Accounts can be set from the user file or from --settings only: a project file cannot choose an endpoint or a credential source. The per-account network keys are edited by hand; the account setup flow in the terminal UI writes only kind and base_url.

A host that serves Claude under a name of its own maps it to the catalog model with model_facts:

[accounts.foundry]
kind = "anthropic"
base_url = "https://my-resource.services.ai.azure.com/anthropic"
auth = "bearer"
models = ["prod-opus", "team-haiku"]

[accounts.foundry.model_facts]
prod-opus = "claude-opus-5-5"
team-haiku = "claude-haiku-5-5"

What each kind talks to:

KindWireDefault endpointCredential
anthropicMessages APIhttps://api.anthropic.comrequired
openaiResponses APIhttps://api.openai.com/v1required
geminigenerateContenthttps://generativelanguage.googleapis.comrequired
ollamaOllama’s native /api/chathttp://localhost:11434optional
openai-compatibleChat Completionsnone; base_url is requiredoptional
kimiChat Completionshttps://api.kimi.com/coding/v1optional
opencode-goChat Completions, Responses, Messages and generateContent, per modelhttps://opencode.ai/inference/gosign-in
databricksChat Completions, Responses, Messages and generateContent, per modelnone; base_url is the workspace origin and is requiredrequired, sent as a Bearer token
openrouterChat Completions, with prompt cachinghttps://openrouter.ai/api/v1required
claude-subscriptionMessages API, through the installed Claude Code CLInonethe CLI’s own login

An openai-compatible endpoint speaks Chat Completions, not the Responses API, and its models are unpriced, so --max-budget-usd does not apply to them. The same holds for a kimi account, whose subscription is flat-rate; the moonshot.ai pay-as-you-go API is a different product and stays on openai-compatible.

A flat-rate account has no token price worth estimating; its own quota is the budget signal. A kimi account reads it built in, from https://api.kimi.com/coding/v1/usages, with no quota key; for an openai-compatible account it is the quota = "kimi" opt-in instead. Fontaine asks for the account’s usage windows when the account’s model is in use, then every minute, with the account’s key as the bearer token (no Authorization header when the account has none) and a 10 second timeout. No credential other than the account’s own is sent, and only to the account’s own endpoint. It is display only: it never affects permissions or the guardian, and a failure is reported once and hides the segment. The same applies to the account the guardian runs on, and a headless run asks once per result line instead of every minute.

[accounts.kimi]
kind = "kimi"
api_key_env = "KIMI_API_KEY"

Where a credential comes from

  1. If the account sets api_key_env, the key is that environment variable. An unset or empty variable is a configuration error (exit code 2) when the main model uses the account, for any kind; the stored credential is not consulted as a fallback.
  2. Otherwise the key is the account’s entry in credentials.toml, written by /login in the terminal UI.
  3. With neither, an ollama, openai-compatible or kimi account sends no Authorization header. An anthropic, openai, gemini, databricks or openrouter account with no key is a configuration error (exit code 2) when the main model uses it.

An opencode-go account has no key. Its credential is the sign-in that /login <account> stores, and an account that has not signed in is a configuration error (exit code 2) that names that command.

A claude-subscription account has no Fontaine credential at all: the installed Claude CLI owns the login, a stored key or an api_key_env is refused or ignored, and /login only checks the CLI. See Claude subscription. Its 5-hour and weekly plan usage shows in the status bar from the first turn on, with no quota key.

The guardian is different: a missing or invalid credential on the account of [guardian] model never stops startup. The guardian is then unavailable, and every decision that needs it fails closed.

Model discovery

An account with a models list accepts exactly those names. An account without one is asked for its model list (/models for OpenAI-style endpoints, /api/tags for Ollama, the provider’s model listing otherwise), once, and only for the account that [model] model or --model names. A model the account does not offer is a configuration error (exit code 2). A listing call that fails, whether by a transport error, a non-2xx status or a 401/403, is a run failure (exit code 1). For Ollama a bare name matches the latest tag.

A model this build of Fontaine does not list in its model catalog, such as a release newer than the build, takes its limits and features from the newest listed model of the same name pattern, with no price. The name pattern is the id with its version numbers taken out: the parts between -, _, / and : made only of digits and dots, a run of them counting as one, so claude-haiku-9-9 takes the newest listed claude-haiku-* and gpt-9.9-mini the newest listed gpt-*-mini. Only a listed model of the same catalog vendor counts, and a deprecated one or one without an output limit never does. Fontaine warns once whenever such a model is resolved, naming the model it took the facts from; update Fontaine for its exact facts. An id with no version number, or whose pattern the catalog has no usable model for, gets no facts and stays an unlisted model (a claude-subscription account refuses it). This applies to every account kind whose models are a catalog vendor’s: anthropic, openai, gemini, ollama, opencode-go, openrouter and claude-subscription. A databricks account does the same for Claude, GPT and Gemini models, taking the facts from the same model’s catalog entry (a dashed version such as gpt-5-1 matches the dotted gpt-5.1) or else deriving them as above. A glm- model gets minimal facts with a known 25,000-token output cap and tools on, and any other model gets none. A host that serves Claude under a name of its own (an Azure Foundry deployment, a custom Databricks endpoint, a proxy behind an anthropic account) names it under model_facts, and the served name then takes the facts of that catalog model (a catalog Claude model on anthropic; a catalog Claude, GPT or Gemini model on databricks). What the mapping does to the price follows the kind: on anthropic it stays unpriced, and on databricks it takes the target’s list price like any other model the catalog lists there. A model with no facts at all (an unmapped name on anthropic, a custom catalog.schema.name endpoint on databricks) is warned about once and never compacts automatically.

An openai-compatible account is an arbitrary gateway with no catalog vendor, so its unlisted models never get derived facts. A derived model keeps no price, so a cost cap treats it as any other unpriced model.

A claude-subscription account is always listed, even with a models list, because the models’ facts come from the CLI’s own answer: the list only narrows what the CLI offers. The listing checks the CLI, so a missing or outdated CLI, a login that is not a Max or Ultra subscription and a conflicting environment variable are run failures (exit code 1) with a corrective message, and a model the CLI marks as drawing from paid usage credits is a configuration error (exit code 2). A model this build of Fontaine does not list gets facts derived as described above (see Claude subscription); one with no listed model of its name pattern is refused. Every listing is bounded in time, including the one at startup.

The model of [guardian] model is checked the same way when its account has a models list, or shares the main model’s account. Otherwise Fontaine makes no call with the guardian’s credentials at startup. An unknown account in [guardian] model is always a configuration error.

With no [guardian] model, the guardian is the highest-ranked benchmark-validated model that one of your accounts offers (see The guardian). An account offers a model when its models list contains it, when it is the main model’s account and the listing already fetched contains it, or, for any other account without a list, when its kind matches and a credential is present; no listing call is made with a guardian credential. When no account qualifies, the main model is the guardian and the start shows a warning (“Guardian is running on your main model <account>/<model>”, with the advice to set [guardian] model or run /guardian-model): in the conversation in the terminal UI, on stderr in a headless run.

fontaine models [<account>] prints the models each account offers (just that account when named), marking the main model, the guardian model and the benchmark-validated guardian models. It lists the way the /model picker does: an account with a models list costs no call, the others are asked once with a 10 second limit, and an account that fails keeps its entry with the error. --format=json prints the same report as JSON ({"accounts": [{"account", "kind", "models": [{"id", "roles", "validated_guardian"}]}]}, or {"account", "kind", "error"} for a failed one; an account with refused rows adds "unavailable": [{"id", "reason"}]). A row an account lists but refuses, such as a claude-subscription model with no listed model of its name pattern, is printed under that account’s models as <id> (unavailable: <reason>). fontaine --model <account>/<model> models marks that model as the main one. The exit code is 2 for an unknown account or when no account is configured, and 1 when every requested account failed to list. The agent can read the same report through the models tool (see Tools); neither shows endpoints, keys or environment values.

Worked examples

Anthropic, with the key in an environment variable:

[accounts.work]
kind = "anthropic"
api_key_env = "ANTHROPIC_API_KEY"

[model]
model = "work/claude-sonnet-5"

A Databricks workspace, serving Claude, GPT, Gemini and open models behind its Unity Gateway with one token (base_url is the workspace origin, with no path):

[accounts.dbx]
kind = "databricks"
base_url = "https://example.cloud.databricks.com"
api_key_env = "DATABRICKS_TOKEN"

[model]
model = "dbx/system.ai.claude-sonnet-5-5"

The guardian’s and the scanner’s calls to models on the Chat wire carry {"reasoning_effort": "none"} unless the account sets thinking_off = false.

Each request goes to the route its model is served on, chosen by model id: claude- models use the Anthropic Messages route (/ai-gateway/anthropic, with prompt caching), gpt- models the OpenAI Responses route (/ai-gateway/openai/v1), gemini- models the native Gemini route (/ai-gateway/gemini), and everything else the provider-neutral MLflow Chat Completions route (/ai-gateway/mlflow/v1). That covers open models such as GLM, Kimi, DeepSeek and gpt-oss-*, and custom catalog.schema.name model services, whose name says nothing about the wire. A leading system.ai. (or the older databricks-) is ignored when choosing. A model the table gets wrong is routed with wires, as on opencode-go. A custom endpoint that serves Claude is mapped under model_facts to take that model’s limits, and also set under wires as messages to be served on the Messages route, because the mapping does not change routing. Every route carries the token as Authorization: Bearer. Without a models list the account lists the chat-capable system.ai.* model services from the workspace’s Unity Catalog; custom services are not listed, so a models list that names one replaces the listing (and must then also name the system.ai.* models you want).

The workspace bills in DBUs, and Fontaine cannot read a per-call DBU figure, so a Claude, GPT or Gemini model whose vendor lists a catalog price is priced at that model’s list price. Every figure it feeds — the usage ledger, total_cost_usd, /cost, the dollar budgets and --max-budget-usd — describes what the same tokens would have cost on the vendor’s own API, and every figure a person reads carries est. so it is never mistaken for the bill. A capped run binds on it like any other price. Open models, gpt-oss-* and an unmapped custom endpoint stay unpriced, and --max-budget-usd with one as the Databricks main model is a usage error (exit code 2). A custom endpoint mapped under model_facts takes its target’s list price, which prices it in the ledger and /cost; it has no OpenTelemetry cost metric, because its spans carry only the endpoint name. On anthropic, the same mapping stays unpriced. auth = "bearer" on an anthropic account still serves other gateways that take only a Bearer token.

A second Anthropic account with its own key, stored with /login personal:

[accounts.work]
kind = "anthropic"
api_key_env = "ANTHROPIC_API_KEY_WORK"

[accounts.personal]
kind = "anthropic"

[model]
model = "work/claude-sonnet-5"

[guardian]
model = "personal/claude-haiku-4-5"

OpenAI:

[accounts.openai]
kind = "openai"
api_key_env = "OPENAI_API_KEY"
models = ["gpt-5.2", "gpt-4o-mini"]

[model]
model = "openai/gpt-5.2"

Gemini:

[accounts.google]
kind = "gemini"
api_key_env = "GEMINI_API_KEY"

[model]
model = "google/gemini-2.5-pro"

A local Ollama daemon, which needs no key:

[accounts.local]
kind = "ollama"
base_url = "http://localhost:11434"
context_tokens = 16384

[model]
model = "local/qwen3:4b"

Every request to an ollama account names its context window, because the daemon otherwise loads a model with its own default (4096 tokens unless the Modelfile or OLLAMA_CONTEXT_LENGTH says otherwise), which cannot hold the guardian’s rules. context_tokens replaces that setting, so a user who raised it to 32768 in Ollama gets 16384 here until they set context_tokens. A larger window costs GPU memory, since the KV cache grows linearly with it, and can push a model onto the CPU on a small card. A prompt longer than the window is refused, not truncated: Fontaine asks the daemon not to cut it, so the guardian denies the call with the daemon’s message (“exceeds the available context size … try increasing it”) and the main agent shows that error. Raise context_tokens to fit the prompt. For a model in rig’s catalog, compaction uses this window, starting when the conversation fills three quarters of a window under about 57k tokens; a model the catalog does not list (a derived or mapped model counts as listed) never compacts by threshold, so a long session ends with that error at the window.

OpenRouter, with prompt caching (an openai-compatible account pointed at OpenRouter still works, but sends no cache markers):

[accounts.router]
kind = "openrouter"
api_key_env = "OPENROUTER_API_KEY"
models = ["anthropic/claude-sonnet-4-6"]

[model]
model = "router/anthropic/claude-sonnet-4-6"

LM Studio:

[accounts.lmstudio]
kind = "openai-compatible"
base_url = "http://localhost:1234/v1"

[model]
model = "lmstudio/qwen2.5-coder-7b-instruct"

vLLM, with an API key if the server was started with one:

[accounts.vllm]
kind = "openai-compatible"
base_url = "http://localhost:8000/v1"
api_key_env = "VLLM_API_KEY"

[model]
model = "vllm/Qwen/Qwen2.5-Coder-32B-Instruct"

LiteLLM proxy:

[accounts.litellm]
kind = "openai-compatible"
base_url = "http://localhost:4000"
api_key_env = "LITELLM_API_KEY"

[model]
model = "litellm/gpt-4o-mini"

OpenCode Go, one subscription serving about thirty models on four wire formats:

[accounts.go]
kind = "opencode-go"

Sign in once with /login go, which shows a URL and a code to approve in a browser, then pick a model with --model go/kimi-k3. Each request goes to the wire its model is served on, chosen from a built-in table by model id: gpt-, grok- and muse-spark- models use the Responses API, claude-, qwen and minimax-m3 use the Messages API, gemini- models use generateContent and everything else uses Chat Completions. Every request carries a fontaine/<version> User-Agent and the session id in x-opencode-session. The access token is refreshed silently.

A model the table gets wrong is routed with wires:

[accounts.go]
kind = "opencode-go"

[accounts.go.wires]
"some-new-model" = "messages"

Go usage is billed against the subscription’s allowances, so its models are unpriced: the cost Go reports, including Extra usage, is not shown or counted, and --max-budget-usd with a Go main model is a usage error (exit code 2).

Claude Code CLI as a subscription transport (see Claude subscription for scope, checks and limits):

[accounts.claude]
kind = "claude-subscription"

Sign in with claude auth login --claudeai (the terminal UI offers to run it when the CLI is not signed in; a headless run exits 1 and names the command), then pick a model with --model claude/sonnet. Usage is subscription usage: tokens are shown, a cost never is, and --max-budget-usd with such a main model is a usage error (exit code 2).

[network]

Proxy, extra CA roots and a client certificate for the HTTP clients Fontaine builds: model accounts, the guardian and its screen, webfetch, the scanner-model download, the opencode-go sign-in, websearch and HTTP MCP servers. User file and --settings only. Stdio MCP servers, shell commands and telemetry exporters are not covered.

KeyMeaningDefault
https_proxyThe proxy for https requests, such as http://proxy.corp:8080. It may carry credentials (http://user:pass@host:port).unset
http_proxyThe proxy for plain http requests.unset
no_proxyHosts that bypass the proxies, in NO_PROXY syntax (localhost,.corp.internal). Needs https_proxy or http_proxy.unset
ca_bundleA PEM file of one or more CA certificates, trusted in addition to the system roots.unset
client_certA PEM certificate chain presented to servers that ask for a client certificate (mTLS). Needs client_key.unset
client_keyThe matching unencrypted PEM private key. A passphrase-protected key is an error. Needs client_cert.unset

With no proxy key set, Fontaine honors the HTTPS_PROXY, HTTP_PROXY, ALL_PROXY and NO_PROXY environment variables (and the system proxy settings on macOS and Windows), as before. Setting https_proxy or http_proxy turns all of that off for the clients concerned. With only https_proxy, plain http requests go direct; with only http_proxy, https requests go direct. An ollama account on localhost therefore goes direct under https_proxy alone, but through the proxy under http_proxy unless no_proxy lists it. SSL_CERT_FILE and SSL_CERT_DIR replace the system roots; ca_bundle adds to them.

Relative ca_bundle, client_cert and client_key paths resolve against the project directory (the launch directory, or --cd), and ~ is not expanded.

Configuration checking is in two tiers. Reading a settings file checks only that the keys are known, allowed in that scope and not empty, and never opens the files, so the example paths below pass documentation checks. The files are read when the configuration is loaded at startup, where any problem (a missing or non-PEM file, a certificate without a key, a no_proxy with no proxy, an unparseable proxy URL) is a configuration error that names the key and exits with code 2. Nothing falls back to a direct or default-trust connection.

Each account may repeat any of these keys to override the [network] value for itself. Overrides apply per key, so an account that sets only ca_bundle keeps the proxy from [network].

[network]
https_proxy = "http://proxy.corp.example:8080"
no_proxy    = "localhost,.corp.example"
ca_bundle   = "/etc/corp/ca.pem"

[accounts.work]
kind        = "anthropic"
api_key_env = "ANTHROPIC_API_KEY"
client_cert = "/etc/corp/client.pem"
client_key  = "/etc/corp/client.key"

[websearch]

Where the websearch tool sends its queries, and whether the provider’s own search is used. User file and --settings only, since it decides where queries go, which key is used and which command runs. See Web search for how the two ways of searching are chosen.

KeyMeaningDefault
backendtavily, searxng or off. Unset: a SearXNG container Fontaine starts itself when docker or podman is installed (see Default search). off disables the client-side websearch tool.unset
base_urlThe SearXNG instance, an http or https URL. Required for searxng; refused for tavily.unset
commandsearxng only: the argv (no shell) that starts the instance serving base_url, such as ["docker", "run", "--rm", "-p", "127.0.0.1:8080:8080", "searxng/searxng"]. Started by the first search with a minimal environment and stopped with the session (SIGTERM to its process group, then SIGKILL after 10 seconds from a background task, so a session that ends sooner can leave a process that ignores SIGTERM running).unset: Fontaine does not start it
startup_timeout_secsHow long to wait for base_url to answer after starting command. Needs command.60
nativeauto uses the provider’s own search where supported (anthropic accounts on the Anthropic API, and claude-subscription accounts); on also uses it for other hosts of a supported kind; off never does.auto
api_key_envtavily only: the environment variable holding the key. Omit it to use the stored credential.unset
max_resultsResults returned, 1 to 20.10
timeout_secsRequest timeout.30

Queries are sent to the provider, or to the configured backend, in the clear. A tavily backend needs a key, and a missing key is a configuration error (exit code 2) at startup, not at the first search. The key is api_key_env when that is set; if the named variable is unset or empty the key counts as missing. When it is omitted, the key is the [websearch] entry in credentials.toml. Keys are never written inline in settings. With backend unset, the managed container gets the minimal child environment plus DOCKER_HOST, DOCKER_CONFIG, XDG_RUNTIME_DIR and CONTAINER_HOST when they are set (the runtime needs them to reach its daemon), a 300 second start timeout for the first image pull, and a command that is fixed by Fontaine: it starts a single shared container named fontaine-searxng, reused by every session and left running until it stops answering (then the next search replaces it), until <runtime> stop fontaine-searxng removes it, or until the machine reboots; a startup sweep removes any leftover fontaine-searxng-<random> container from an older Fontaine. command is an executable like an MCP server or a hook command, but it can only start the instance; it never loosens a permission decision.

[websearch]
backend = "tavily"
api_key_env = "TAVILY_API_KEY"
max_results = 8

[model]

KeyMeaningDefault
modelThe session model as <account>/<model>, a role name, or an ordered list of them. It is shorthand for the main role, so setting it and [models.roles] main in one file is an error. --model overrides it. There is no default model: a run with neither is a configuration error (exit code 2) that names both.unset
effortThe main agent’s reasoning effort: off, low, medium, high or max. --effort overrides it and /effort changes it for a session. Fontaine passes it through rig’s portable setting, which maps it onto the provider’s own parameter. The levels a model takes come from rig’s catalog; a derived model’s come from the listed model it was derived from, and on claude-subscription from the flags the Claude CLI reports for it. Unset sends no reasoning parameter, so the model thinks at its own default. A level the model or its endpoint cannot take (a non-reasoning model, a level the catalog does not list for it, or a generic openai-compatible gateway, which has no known mapping) is left out of the request with a one-time warning, and the run goes on. Subagents use it too, unless their type sets its own. The guardian is not affected: it always runs with thinking off. Not settable from the shared project file.unset
max_output_tokensThe most output tokens one model call of the main agent or a subagent may produce. By default every call sends the model’s own output limit, else 32000 (nothing is sent on ollama or claude-subscription when the limit is unknown, so the daemon’s own default applies; an anthropic turn then fails unless this is set or the model is mapped under model_facts). A value lowers the cap but never raises it past the model’s known limit, and is clamped per model, so subagents on other models stay within theirs. It does not apply to the guardian or /btw, which keep their own caps. A small-context local server (vLLM, for example) rejects a request whose prompt plus cap exceeds its context; set this lower for it. Not settable from the shared project file. Must be at least 1.unset

[models.roles]

A role is a name for an ordered list of models. Each entry is an <account>/<model> or the name of another role, and a bare name (no /) stands for its role’s list everywhere a model is accepted: --model, [model] model, [agents.types.<name>] model, an agent file’s model, the agent tool’s model argument and /model. The list is a preference order.

[models.roles]
main       = ["anthropic/claude-opus-5-5"]
setup      = ["anthropic/claude-haiku-5-5"]
sonnet     = ["anthropic/claude-sonnet-5-5", "anthropic/claude-sonnet-4-6"]
coding     = ["sonnet", "kimi/kimi-for-coding"]
thinking   = ["anthropic/claude-opus-5-5", "openai/gpt-5.5"]

Fontaine reads six role names itself. Every other name is yours, so Claude Code’s sonnet and opus aliases port unchanged once you define them.

RoleUsed forWhen it is not defined
mainThe session’s model. It is the same list as [model] model.main is the same setting as [model] model, so set one or the other; --model overrides it. With neither, the run exits with code 2
critiqueThe fontaine auto-mode critique review.The guardian’s model
setupThe model scan of /auto-mode-setup and fontaine auto-mode setup.The guardian’s model
compactionThe summary request of a compaction. The threshold still follows the main model’s window.The main model, at its current entry
advisorThe advisor tool: the model the main model consults.The tool does not exist
fallbackWhere a subagent goes when its own list is spent on a usage window, before the run pauses.The run pauses until the window resets

Roles never apply to the guardian: [guardian] model and the [guardian.composition] models stay one <account>/<model>, and a pinned guardian is never substituted.

Rules, all checked when the configuration loads (exit code 2):

  • A role name uses letters, digits, _ and -. inherit is reserved, and a name never starts with $.
  • A list is not empty. Each entry is an <account>/<model> of a configured account or a defined role. $main is a synonym for main, and naming it needs [model] model or [models.roles] main in your settings: --model does not define it, so a list naming main without one fails to load.
  • A role never reaches itself through other roles; the error names the cycle.
  • Every role is checked, whether or not anything uses it.
  • The section is read from your user file and --settings only, like [accounts], because an entry names an endpoint. A later scope replaces a whole role.
  • [model] model and [models.roles] main are one setting. In one file they are an error naming both keys; across scopes the one from the higher-precedence scope wins, so a trusted project-local [model] model still overrides a main in your user file.
  • main or $main inside another role splices the configured main list. --model does not re-point it.

An entry that names a role is replaced by that role’s list in place, and a model listed twice keeps its first position. A repository’s agent file or a plugin’s may name a role or $main, not an endpoint; see Extensions.

Falling through to the next entry

When the serving entry fails with a quota-class error that persists past the retries on the same model, the caller moves to the next entry of its list and stays there. The errors are an HTTP 402, 429 or 529, a rate-limit, quota or overload code a provider sends without a status, and a claude-subscription plan limit. A 400, a 500 or a refused request never moves on, and neither do Fontaine’s own token and cost budgets, which are your limit and not the account’s.

  • The main conversation moves its agent to the next entry and continues the turn there. A warning names both models and the switch is recorded in the session log and the audit log. The entry that worked becomes the one later turns start on.
  • A subagent on a role or a list moves for itself, and the role’s other subagents start on the entry that worked. A subagent on $main moves its own agent without changing the main conversation’s entry.
  • Compaction, the advisor, the critique and the setup scan walk their own role’s list the same way.
  • Each request tries every entry once. When the whole list is spent on a quota error the turn fails with every model in <role> failed added. When it is spent on a usage window that has run out (a provider’s window code, a Retry-After of more than five minutes, or a claude-subscription plan limit), the whole run is paused until the window resets instead (a subagent first tries the fallback role), and the request then goes through the list again from the entry the list is on; see Usage windows.
  • With an explicit --max-budget-usd, an entry with no known price is skipped, because a capped run has to stay measurable.
  • A resumed session starts every list at its first entry again.
Subagent fallback

Define a fallback role to keep subagents working when their own list is spent on a usage window. Before the run pauses, such a subagent moves to the first entry of fallback that can serve, says so (agent-1: kimi/kimi-for-coding usage window spent; continuing on claudemax/sonnet), and continues; the move is recorded in the session log and the audit log with role fallback. The run pauses only when every entry of fallback is spent too. With no fallback role, a spent usage window pauses the run as before: a different model is a cost and capability change, so the role is opt-in, and the entries you list are the only ones ever used.

  • Entries on an account whose window is already spent, entries that do not resolve (with a warning) and, under an explicit --max-budget-usd, entries with no known price are skipped.
  • The move is the subagent’s own: the role’s other subagents keep their entry, and a later subagent on the spent role tries it first. The subagent’s mode, permissions and guardian do not change.
  • The subagent stays on fallback: a later quota failure walks that list, never back onto a spent entry, and after a pause it retries its current entry. A subagent already on fallback does not fall back again.
  • The main conversation does not use it; its main list holds its own fallbacks. A user role that was already named fallback now serves this purpose too.

Falling through reacts to what happens at run time. A typo, a missing credential or an account that no longer exists is still an error at startup and never silently skipped. The /cost report breaks the session’s spend down by role and model.

[guardian]

Keys of the guardian that judges tool calls in auto mode. The guardian explains what they do.

KeyMeaningDefault
modelThe guardian model as <account>/<model>; it may use a different account than [model]. A model named here is pinned: it is never substituted when it is unavailable.unset: the top-ranked validated model your accounts offer, else the main model
profilefull or minimal. minimal narrows the guardian for containers and only loads when --in-container is given and a runtime probe finds a container; otherwise full runs, with a notice. It never turns the guardian off.full
timeout_secsTime allowed for one verdict, retries included; at least 1. An attempt that stalls is dropped and retried within it, and on expiry the call is denied. The first attempt may use all but 10 seconds of it (for timeouts of 15 seconds or more; each retry gets at least 5 seconds when that much remains), so a slow model needs more than its worst answer time plus 10.30
confidence_thresholdBetween 0 and 1. An allow below it on a destructive call is turned into a deny.0.7
cacheWhether verdicts are cached for 60 seconds.true
scannerTool-result scanner: off, pg2, llm or command; it is the only switch. User file only. Scanning tool results explains each. pg2 needs a build with the pg2 feature, which release binaries have; elsewhere it is a configuration error.off
scanner_commandProgram used by the command scanner: required with scanner = "command". User file only.unset
scanner_model_pathDirectory holding model.safetensors, tokenizer.json and config.json for the pg2 scanner. With it set, nothing is downloaded. User file only.unset: downloaded into <data dir>/models/promptguard2-86m/
scanner_hf_token_envName of the environment variable holding the Hugging Face token the pg2 download uses. The variable is always removed from shell and hook environments, whatever scanner is. User file only.HF_TOKEN

The llm scanner uses the guardian’s model, so it follows model. timeout_secs bounds each scan of every scanner type (the llm scanner retries a stalled attempt within it), and the pg2 model load at startup.

[guardian.composition]

How the guardian is composed from the LLM guardian and cheap local reads in auto mode: a built-in preset or a Rune script. With the screen preset it is an allow screen in front of the guardian: a small model, local (Ollama, yes/no questions) or hosted (Jev on OpenRouter), allows a call that is clearly safe without waiting for the guardian, and escalates a call that is confidently outside what you asked for (only if you set stop_threshold; no model has a default). Every other call meets the guardian. A composition script is Rune source, hosted like the [statusline] script. Composing the guardian explains it, how to calibrate it and how to write a script. The section is read from the user file only: other scopes may set shadow = true, which holds over the user file’s shadow = false, and nothing else, so a repository cannot load a script. An invalid composition stops startup with exit code 2, naming the key.

KeyMeaningDefault
presetA built-in preset: screen. Exactly one of preset and script is required.unset
scriptA Rune file. A relative path resolves against the user config directory. It must compile against the host functions and define guardian with two parameters.unset
model<account>/<model> of an [accounts.*] entry of kind ollama or openrouter. For ollama, its base_url is the daemon that is asked, without credentials, so the endpoint must not require authentication. For openrouter (typesafe/jev-1.14), the model is read through <base_url>/systemone, where base_url is the same one that serves chat (default https://openrouter.ai/api/v1), with the account’s key (api_key_env or the one /login stored); the key is sent only over https or to a loopback host. A key that does not resolve stops startup with exit code 2, naming this key and the account. The default model of every read, and required with a preset: a hand-written section never starts sending guardian state to a hosted model by itself. The account’s context_tokens is the window a read requests; Ollama reloads a model whenever the requested window changes, so a read and a guardian on the same model need the same value (the same account does).unset
shadowRun the composition and record every read, but let the guardian decide.true
timeout_msTime allowed for each read; at least 1. On expiry the read fails.2000

[guardian.composition.params] holds the preset’s parameters, or free-form numbers, strings and booleans passed to a script as params. The screen preset takes:

ParamMeaningDefault
questionLocal model only (refused for a hosted one, which asks a single five-level question). The stop read’s question: employee_allowed (“If an employee were given the user’s request, would they be allowed to take this action?”) or outside_request (“Is this action outside what the user’s request asked for?”). A threshold is calibrated for one question.employee_allowed
stop_thresholdThe risk, greater than 0 and at most 1, at which a call is escalated.unset: the screen never escalates, and every call it does not allow goes to the guardian
allow_thresholdAllow a call without the guardian when the allow read’s risk is below this (and, on a local model, the steering score is below steering_veto). Greater than 0 and less than 1. On a local model or a hosted model that is not typesafe/, with shadow = false, at least one of stop_threshold and allow_threshold is required.local model: unset, no allow path; hosted typesafe/ model: 0.20; another hosted model: unset
allowHosted model only: false switches the allow path off, and allow_threshold is then ignored. Refused on a local model.true
steering_vetoLocal model only: the steering score, greater than 0 and at most 1, at or above which the screen never allows a call. A hosted model has no steering read, and this is refused for it.0.001
concurrentRace the screen against the guardian instead of asking the guardian only for what the screen does not settle. A settled call then spends the guardian’s input tokens.false

[guardian.composition.reads.<name>] declares a script’s reads; a preset declares its own and takes none. Each read has model (default: the composition’s model), prompt (plain or hardened) and question (employee_allowed, outside_request or steering). The hardened prompt is valid only with employee_allowed, the one wording its threshold was fitted to.

[accounts.local]
kind = "ollama"

[guardian.composition]
preset = "screen"
model = "local/qwen3:4b-instruct-2507-q4_K_M"
shadow = false

[guardian.composition.params]
allow_threshold = 0.00000156
# stop_threshold = 0.0000599
# concurrent = true

The hosted Jev screen needs no threshold; its defaults apply (another hosted model needs its own). Where it is enabled, guardian state leaves the machine for OpenRouter and Typesafe (see the screen preset on a hosted model):

[accounts.openrouter]
kind = "openrouter"
api_key_env = "OPENROUTER_API_KEY"

[guardian.composition]
preset = "screen"
model = "openrouter/typesafe/jev-1.14"
shadow = false

# [guardian.composition.params]
# allow = false            # switch the allow path off; with no stop_threshold every call goes to the guardian

With no shadow key a hand-written section stays in shadow mode; fontaine auto-mode setup is what writes shadow = false.

The model’s answers are nearly certain, so its risk scores are tiny or near 1, and a working threshold is a small number. 0.0000599 and 0.00000156 are the ones measured in Cascade scorecards. Calibrate your own from the scores that shadow mode records on your traffic; allow_threshold in particular is fitted to one model, one prompt and one question, and a wrong value lets the screen allow calls the guardian would not have.

Bring your own scanner

scanner = "command" runs the program at scanner_command once per tool result, with no arguments and no shell, and the same scrubbed environment as hooks, without [env]. It receives one JSON object on standard input and answers with one on standard output:

{"tool": "webfetch", "content": "the text of the tool result"}
{"verdict": "flagged", "reason": "asks the agent to send ~/.ssh to a host"}

verdict is clean or flagged; reason is optional text shown to the agent. A non-zero exit, no answer within timeout_secs, a program that cannot be started, or output that is not exactly this shape counts as a failed scan: the result is marked unscanned and suspect.

[guardian]
model = "work/claude-haiku-5-5"
profile = "full"
timeout_secs = 30
confidence_threshold = 0.7
cache = true
scanner = "off"
[guardian]
scanner = "command"
scanner_command = "/usr/local/bin/injection-scan"

/model and /guardian-model in the terminal UI write [model] model and [guardian] model to the user file for you. When a higher scope also sets the key, the choice is still saved to the user file, and the notice names the scope that wins from the next launch.

[statusline]

A Rune script that renders the terminal UI status bar’s line, and a user-defined command whose output the bar shows. Both run code, so the section is accepted from the user file only: project, project-local and --settings files are refused.

KeyMeaningDefault
commandThe shell command; when absent or empty the feature is off.unset
scriptInline Rune source that defines pub fn statusline(ctx) and returns the bar’s line; the embedded default script renders it when unset.unset
refresh_interval_secsRe-run the command while idle, at least 1; requires command.unset

The command receives one JSON object on stdin and its first stdout line (ANSI escapes stripped) is shown in the bar. Its process tree is stopped after 5 seconds (on Windows, a descendant started before the command joins its Job Object can escape), and any non-zero exit, timeout or empty output keeps the previous good line. See Custom status line for the full JSON contract.

script is source text, not a path (use a TOML multi-line string), and is read from the user file only. Fontaine compiles it at startup and checks that it defines statusline with one parameter; a script that does not compile stops startup with exit code 2 naming statusline.script, the way a [guardian.composition] script does. It is not run at startup, so a runtime error shows while the bar draws, as one warning and the default bar. An empty script is refused, and /config and fontaine doctor show the key as set, never the source. With a script set, refresh_interval_secs still only re-runs the command. The host API is in The status line script.

[statusline]
command = "jq -r '.mode'"
refresh_interval_secs = 10

[permissions]

Rule strings use the Tool or Tool(specifier) form described in Permissions. At load, Fontaine checks the outer shape, that the tool is one of shell, read, edit, write, notebook_edit, ls, glob, grep, webfetch, websearch, agent, skill, monitor, lsp, powershell, job_output, job_cancel, send_message, ask_user_question, todo_write, models, tool_search, advisor, cron_create, cron_jobs, cron_delete, schedule_wakeup, list_mcp_resources, read_mcp_resource or an mcp__<server>[__<tool>|__*] name, and that the specifier is valid for the tool (a shell specifier is literal command words, a path specifier a gitignore-style pattern, a webfetch specifier domain:<host> or domain:*.<host>). A bad rule is a configuration error. deny and ask rules apply in every mode; allow rules act after the floor.

KeyMeaningDefault
default_modemanual, acceptEdits, dontAsk, auto or afk. Applies to both surfaces.unset: the terminal UI starts in auto, a headless run in manual
denyRules that always deny.[]
askRules that always prompt.[]
allowPre-approval rules. User-trust scopes only.[]
additional_directoriesExtra workspace roots. User-trust scopes only. See Workspace roots.[]
auto_tracked_editsIn auto, edits to any file inside the primary root, tracked by git or not, skip the guardian (after the floor). Project scope may only set false.true
auto_scratch_writesIn auto, file-tool writes into the session scratch directory skip the guardian (after the floor). Project scope may only set false.true
auto_shell_editsIn auto, a shell call that Fontaine parses in full and that is made only of read-only commands and in-root edits, deletions of files or local git steps (sed -i, mkdir, mv, rm, git add, git commit, git rebase --continue and the like) skips the guardian (after the floor). Project scope may only set false. See the pipeline.true

default_mode = "auto" and "afk" load only from the user file and --settings. It is rejected from the shared project file and from settings.local.toml, trusted or not, because it loosens: those scopes accept only manual and dontAsk.

[permissions]
default_mode = "manual"
deny = ["shell(rm *)", "read(.env)"]
ask = ["webfetch(domain:*.example.com)"]
allow = ["shell(cargo test)"]
additional_directories = ["/home/me/shared-libs"]

Workspace roots

The workspace is an ordered set of roots: the primary root, then every --add-dir <path> and every additional_directories entry. File tools write a path that lies inside any root, and shell working directories stay inside them; every file tool — the four read-only ones (read, ls, glob, grep) and the write tools (write, edit, notebook_edit) — may also name a path outside the roots, each call adjudicated through the normal permission decision: it asks in the asking modes, is judged by the guardian in auto (an un-asked external write is denied; see Guardian) and is denied in dontAsk and headless runs unless an allow rule or hook already covers it (see Permissions). A relative entry is resolved against the project directory (the launch directory, or --cd); a leading ~ expands to the home directory (see Workspace roots). An entry that does not exist, is not a directory or cannot be resolved is left out, with a warning naming the path and whether it came from --add-dir or the settings, and the run continues. The terminal UI shows the warning in the conversation; a headless run prints it on stderr.

Each session also gets a private scratch directory as a root of its own, with no setting to add or move it (in auto, file-tool writes into it skip the guardian; see auto_scratch_writes above): $XDG_RUNTIME_DIR/fontaine/<session id>/ where that is available, else a per-user directory under the temp dir ($TMPDIR or /tmp; %TMP%/%TEMP% on Windows). It is removed when the session ends and swept after a crash. For shell it is treated like any root: read-only commands whose operands are inside it take the pre-classifier fast path, and other commands go through the guardian as usual. See the scratch directory. Tests and sandboxes redirect it by setting XDG_RUNTIME_DIR (TMP on Windows).

Roots grant file access, not configuration: settings, hooks, MCP servers and extension files load from the primary root only. A .fontaine/settings.toml in an added root is not read. See Tools.

[[hooks.<event>]]

User hooks: handlers that look at a tool call, a prompt or a moment in a session. The events are pre_tool_use, post_tool_use, post_tool_use_failure, permission_denied, task_created, task_completed, teammate_idle, session_start, session_end, user_prompt_submit, stop, stop_failure, subagent_start, subagent_stop, pre_compact, post_compact, notification, elicitation and activity_changed; any other key under [hooks] is a config error. A repository’s settings may define activity_changed hooks (a command after workspace trust), since it forces no model calls. What a matcher selects on depends on the event, and an event with nothing to select on rejects one (see Matchers).

KeyMeaningDefault
typecommand, http or prompt; the event must take it.command
matcherWhat the hook runs for. For the tool events, a rule in the Tool(specifier) form; a hook without one runs for every call and counts as broad.none
commandThe command line, run by the shell. Required for command.none
urlThe endpoint an http hook POSTs the event to. Required for http.none
headersA table of request headers for an http hook; $VAR expands only for names in allowed_env_vars.none
allowed_env_varsThe environment variables headers may read. It may not name a variable the shell tool’s scrub removes.none
promptThe question a prompt hook puts to the guardian’s model; $ARGUMENTS stands for the event. Required for prompt.none
timeout_secsAt least 1.30 (session_end: 1.5 seconds)
[[hooks.pre_tool_use]]
matcher = "shell(git *)"
command = "/home/me/.config/fontaine/hooks/git-guard.sh"
timeout_secs = 10

Hooks the repository defines start only after workspace trust in the terminal UI, and their allow is ignored. A repository’s http and prompt hooks, and its stop, subagent_stop and teammate_idle hooks, are never run. See User hooks.

[mcp.servers.<name>]

MCP servers. Set exactly one of command (a stdio server) or url (streamable HTTP). args, env_vars and env apply to stdio servers only. env_vars lists variable names to pass through; values never appear in configuration, and the rest of Fontaine’s environment is not passed. headers (a string map) and headers_helper (a path to an executable) apply to http servers only: static headers sent on the server’s protocol requests, and an executable run at connect time whose KEY: VALUE stdout lines become headers, overriding static ones of the same name. A headers_helper in the project scope is refused: a repository Fontaine merely opened must not make Fontaine execute a script. See Authentication. Tools register as mcp__<server>__<tool>, always as arbitrary tools. A server a repository defines starts only after workspace trust and your approval of that server in the terminal UI. The same servers can be declared in local scope (mcp-local.toml) or a repository’s .mcp.json, and fontaine mcp add writes any of them; see Scopes.

[mcp.servers.github]
command = "github-mcp-server"
args = ["stdio"]
env_vars = ["GITHUB_TOKEN"]

[mcp.servers.docs]
url = "https://mcp.example.com/docs"
headers = { "X-Team" = "payments" }

[mcp]

tool_search controls tool search, which keeps MCP tool definitions out of requests until the model loads them with the tool_search tool: auto (the default) defers them when their definitions would take more than a tenth of the model’s context window, on always defers them, off never does. Either scope may set it: deferral hides schemas and changes no permission decision. It has no effect with claude-subscription accounts.

native_tool_search (default true) lets an anthropic account load deferred tools through Anthropic’s own tool search, which keeps the prompt cache across a load; false loads them on the client side as every other provider does. It applies only to models that support the feature, and a host that rejects it falls back by itself for the session. Either scope may set it, for the same reason as tool_search.

[mcp]
tool_search = "on"
native_tool_search = true

[lsp.servers.<name>]

A language server for the lsp tool and the diagnostics note on edits. User file or --settings only: a server runs on your machine on every edit, so no repository, project-local file or trust prompt can add one. Names use the MCP server alphabet. An invalid entry is a configuration error that names it.

KeyMeaningDefault
commandThe program to start; required.–
argsIts arguments.[]
extension_to_languageExtension, with its dot, to the language id sent in didOpen; required, at least one entry.–
env_varsParent variable names to pass through.[]
envLiteral variables set on the server.{}
initialization_optionsSent in initialize.unset
settingsSent by workspace/didChangeConfiguration and answered to workspace/configuration.unset
startup_timeout_msHow long the handshake may take.30000
shutdown_timeout_msHow long shutdown and exit may take before the server is killed. Quitting the terminal UI does not honor it: the servers are ended at once, inside the shared two-second exit budget.2000
request_timeout_msHow long one request may take.60000
restart_on_crashRestart a server that crashed after it was running.true
max_restartsRestarts allowed for the session.3
diagnosticsAdd the diagnostics note to edits of the files it handles.true

The server starts with the same environment as an MCP stdio server: a small base set of variables, the ones env_vars names, the [env] table and its own env; its working directory is the primary root, and it gets the workspace roots as workspace folders. /add-dir tells a running server that supports it.

[lsp.servers.rust-analyzer]
command = "rust-analyzer"
extension_to_language = { ".rs" = "rust" }
env_vars = ["RUSTUP_HOME", "CARGO_HOME"]

[auto_mode]

Prose lists for the guardian: environment (what is trusted and sensitive in your setup), allow (exceptions that clear a soft-deny match), soft_deny and hard_deny (see rule precedence). The marker $defaults splices the shipped defaults in where it stands.

  • environment and allow: unset or empty gives the shipped defaults; a list with $defaults has them spliced in at that position; any other list replaces them.
  • soft_deny and hard_deny: the shipped entries are always present, because a shared project file may add to these lists and must not be able to replace the defaults by adding. A list without $defaults has them placed first.

environment and allow loosen, so they come from user-trust scopes only; soft_deny and hard_deny can be added to from any scope. Under the minimal profile only environment is used.

KeyMeaningDefault
setup_reminderWhether an auto session whose project has no stored environment facts warns to run fontaine auto-mode setup. User-trust scopes only: a shared project file cannot set it.true

fontaine auto-mode config prints the lists a session would use and which scopes set them, and the project’s stored environment record, or none — run fontaine auto-mode setup; fontaine auto-mode setup collects that record and can write [guardian.composition] to the user file after a confirmation. See Inspecting the rules.

[auto_mode]
environment = ["$defaults", "Source control: github.com/myorg"]
allow = ["$defaults", "Deploying to the staging namespace is allowed: it resets nightly"]
hard_deny = ["$defaults", "Never send repo contents to third-party code-review APIs"]

[agents]

Subagent limits and agent types.

KeyMeaningDefault
max_parallelSubagents running at once across the whole session, at any depth; at least 1. A spawn past it is refused, not queued.4
subagent_token_budgetOpt-in per-subagent token cap, the guardian’s calls for it included. A subagent that passes it stops and returns a partial report. Unset means uncapped.unset
subagent_cost_budget_usdOpt-in per-subagent spend cap. Inactive, with a one-time notice, on a model with no known price; a token cap, if set, still binds. Unset means uncapped.unset
session_token_budgetA token ceiling that every agent in the tree debits, when set.unset
session_cost_budget_usdThe same in dollars, when set.unset
teamsTurns on the task boards: the board_show and board_update tools, the owner reminders and the task_created, task_completed and teammate_idle hooks. Set to false, the board tools are not registered. It does not control idling: a subagent that ends done or failed goes idle when its turn ends and can be woken, unless it is later killed, runs out of budget or is retired. Like the other [agents] keys it cannot be set from the repository’s shared settings.true

[agents.types.<name>] defines an agent type with model (<account>/<model>, a role name, $main, $guardian_default, or a list of the first three; a list of roles is its own preference order, and $guardian_default stands alone), tools (built-in or mcp__ tool names), effort (off, low, medium, high or max; unset inherits the session’s level, and a subagent may run above or below its parent because effort is not a permission) and mode. mode accepts only inherit (the default: the parent’s mode), manual or dontAsk; any other value is an error, so a subagent is never looser than its parent. A type’s toolset is cut down to what its parent has. Agent files in agents/ define types too; see Extensions.

[agents]
max_parallel = 4

[agents.types.reviewer]
model = "work/claude-sonnet-5"
tools = ["ls", "read", "glob", "grep"]
mode = "inherit"

[context]

KeyMeaningDefault
autocompact_windowA token count. Before a turn, the conversation is summarized once its messages pass it. The model’s own limit still applies, so the effective trigger is the lower of this and the model’s window less a 16,384-token reserve. At least 1.unset

Unset, compaction runs when the model’s window less the reserve is passed, and only for a model whose window the catalog knows. Set, it also runs for a catalog-listed model whose window is not known. A model the catalog does not list (a gateway or local alias; a derived or mapped model counts as listed) is never compacted automatically, with or without the setting; /compact cannot summarize with it either. A small value also shrinks what a compaction keeps: the newest messages it leaves as they are and the summary it asks for are each capped at a quarter of the value, so the conversation ends under it. It applies to headless runs too. See Context for /compact and /context.

[context]
autocompact_window = 150000

[schedule]

KeyMeaningDefault
enabledWhether the scheduling tools and /loop are available in the terminal UI. When false the tools are not registered, /loop says scheduling is off, and a schedule saved by an earlier session is left on disk and never runs. Only the user file and --settings can set it.true
[schedule]
enabled = false

[memory]

KeyMeaningDefault
autoWhether the agent may save notes to the per-project memory store and the store’s index loads into each session. A change applies at the next launch. Only the user file and --settings can set it.true
[memory]
auto = false

[goal]

KeyMeaningDefault
max_turnsGoal turns in one unattended stretch, 1 to 1000. Reaching it pauses the goal; your next message starts a fresh stretch.50
max_cost_usdThe stretch’s spend (the main model, compaction, the guardian, the goal evaluator and subagents) that pauses the goal, zero or more. Inactive for a model with no known price.unset
max_tokensThe stretch’s tokens (the same sources as max_cost_usd) that pause the goal, 1 or more. Counts tokens whether or not the model is priced.unset
max_duration_secsWall-clock seconds of one stretch that pause the goal, 1 to 2592000 (30 days); time spent waiting for a usage window does not count. Checked after a turn is evaluated, so a stretch can overrun it by one turn and one evaluation.unset
checkin_minutesMinutes that a running subagent, background shell or monitor keeps the goal waiting before the model is asked to check on it, 0 to 1440. Later check-ins come after twice that, then every four times that. 0 turns check-ins off; the goal still waits for the work.30

A goal turn runs with nobody typing, so only the user file and --settings can set these. The no-progress cap (8 verdicts in a row after turns that made no call other than reads and monitor starts) is fixed.

[goal]
max_turns = 50
max_cost_usd = 5.0
max_tokens = 2000000
max_duration_secs = 7200
checkin_minutes = 30

[retry]

KeyMeaningDefault
max_retriesRetries of a failed model call on top of the first attempt, 0 to 10. 0 turns retrying off.4
base_delay_msThe wait before the first retry, in milliseconds, at least 1. It doubles with each retry and is then multiplied by a random factor between 0.5 and 1.500
max_delay_secsThe longest single wait, in seconds, at least 1 and not below base_delay_ms. A Retry-After longer than this ends the retries at once: the server asked for more than a run will wait.30
max_total_delay_secsThe longest the retries of one turn wait in total, in seconds, at least 1.120

These govern a transient model failure (a cut connection, a 5xx, throttling) on the main agent and on every subagent. A wait is the larger of the backoff and the reply’s Retry-After header, and each retry is announced with one warning line that names the agent, the attempt, the wait and the status, never the reply’s body. A 402, 429 or 529 gets at most 2 retries and at most 10 seconds of waiting in total, so a model list moves on to its next entry quickly; a spent usage window is not retried at all. Only the model request is sent again: a tool call that already ran is never repeated.

Retrying more is spend, so only the user file and --settings can set these.

[retry]
max_retries = 4
base_delay_ms = 500
max_delay_secs = 30
max_total_delay_secs = 120

[feedback]

KeyMeaningDefault
draftsWhether the model may queue bug-report drafts with draft_bug_report: on offers the tool and counts the drafts in the footer, quiet offers it without the footer count, off leaves the tool out.on

Only the user file and --settings can set this. Drafts are never sent: you file a report with /bug, which shows the exact text first.

[feedback]
drafts = "quiet"

[remote]

KeyMeaningDefault
relayWhich network paths the remote control endpoint may use: default uses the public relays run by the iroh project, so a device behind a NAT can still reach the session (a relay sees connection metadata, never content), and also publishes the host’s node id and home relay URL to iroh’s address-lookup service so paired devices can find it again, a metadata exposure beyond relay use (the attaching device only resolves, never publishes); disabled allows direct connections only, publishes nothing, and a device dials the addresses it stored and queries no lookup service.default

Only the user file and --settings can set this, and a project file that does is refused. It never enables remote control: only fontaine --remote, /remote on or /remote-control in a live terminal session does. fontaine attach reads only the user-scope value.

[remote]
relay = "disabled"

[afk]

KeyMeaningDefault
temperature_ceilingThe session temperature at which an AFK stretch is stopped. A finite number above zero.12.0

The user file and --settings set the value, and --afk-temperature-ceiling overrides both for one session. A shared project file or a project-local file may only lower it: the lowest value any of them sets caps whatever the user, the command line or the default gave, whichever file is read first. A value that is zero, negative, infinite or not a number is a configuration error in every scope, so no scope can switch the stop off. Nothing in a session can change it: the model has no tool for it, and edits to settings files are a protected-path and Safety Bypass case.

[afk]
temperature_ceiling = 8.0

[headless]

KeyMeaningDefault
max_usage_wait_secsThe longest a run waits for an account’s spent usage window to reset, in seconds, at least 1. It bounds fontaine -p, and the terminal UI while AFK mode is on, because nobody can cancel a wait then.21600 (6 hours)
on_usage_limitwait holds the run until the window resets; exit ends a headless run at once with exit code 3.wait
require_trusttrue makes a headless run skip a repository’s hooks, MCP servers and skill commands unless the workspace was trusted in the terminal UI, and print one line on stderr. false loads them without asking, as Claude Code’s -p does. User file or --settings only.false

--max-usage-wait and --on-usage-limit=wait|exit override both for one run. A shared project file or a project-local file may set on_usage_limit = "exit", which only ends a run sooner, and nothing else here.

[headless]
max_usage_wait_secs = 7200
on_usage_limit = "wait"
require_trust = false

[shell]

KeyMeaningDefault
max_timeout_secsThe longest timeout_secs a model’s shell call may ask for, 1 to 86400. In the main conversation it is how long a call blocks before the command is moved to a background job; for a subagent or a skill’s shell injection it is how long the command runs before it is stopped.600

A repository must not stretch how long commands run, so only the user file and --settings can set it. No tool argument lifts it. The ! mode keeps its own 120 second default.

[shell]
max_timeout_secs = 1800

[checkpoints]

KeyMeaningDefault
enabledWhether write and edit save a file’s contents before changing it, for /rewind. When false a rewind can restore the conversation but not the code.true
max_file_bytesA file larger than this is not saved; the edit goes ahead and the rewind lists the file as not restorable. At least 1.10485760 (10 MiB)
max_session_bytesOnce the saved copies of a session reach this size, later files are not saved. At least 1.268435456 (256 MiB)

Only the user file can set these; neither a repository nor --settings can.

[checkpoints]
max_file_bytes = 5242880

[plugins]

KeyMeaningDefault
auto_updateWhether registered marketplaces and installed plugins update themselves in the background when the terminal UI starts (see Auto-update). A plugin revision that changes its hooks, servers, skill ! commands or scripts is held for fontaine plugin update either way. Headless runs never auto-update.true

Updating changes code you approved at install, so only the user file can set it; a repository and --settings cannot. One marketplace or plugin can opt out on its own with fontaine plugin marketplace auto-update <name> no or fontaine plugin auto-update <name> no.

[plugins]
auto_update = false

[updates]

KeyMeaningDefault
auto_updateWhether an install made by a Fontaine installer replaces itself in the background when the terminal UI starts (see Automatic updates). Off disables the check and the install; fontaine update still works. Headless runs never auto-update.true

Replacing the executable is not something a repository may switch, so only the user file can set it; a repository and --settings cannot.

[updates]
auto_update = false

[shell_preclassifier]

KeyMeaningDefault
allow_extraExtra read-only commands for the shell pre-classifier. Each entry is a command name or a command subcommand pair with no flags; any flag on the call falls through, and positional words must be in-scope paths. User-trust scopes only.[]

[telemetry]

Telemetry is off by default.

KeyMeaningDefault
enabledTurns export on.false
backendmicromegas or otlp.micromegas
endpointThe ingestion URL. Required when enabled; there is no default.unset
api_key_envThe name of the environment variable holding the ingestion key. Omit it to use the stored credential.unset
tracesExport spans.true
log_user_prompts, log_assistant_responses, log_tool_details, log_tool_contentContent opt-ins.false
content_max_bytesTruncation limit for opted-in content.61440
resource_attributesStatic tags attached to everything exported.{}

Enabling telemetry requires both the ingestion URL and an ingestion key. Setting enabled = true without an endpoint, or without a key, is a configuration error and Fontaine exits with code 2. The key is api_key_env when that is set; if the named variable is unset or empty the key counts as missing. When api_key_env is omitted, the key is the [telemetry] entry in credentials.toml. Keys are never written inline in settings.

Project scopes can only set enabled = false. What is exported, the two backends and the privacy defaults are described in Telemetry.

[telemetry]
enabled = true
backend = "micromegas"
endpoint = "https://telemetry.example.com"
api_key_env = "MICROMEGAS_INGESTION_API_KEY"
resource_attributes = { "team.id" = "platform" }

[env]

Environment variables set on every process a tool or extension starts: the shell tool, ! commands, hooks and stdio MCP servers. Each key is a variable name and each value a string.

[env]
HTTPS_PROXY = "http://proxy.internal:3128"
PATH = "/home/me/.local/bin:/usr/local/bin:/usr/bin:/bin"
RUST_LOG = "warn"
  • Values are literal: $VAR and ~ are not expanded, so PATH = "/opt/bin:$PATH" sets PATH to exactly that text. Write the whole value out.
  • The entries are applied after the scrub of credential variables (see Tools), so an entry may deliberately set a scrubbed name. They are applied before the variables Fontaine sets itself.
  • Names starting with FONTAINE_ (in any case) are reserved and are an error. A name may not be empty or contain =, and neither names nor values may contain a NUL character. Values must be strings; a number or a boolean is an error.
  • Scopes merge per key and the higher scope wins; on Windows names are compared without regard to case, so Path in --settings replaces PATH in the user file. There is no way to unset a variable.
  • Values are never logged and never appear in a configuration error, and the settings debug output hides them. The guardian is told the names that are set, never the values.
  • Fontaine’s own process is not affected: provider, telemetry and scanner-command lookups keep using the variables they name, and neither the scanner = "command" program nor the [websearch] command SearXNG launch gets [env]. The SearXNG child’s environment is deliberately the minimal one; pass it variables inline in the argv (for docker run, -e NAME=value).
  • User-trust scopes only (see Trust asymmetry).

[tui]

Terminal preferences. They are personal, so only your user file and --settings may set them; a project or project-local file that has a [tui] table is an error.

KeyMeaningDefault
themeThe colour theme: dark-ansi, light-ansi, dark, light, dark-daltonized or light-daltonized. /theme writes it. See Terminal setup.dark-ansi
screen_readerTurns on screen-reader mode. --ax-screen-reader turns it on and FONTAINE_AX_SCREEN_READER=0 keeps it off over this setting. See Terminal setup.false
show_reasoningShows the model’s reasoning in the conversation: it streams live, then folds to a few rows once it settles, and /expand thinking prints it in full. false hides it. See Terminal UI.true
notifyHow a prompt that waits for your answer (an approval, a question, an MCP server or skill prompt, the guardian-unavailable prompt) signals the terminal: bell (the default), osc9 or osc777 (a desktop notification, on terminals that support the sequence) or off. Screen-reader mode keeps its own bell. See Notifications.bell
prompt_suggestionsAfter a turn, asks the main model for the message you are likely to type next and shows it dimmed in the empty input; Tab or Right fills it in. It is an extra model call per turn, shown as suggestions in /cost. See Prompt suggestions and history completion.false
history_completionShows the newest earlier input that extends what you are typing as dimmed text after the cursor; Tab or Right accepts it. No model call.true
editor_modeHow the input box edits text: emacs (readline-style, the default) or vim (modal INSERT/NORMAL; see Vim input mode). /vim toggles it live and saves the choice.emacs
[tui]
theme = "dark"
screen_reader = false
show_reasoning = true
editor_mode = "vim"
notify = "osc9"
prompt_suggestions = true
history_completion = true

[keybindings]

Maps keystrokes onto the TUI’s global actions, so the keys above the input do what you want. It is personal configuration: only your user file and --settings may set it, a [keybindings] table in a project file is an error, and an unknown action, an unknown key or a rebind of a reserved key fails to load with exit code 2 naming the entry.

Each entry is "<keystroke>" = "<action>"; the empty string unbinds the keystroke:

[keybindings]
"ctrl+g" = "todos"   # this key now opens the task list…
"ctrl+t" = ""       # …and this one does nothing
"f2"     = "cycle_mode"

A keystroke is modifiers (ctrl, alt — meta is an alias — and shift) then a key name: enter, tab, backtab, esc, up, down, left, right, home, end, pageup, pagedown, backspace, delete, insert, space, plus or a single character, f1–f24 included; names read case-insensitively (Ctrl+Shift+T and ctrl+shift+t are the same key). One keystroke per entry — chords (space-separated sequences) are not supported. Binding a keystroke that already triggers an action replaces that action’s use of the key; several keys may trigger one action. A bare printable key (such as "a") bound to an action can no longer be typed into the input. On Windows, a ctrl+alt+<char> binding hides that AltGr character, as the console reports AltGr as Ctrl+Alt. Changes apply on the next launch; /keybindings prints the effective table and the file to edit.

ctrl+c (interrupt) and ctrl+d (quit) are reserved: they cannot be rebound or unbound, so interrupting and quitting always work. Terminal-aliased keys are worth knowing about: many terminals deliver Tab for Ctrl+I, Enter for Ctrl+M, Backspace for Ctrl+H and Esc for Ctrl+[.

The actions and their default keystrokes:

ActionDefaultWhat it does
cycle_modeshift+tabCycle the permission mode; the cycle stays manual → accept edits → auto → AFK → manual, no matter the key.
interruptctrl+c (reserved)Interrupt a running turn; quit when idle.
quitctrl+d (reserved)Quit when the input is empty; with text it deletes the character under the cursor.
agents_panelnoneOpen or close the agents panel; /agents opens it without a key.
todosctrl+tExpand or collapse the task list.
transcriptctrl+oOpen or close the transcript view.
reprintctrl+lRedraw the screen from the transcript.
attach_clipboardctrl+v, alt+vAttach the clipboard’s image.
history_searchctrl+rSearch the prompt history.
history_previousupRecall the previous input on the input’s first line.
history_nextdownWalk back forward while recalling; both also move the cursor inside a multi-line input.
submitenterSend the message.
newlineshift+enter, alt+enter, ctrl+jInsert a newline.

Only the global actions are remappable: an open overlay (approval, question, picker, panel) keeps its own keys, and so do the vim cursor keys. Ctrl+P and Ctrl+N remain hardcoded aliases of Up and Down.

Skill trust

Which skills have had their allowed-tools honoured is kept in <config dir>/skill-trust.toml, outside every repository and apart from the workspace trust.toml. fontaine plugin trust and the terminal UI’s /skills trust write it; nothing in a project scope can read it into a grant. A record for a project skill is ignored with a warning.

[[skill]]
name = "dev-skills:pr"          # the composed name /skills shows
digest = "sha256:9f2c5a0e"      # of the skill file's bytes, frontmatter and body
tools = ["shell(git *)"]        # the trusted version's allowed-tools
commands = ["!git status"]      # the trusted version's `!` lines

tools and commands are kept so a later change can be shown as a difference. The file is atomically replaced under skill-trust.lock and readable by the current user only. An unreadable or unparseable file trusts nothing and is reported once at start; plugin trust and untrust refuse to overwrite it.

Workspace trust

Some project files can name programs to run, such as hooks and MCP servers, and skills can carry commands. Whether the repository may be treated as the user’s own is decided by a trust record that lives outside the repository: <data dir>/trust.toml. The terminal UI asks about a folder it does not know, before anything the repository defines starts, and writes your answer there (“trust” is recorded; “do not trust” is not, and is asked again next session). You can also edit the file by hand. Each entry is the canonical path of a trusted directory, written as a TOML literal string (single quotes) so Windows paths need no escaping:

[[trusted]]
root = '/home/me/code/myrepo'

The same file records which repository-defined MCP servers you approved, one [[approved_servers]] entry per root, server name and definition digest; a changed definition is asked about again. See MCP servers.

Trust covers what a repository can run: hooks, MCP servers and skill commands. It never lets any of them approve a tool call. A headless run (fontaine -p) loads a repository’s hooks and MCP servers without asking, as Claude Code’s -p does (unless [headless] require_trust = true and the workspace is not trusted), and holds them to the same rule. Prompt content (instruction files such as FONTAINE.md, CLAUDE.md, AGENTS.md and rules under .claude/ or .fontaine/, skills, agent files, output styles) and the keys that only tighten load whatever the answer.

A root is trusted when it, or an ancestor of it, is recorded. Inside a git work tree the search stops at the work-tree root, so trusting your home directory does not trust every repository in it; outside any repository there is no bound. An entry that cannot be resolved is ignored, and an unreadable or unparseable trust.toml trusts nothing, and the session reports it once at start so the file can be fixed or removed. Writes to trust.toml and to the settings file are atomic and take a lock beside the file (trust.lock, config.lock), so a crash cannot truncate them and two sessions cannot drop each other’s edits. Reading either file takes the same lock briefly, so a read never sees an edit half-done. Paths compare case-insensitively on Windows.

Project-local settings

.fontaine/settings.local.toml is meant to be personal and untracked. It gets user trust only when both hold:

  • git does not track it. Untracked and ignored files both count; a file that was force-added is tracked. Fontaine reads the repository itself and never runs git.
  • the workspace root is trusted.

Anything else loads as project scope and is validated against the project column: a tracked file, an untrusted root, no git repository, a .fontaine directory that is a symlink out of the work tree, or any error reading the repository. If an untrusted root’s untracked file sets a key only user trust may set, Fontaine exits with code 2, names the root, and prints the trust.toml entry to add.

Credentials

<data dir>/credentials.toml holds stored credentials. Each account has either an api_key or, after a sign-in, an oauth entry, and the telemetry and web search keys are kept separately, so an account named telemetry or websearch cannot shadow them:

[accounts.work]
api_key = "sk-..."

[accounts.go.oauth]
access = "..."
refresh = "..."
expires_at = 1798000000
server = "https://opencode.ai/console"
org_id = "org_..."
email = "me@example.com"

[telemetry]
api_key = "ingestion-key"

[websearch]
api_key = "tavily-key"

# MCP servers `fontaine mcp login` signed in to. `credentials` and `state` are the
# authorization library's stored credentials and PKCE state as JSON, and `resource` is the URL
# they were issued for: a declaration with a different `url` never receives the token.
[mcp."github"]
credentials = "{\"client_id\":\"...\",\"token_response\":{...}}"
state = "{\"pkce_verifier\":\"...\",\"csrf_token\":\"...\"}"
resource = "https://mcp.example.com/mcp"

/login in the terminal UI is the way to store a credential interactively; see Managing providers. For a key-based account it reads the key into a hidden field and writes it here, and for an opencode-go account it runs a device sign-in: it shows a verification URL and a code, waits while you approve it in a browser, and stores the token pair as an oauth entry. The account can also be added in the dialog, which writes its [accounts.<name>] table to your user settings file in place, keeping the file’s comments and layout. The credentials file is written through the owner-only writer and every other entry in it is kept. A file that cannot be parsed is never overwritten. Logging out and removing an account delete its entry. An MCP server’s entry is written by fontaine mcp login and deleted by fontaine mcp logout; it holds an OAuth token bound to that one server URL, never one of your other credentials.

Fontaine refreshes the access token as it expires and writes the rotated pair back; writers of the file take a lock beside it (credentials.lock), so concurrent sessions and logins do not overwrite each other’s rotation. A sign-in that has ended is reported with the /login command to run again.

There is no command-line way to store a credential. Automation sets api_key_env on the account and exports the variable, or ships a credentials.toml in the data directory (the schema above, owner-only). The telemetry ingestion key is the [telemetry] entry of that file, or the variable [telemetry] api_key_env names; the Tavily key is the [websearch] entry, or the variable [websearch] api_key_env names. An opencode-go sign-in is a poor fit for CI: refresh tokens rotate, so a copied credentials.toml works on one machine at a time and the copy left behind stops working after the first refresh. Use a key-based account there.

A claude-subscription account never has an entry here, and one left behind under its name is never read.

A missing file or entry means no credential. A file that cannot be parsed, or that cannot be read for any reason other than not existing, is a configuration error naming the path.

Command line and environment

Flag or variableEffect
--settings <file>Layers a TOML file over the project and user settings for this session (CLI scope).
--cd <dir>, -C <dir>Starts in this directory instead of the launch directory; see Headless runs. A relative --debug-file resolves against it.
--debug-file <path>Writes debug-level diagnostics to the file, which is created readable by the current user only. The config loaded event, which carries the resolved scope stack, is written here.
--model <account>/<model>Overrides [model] model.
--effort <level>Overrides [model] effort with off, low, medium, high or max. Any other value is a usage error that lists these.
--permission-mode <mode>Overrides [permissions] default_mode. auto and afk are accepted.
--in-containerStates that the process runs inside a container. With [guardian] profile = "minimal" it lets the minimal guardian load, after a runtime probe also finds a container; the flag alone is never enough.
--continue, --resume <id-or-name>, --fork-session, --name <name>Reopen the latest session of the project directory (the launch directory, or --cd), reopen one by id or by name, copy the one that would have been reopened under a new id, or name the session started (or, without --fork-session, the one reopened). See Headless runs.
--allowed-tools <rule>, --disallowed-tools <rule>Adds an allow or deny rule for the session (CLI scope). Repeatable.
--afkStarts the session in AFK mode, which decides as auto does. It is shorthand for --permission-mode afk; combined with another --permission-mode it is a usage error.
--afk-temperature-ceiling <n>Sets [afk] temperature_ceiling for the session (CLI scope).
--on-usage-limit=wait|exit, --max-usage-wait <duration>Set [headless] on_usage_limit and max_usage_wait_secs for the session (CLI scope); see Usage windows.
--ax-screen-readerPrints the interface as plain labelled lines for a screen reader instead of drawing it, and prints [Screen Reader Mode: on via flag] first. A headless run ignores it.
FONTAINE_AX_SCREEN_READER1 turns screen-reader mode on and 0 keeps it off even when [tui] screen_reader is true; the flag still turns it on. Any other value is ignored, with a warning in the conversation (or on stderr when the UI cannot start).
MAX_MCP_OUTPUT_TOKENSThe token limit of one successful MCP tool result; a larger one is saved to a file in the session’s scratch directory. A positive whole number; anything else is warned about once at startup and the default (25000) is used.
FONTAINE_CLAUDE_CAPTUREDevelopment only: 1 or full records every claude-subscription request’s frames and results, delta only the new messages; unset, empty and 0 are off, and any other value is off with a warning. A user-level environment variable only: no config key, and a project file cannot set it. The record is unredacted; see Capturing traffic.
FONTAINE_LOGAn EnvFilter directive that replaces the default debug filter of the debug file. On its own it creates no file and prints nothing.
FONTAINE_CONFIG_DIR, FONTAINE_DATA_DIRDirectory overrides, described above.

The flags of a non-interactive run (-p) are in Headless runs.

An unparseable FONTAINE_LOG or an unopenable --debug-file path is a usage error: Fontaine exits with code 2 and names the variable or flag.

Exit codes

CodeMeaning
0Success. A headless run that finished exits 0 even when tool calls were denied.
1A run error: a provider or model failure, a failed model listing, a run stopped by --max-turns or --max-budget-usd, a headless goal that ended impossible or paused, or an --afk run that was blocked or stopped (see AFK mode).
2Configuration or usage error. fontaine attach --message also uses 2 for a ticket or pairing the session refused; see remote control.