Configuration Reference

Use this reference when editing Octomind’s TOML configuration or diagnosing a load error. 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, layers-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 = 13
log_level = "info"
default = "assistant:concierge"
sandbox = false
telemetry = true

Performance & Limits

mcp_response_tokens_threshold = 20000
max_session_tokens_threshold = 200000
cache_keepalive_enabled = false
cache_keepalive_max_idle_seconds = 1800

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.

[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

[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>. Uses the exact same schema as [[layers]] (same LayerConfig struct) — see the field table below, including the required input_mode / output_mode / output_role fields. The only difference is invocation: [[commands]] entries are run manually from a session via /run <name>, while [[layers]] are orchestration units invoked over ACP. For [[commands]], name is the token you type after /run.

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

[[layers]]

Optional reusable ACP-invocable units; the template has no active [[layers]] entries. [[commands]] uses the same schema. Layers delegate to roles via the ACP protocol — the actual model, system prompt, and MCP configuration live in [[roles]], not here.

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.

[[layers]]
name = "task_refiner"
description = "Refines and clarifies user requests for better processing by subsequent layers"
command = "octomind acp task_refiner"
input_mode = "last"
output_mode = "none"
output_role = "assistant"

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

[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 = 70000

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

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

[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.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. Thresholds and trial limits are fixed internal constants.

[supervisor.gate]

Verify-gate on self-reported completion. Free deterministic pre-gates run first (no model call); the LLM checklist runs only if those pass.

[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

[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.learning]
enabled = true

[supervisor.learning.evolution]
enabled = false

[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