Configuration Reference: Octomind TOML Config Fields and Defaults

Use this reference when editing Octomind’s TOML configuration or diagnosing a load error, with every field and its default. It covers the complete shipped template, optional parsed fields, and model, role, tool, and supervisor settings.

Get started

octomind config
octomind config --show
octomind config --validate

The default path is ~/.local/share/octomind/config/config.toml on macOS/Linux and %LOCALAPPDATA%\octomind\config\config.toml on Windows. See Environment Variables for path and credential overrides. --show displays selected settings, not a complete TOML dump. Startup can create or migrate configuration even for inspection commands. Use default.toml for the complete starting file.

The tables below follow template order. “Default” means the value shipped in that template, not permission to omit a required key. Examples are fragments to merge into that complete file; replace an existing table instead of declaring it twice. Arrays of named entries require complete replacements when overriding a name.

Multi-File Configuration

Octomind supports split-file configuration. All *.toml files in the config directory are merged:

1. config.toml is loaded first
2. Other *.toml files are loaded alphabetically
3. Tables deep-merge; arrays of tables concatenate; scalar arrays such as allowed_tools replace
4. Array entries with the same name are deduplicated (the entire last entry wins; it is not a field patch)
5. Scalar values are overridden by later files

This allows organizing config by concern (e.g., mcp-github.toml, commands-custom.toml).

Special Case: mcp-*.toml Override Files

Files matching the pattern mcp-*.toml are loaded AFTER all other *.toml files, regardless of their alphabetical position. This ensures they can reliably override same-named MCP servers defined in earlier files like mcp.toml.

Without this special handling, mcp.toml would lexicographically sort after mcp-github.toml and silently overwrite any server overrides.

This mechanism is used by the model-callable mcp tool’s persist action, which writes to <config_dir>/mcp-<name>.toml with auto_bind = ["<role>"] when enabled. Persisting a disabled server omits auto_bind; it stays defined but is not automatically enabled on the next startup.

The selected OCTOMIND_CONFIG_PATH determines the directory to merge and the primary migration/save path; it does not restrict loading to one file. The file literally named config.toml still sorts first. Ordinary mutations save to the loaded path; config --upgrade and displayed path labels use the standard <data>/config/config.toml. If no TOML exists, loading creates the embedded default config. Existing files must collectively supply required fields; they are not automatically overlaid on the template.

For a split config, put the following in model-local.toml beside config.toml:

[model]
reasoning_effort = "high"

octomind config --validate

Root-Level Settings

About the default value: "assistant:concierge" is a tap agent addressed as category:variant, shipped by the built-in default tap muvon/tap (which resolves to the GitHub repo github.com/muvon/octomind-tap) — not a role defined in this config file. If you search this file for a concierge role you will not find one. A bare tag without a colon (e.g. "developer") resolves against your local [[roles]]; a category:variant tag resolves against installed taps.

version = 26
log_level = "info"
default = "assistant:concierge"
sandbox = false
telemetry = true
commit_attribution = "Co-Authored-By: Octomind <[email protected]>"

Performance & Limits

mcp_response_tokens_threshold = 20000
max_session_tokens_threshold = 300000
cache_keepalive_enabled = false

User Interface

enable_markdown_rendering = true
markdown_theme = "default"
max_session_spending_threshold = 0.0
max_request_spending_threshold = 0.0

Capability auto-activation

# Root keys must precede the first table header.
auto_capabilities = true

[model]

The complete main model profile and inheritance baseline. Persistent role, supervisor, and compression profiles use the same fields; name-only tap/workflow overrides retain the inherited parameters.

request_transport applies to every octohub: and chatgpt: model call, including supervisor and compression calls that inherit it. Set request_transport = "http" to opt out. WebSocket errors do not silently fall back to HTTP or replay a request. The library derives the Octohub WebSocket URL from the existing Octohub HTTP(S) base URL, preserving private hosts and ports; no separate endpoint setting is required.

ChatGPT WebSocket calls: each received response event or ping/pong resets the inactivity timer; waiting for a session connection does not consume it. Connection setup has a separate deadline.

[model]
name = "octohub:auto"
reasoning_effort = "medium"
max_tokens = 32768
temperature = 0.3
top_p = 0.7
top_k = 20
max_retries = 1
retry_timeout = 30
request_timeout_seconds = 300
stream_timeout_seconds = 0
request_transport = "websocket"

[capabilities]

Map of capability name to provider override. Used by tap agents to route specific capabilities to different providers.

[capabilities]
codesearch = "octocode"  # uses capabilities/codesearch/octocode.toml

Type: map of strings to strings; default {}. Each key maps to a provider TOML file within the tap's capabilities/ directory.

[taps]

String-to-string map, default {}, of tap agent tag to model name. It changes only name; all other parameters come from the main profile before any independent role override.

[taps]
"developer:general" = "ollama:glm-5.3"
"assistant:concierge" = "openai:gpt-5.6-luna"

Priority (highest wins): explicit runtime override > the active role's [roles.model] > the tap name mapping > [model].

1. --model CLI flag (if provided)
2. The model the agent's role/manifest declares (for developer:general, the manifest's role model)
3. Main [model] profile — its name is replaced by the matching tap mapping when present

[taps] only applies to tap agents (tags with :). Plain roles resolve [roles.model] directly against [model].

[[roles]]

Define custom roles that override or extend tap-provided agents.

The shipped role entries are below; the full default system strings are in the linked template. None of these four entries declares a model override. system and welcome are required strings, with no generic default for a new role.

[roles.model]

Optional partial model profile for the role: name (string), reasoning_effort (enum), max_tokens (u32), temperature/top_p (f32), top_k/max_retries (u32), and retry_timeout/request_timeout_seconds (u64). Every omitted field inherits its [model] value. The example below changes only name and effort.

[roles.mcp]

MCP configuration for the role. Omitting the whole table gives empty lists; if the table is present, both lists are required. The shipped values vary by role as shown above.

[[roles]]
name = "assistant"
system = """
You are helpful and knowledgeable assistant.
Working directory: {{CWD}}
"""
welcome = "Hello! Ready to code. Working in {{CWD}} (Role: {{ROLE}})"

[roles.model]
name = "openai:gpt-5.6-sol"
reasoning_effort = "high"

[roles.mcp]
server_refs = ["core", "orchestration", "runtime", "filesystem", "agent"]
allowed_tools = ["core:*", "orchestration:*", "runtime:*", "filesystem:*", "agent:*"]

[mcp]

Global MCP (Model Context Protocol) configuration.

[[mcp.servers]]

MCP server definitions. Three types supported: builtin, http, stdio.

Builtin servers (declared in the template; enabled through role references or exact auto_bind, no external process):

filesystem is not declared here. It is an external stdio server backed by octofs and provided through tap capabilities. Tool availability comes from the installed external server. /mcp full shows the installed server's authoritative schemas.

Common server fields

HTTP server fields

Authentication: Configure a static Authorization header for bearer tokens or API keys. Without one, Octomind uses MCP Authorization Discovery (RFC 9728), registers via CIMD/DCR, and authenticates using PKCE.

Stdio server fields

The template declares core, runtime, agent, and orchestration, each with type = "builtin", timeout_seconds = 30, and tools = []. HTTP/stdio entries are commented examples, not active defaults. Timeouts must be 1–3600 seconds. Auto-bound servers also gain server_refs and, when restricted, a server:* allowance in the merged role. Executables in .agents/tools/ form an additional dynamically registered local tool surface; they are not another template server entry.

[mcp]
allowed_tools = []

[[mcp.servers]]
name = "search"
type = "http"
url = "http://localhost:9000/mcp"
headers = { Authorization = "Bearer {{ENV:MY_MCP_TOKEN}}" }
timeout_seconds = 30
tools = []
auto_bind = ["developer:general"]

[[mcp.servers]]
name = "files"
type = "stdio"
command = "octofs"
args = []
env = { PROJECT_LABEL = "demo" }
cwd = "."
timeout_seconds = 30
tools = []
auto_bind = ["developer:general"]

The HTTP example needs your running endpoint and MY_MCP_TOKEN; the stdio example needs octofs installed. Inspect the actual enabled surface inside a session:

/mcp full

[[hooks]]

Webhook HTTP listeners that pipe payloads through scripts and inject output into sessions.

[[hooks]]
name = "github-push"
bind = "0.0.0.0:9876"
script = "/tmp/octomind-hook.sh"
timeout = 30

No hooks are active in the template. To try the example, create its script, add the TOML above, then launch and send a payload (the final command goes in another terminal):

printf '#!/bin/sh\ncat\n' > /tmp/octomind-hook.sh
chmod +x /tmp/octomind-hook.sh
echo "Wait for webhook messages" | octomind run --name hooks-demo --daemon --format jsonl --hook github-push
curl --data 'Summarize the current task status' http://127.0.0.1:9876/

[[commands]]

Custom session commands triggered with /run <name>. Each entry delegates to a role over ACP — the actual model, system prompt, and MCP configuration live in [[roles]], not here. name is the token you type after /run. See the field table below, including the required input_mode / output_mode / output_role fields.

[[commands]]
name = "reduce"
description = "Compress session history for cost optimization during ongoing work"
command = "octomind acp reduce"
input_mode = "all"
output_mode = "replace"
output_role = "assistant"

The template ships only the reduce command shown above. Run it inside an existing session:

/run reduce

Multi-step AI workflows are no longer defined in this config. Use the external CLI: octomind workflow <file.toml> — see doc/usage/09-workflows.md.

input_mode, output_mode, and output_role have no default — config loading fails if any is omitted. Only workdir is optional.

[[agents]]

Specialized AI agents using ACP protocol. Each becomes an MCP tool (agent_<name>).

[[agents]]
name = "context_gatherer"
description = "Gather detailed context from files and codebase."
command = "octomind acp task_researcher"
workdir = "."

The template’s one agent is named context_gatherer, with workdir = "." and command octomind acp context_gatherer. It does not define a matching context_gatherer role. The example above points the same tool at the shipped task_researcher role; that role still needs an available filesystem server.

[[prompts]]

Reusable prompt templates accessible via /prompt <name>.

[[prompts]]
name = "review"
description = "Request code review with focus on best practices"
prompt = """Please review the code above focusing on:
- Code quality and best practices
- Security considerations
- Performance implications"""

The template ships review, explain, optimize, test, and debug, each with its own description and prompt text in default.toml. There is no generic default for name or prompt; description is absent when omitted. Text is injected verbatim, without variable substitution.

/prompt review

[skills]

Automatic skill activation and validation.

[skills]
auto_activation = true
auto_validation = false
activation_timeout = 3
validation_timeout = 60
max_retries = 3

auto_validation scope: this flag gates only the validate scripts declared inside SKILL.md files. It does not gate the separate guardrail [[validator]] system in .agents/guardrails.toml — those end-of-turn validators run unconditionally regardless of this setting.

[timing]

Per-person calibration of the human-time and energy estimate in /report. The defaults are starting guesses; see Human Time and Energy for the model, its sources, and the calibration procedure. Reading, review and typing speeds and the flag thresholds are fixed research values in timing.rs, not config.

[timing]
think_overhead_min = 1.5
deliberation_factor = 2.0
attention_window_min = 30.0
review_weight = 2.0
wait_weight = 0.25
switch_cost_dhe = 0.05

Configs from before schema version 20 gain this section on upgrade; values already present are kept.

[compression]

Automatic context compression system.

The automatic trigger adapts within a long turn: successive folds raise the baseline geometrically, capped under the usable ceiling; a real user turn resets it. Compression may therefore wait beyond threshold.

Depth is computed, not configured. When compression becomes eligible, how deep each compression goes is derived per cycle from the measured session growth rate and the context ceiling — the lower of max_session_tokens_threshold (see Performance & Limits) and the session model's usable window. The derived ratio always lands in [2.0, 16.0].

[compression.attention]

Optional PACT-style provenance and archive governance around compression.

[compression.attention.governance]

[compression.attention]
enabled = false
validator = true
telemetry = true

[compression.attention.governance]
enabled = true
verify_hash = true

Keep scalar [compression] keys before nested [compression.attention] and [compression.model] headers; TOML assigns later scalars to the most recent nested table.

[compression.model]

Model used for compression decisions and summary generation.

[compression]
knowledge_retention = 25
analysis_findings_max_tokens = 6000
threshold = 105000

[compression.model]
name = "octohub:auto"
reasoning_effort = "none"
max_tokens = 32000
temperature = 0.3
top_p = 1.0
top_k = 0
max_retries = 1
retry_timeout = 30
request_timeout_seconds = 300

[decision]

Calibrated decisions use a provider-qualified model for selected routing and evaluation seams. The model gets one attempt with a five-second timeout and no retries. An absent or empty model disables this routing. If a decision answer is unavailable, supervisor decisions fail closed; writing still uses the shared [supervisor.model] profile. Configure the credential required by the selected provider: CLOUDFLARE_API_KEY and CLOUDFLARE_ACCOUNT_ID, TYPESAFE_API_KEY, or OCTOHUB_API_KEY (and optionally OCTOHUB_API_URL).

[decision]
model = "cloudflare:typesafe/jev"
recall = false
skills = false
capabilities = false
compression = false
supervisor = false

[supervisor]

The out-of-band control plane around the agent loop. It hosts learning (distill + recall + orientation memory), deterministic detectors, the verify-gate, the external plan manager, and condense. See the Supervisor guide for how the mechanics fit together. Strict: the [supervisor] section and its required keys must be present — a missing section or key is a hard parse error, not a silent default.

When the supervisor is active, deterministic detectors, goal recitation, and check-after-mutation pre-gates use fixed internal thresholds. The enabled switches below control their respective model-driven mechanics. Detector hints are advisory; max_identical_rounds is the one hard stop.

[supervisor.model]

Optional partial profile shared by every supervisor mechanic: authorizer, gate, resolve, plan, condense, extraction, recall, retention, verification, and evolution. It accepts every field from [model]; omitted fields inherit main. Omitting the entire block uses [model] unchanged.

[supervisor.hindsight]

An optional, local verifier scores the session event trace when the agent hands a turn back. It estimates whether the user's next turn will be a correction and, if so, its class. This is observe-only: scores are logged, shown in a supervisor notice, tallied in /info, and appended to hindsight.jsonl beside the verify-gate verdict. Hindsight inference is shared across Octomind processes using the same runtime directory. An automatically started worker owns the model; client processes keep no Hindsight weights. The worker exits after 15 minutes without clients. The hidden hindsight-worker command is internal and should not be launched manually. On macOS, Octolib reuses CoreML compiled-model cache entries; Linux and Windows retain their existing execution-provider selection.

[supervisor.hindsight]
enabled = false
model = "muvon/hindsight"

[supervisor.advise]

An optional, model-written steer note. On a loop or recovery alarm, one shared supervisor-model call reads the request, the last tool receipts, and any stuck-keyed experience records, and answers with a short observation that cites a receipt (#N). It never gives a command or code, and it may skip, in which case the plain note goes out. One in four eligible alarms is a control that gets the plain note. Every alarm is appended to advise.jsonl in the data directory with the gate verdict that followed. With [decision] supervisor = true, an observe-only usefulness score is logged beside it. See the Supervisor guide.

[supervisor.advise]
enabled = false

[supervisor.learning]

Cross-session adaptive learning. Extracts lessons and orientation memory (durable subject understanding, recalled as working assumptions to verify) from sessions and injects them into future sessions. See Learning Guide for full details.

[supervisor.learning.evolution]

Optional grounded behavior evolution. When enabled, newly stored quote-backed rules and verified experiences may produce scoped native skill or guardrail candidates. Synthesis and admission both use the single [supervisor.model] profile, which must support structured output. A trial randomizes each session into a control arm (trigger observed, behavior not applied) or a treatment arm, so both arms run concurrently; it is promoted only when the treatment beats that control by more than the noise margin and by more than 2.5 posterior standard deviations, at an acceptable API-call cost; see Learning.

[supervisor.gate]

Verify-gate on every turn stop: a done claim, or a blocked/need_input hand-back checked for being genuine. Free deterministic pre-gates run first (no model call); the LLM checklist runs only if those pass.

The advisory names every remaining unsettled condition. With gate evaluation enabled, a calibrated check removes conditions whose specific case a recorded action exercised (probability at least 0.5 in any evidence slice). Refused answers, unavailable evaluation, or disabled evaluation keep the conditions. Repeated uncertainty does not send another advisory within the same turn, and it never certifies success or becomes a blocking failure. Matched findings missing a verbatim citation receive one bounded protocol repair before any advisory decision; this shares the existing format-repair budget.

With [decision] supervisor = true, a working-tree diff larger than the gate's size cut is not cut by size: the evaluation model scores every hunk in batched windows, as the condense seam scores tool-output chunks, and the verifier reads in full the hunks the request's conditions depend on (the work itself and the checks produced for it), bounded by what the verifier model's input window leaves. The rest become one-line stubs naming the hunk and marked unseen, so the verifier knows they exist and does not read them as absent changes. An unavailable or empty answer falls back to the size cut. The second-opinion refutation reads evidence over the evaluation state cap in slices and drops a finding any slice refutes.

[supervisor.authorizer]

Checks exact proposed tool operations against role + user intent after native pre-call guards and before execution. Uses [supervisor.model]; uncertain or unavailable decisions allow calls. A block requires grounded source/argument evidence and independent confirmation by the same shared model. Requires the supervisor master switch for root sessions. Inherited delegation constraints remain enforced in child sessions. See Tool authorization.

[supervisor.plan]

Adaptive external plan manager. The specialist has no plan mutation tool; a sparse hidden signal emitted alongside real work wakes this manager only when planning or a transition is needed.

[supervisor.condense]

Task-aware narrowing of oversized plain-text tool outputs. A result whose own output exceeds tokens_threshold becomes a candidate; smaller results in the same round are passed through untouched and never shown to the condenser. One shared supervisor-model call per round selects, by original line ranges over a bounded query/diagnostic-aware view, what the current task needs; kept lines are reconstructed verbatim, and irrelevant results get deterministic notices rather than model-authored summaries. Full originals are spilled to session files first when the active role can read them back. The mcp_response_tokens_threshold prefix-cut is applied before condensation.

[supervisor]
enabled = true
max_identical_rounds = 10

[supervisor.model]
name = "octohub:auto"
reasoning_effort = "medium"
max_tokens = 8192
temperature = 0.0
top_p = 1.0
top_k = 0
max_retries = 1
retry_timeout = 30
request_timeout_seconds = 300

[supervisor.hindsight]
enabled = false
model = "muvon/hindsight"

[supervisor.advise]
enabled = false

[supervisor.learning]
enabled = true

[supervisor.learning.evolution]
enabled = false
min_samples = 10
noise_margin = 0.15
cost_allowance = 0.10
cost_per_gain = 2.0
max_trial_uses = 40

[supervisor.gate]
enabled = true

[supervisor.authorizer]
enabled = false

[supervisor.plan]
enabled = true

[supervisor.condense]
enabled = true
adaptive = false
tokens_threshold = 5000

Parsed fields absent from active template settings

These are accepted configuration surfaces, not additional shipped defaults. Runtime-only role_map, runtime_output_mode, working_directory, and config_path are skipped by serde and cannot be set in TOML.

The root model string and historical flat model parameters are migration/normalization inputs, not the version-12 output format; use [model]. The ProvidersConfig/OpenRouterConfig compatibility types in src/config/providers.rs are not fields of the loaded Config; they do not enable TOML credential storage.

[registry]

Controls caching of agent manifests fetched from taps. Registry sources themselves are managed with octomind tap <user/repo> [path] and octomind untap <user/repo>.

Fetched manifests are cached at <data>/agents/<category>/<variant>.toml. Within the TTL the cached manifest is served immediately; once stale, the cached copy is still served (stale-serve) while a background refresh fetches the latest version. See Tap System for the registry behavior.

[registry]
cache_ttl_hours = 24

Guardrails (.agents/guardrails.toml)

This separate project file is parsed by src/config/guardrails.rs; none of these keys belongs in the main config. Each table is an optional array, defaulting to empty. The complete operating guide and script examples are in Guardrails.

when conditions on guards/validators use +target (used) or -target (not used). Role filters here accept an exact tag or domain prefix. Main-config MCP auto_bind remains exact-match only. Project [[hook]] is distinct from the main-config HTTP listener [[hooks]].

# .agents/guardrails.toml
[[guard]]
match = 'shell(command=^rm\s+-rf)'
message = "Recursive force deletion is blocked in this project."

Template Variables

These variables are substituted in role system and welcome fields at prompt-expansion time:

{{HOME}} is not substituted here. It is only resolved by the octomind vars command listing, not in system/welcome prompts. Using {{HOME}} in a role prompt leaves the literal text in place — use an absolute path or {{CWD}} instead.

octomind vars --preview

[[roles]]
name = "brief"
system = "Answer briefly. Working directory: {{CWD}}. Role: {{ROLE}}."
welcome = "Ready in {{CWD}}"

[roles.mcp]
server_refs = []
allowed_tools = []

octomind run brief

Common questions

• Why did an override lose fields? Same-name array entries replace the entire earlier entry. Copy the complete role/server/command before changing it; scalar tables such as [model] deep-merge instead.
• Why is a tool missing? Check role server_refs, exact auto_bind tags, server tools, and role allowed_tools, then inspect /mcp full. A template role reference does not install an external server.
• Why is a compression setting ignored? Root compression keys must precede its nested table headers. Use [compression.model]; [compression.decision] is only a legacy load alias when the current table is absent.
• Why did validation reject a short config? Existing configs are strict, not sparse overlays on built-in defaults. Start from the complete template, then split it if needed.

Source map

Defaults and long prompt strings: default.toml. Loading and merging: loading.rs, merge.rs. Schemas: config/mod.rs, model.rs, roles.rs, mcp.rs, layer_trait.rs, supervisor/mod.rs.

See also

• CLI Reference
• Session Commands
• Environment Variables
• Configuration Guide