Configuration Reference

All values shown match config-templates/default.toml. Fields marked (required) have no fallback default.

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.

Performance & Limits

User Interface

[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

Empty by default. Each key maps to a provider TOML file within the tap's capabilities/ directory.

[taps]

Map of tap agent tag to model override. Set a preferred model for specific tap agents.

[taps]
"developer:general" = "ollama:glm-5"
"octomind:assistant" = "openai:gpt-4o"

Priority (highest wins): CLI --model > the active role's model > root config.model (resolved in src/session/chat/session/core.rs). For a tap agent, a [taps] entry overrides the config.model tier:

1. --model CLI flag (if provided)
2. The model the agent's role/manifest declares (for developer:general, the manifest's role model)
3. Global model in config — which a [taps] entry for "developer:general" replaces when set

[taps] only applies to tap agents (tags with :); it acts at the config.model tier, so it takes effect only when neither --model nor the agent's role sets a model. Plain role names use their [[roles]] model if set, otherwise config.model.

[[roles]]

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

[roles.mcp]

MCP configuration for the role.

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

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

[mcp]

Global MCP (Model Context Protocol) configuration.

[[mcp.servers]]

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

Builtin servers (always available, no external process):

filesystem is not declared here. Default roles reference a filesystem server in their server_refs, but it is not a builtin and is not defined in this config file's [[mcp.servers]]. It is an external stdio server backed by octofs, provided by the built-in tap. Its tools are view, text_editor, batch_edit, extract_lines, shell, and workdir. See MCP Tools for the full surface.

Common Fields

HTTP-Specific Fields

OAuth Authentication: HTTP servers requiring authentication are handled automatically via MCP Authorization Discovery (RFC 9728). No manual configuration needed — just provide the URL and Octomind will discover OAuth endpoints, register via CIMD/DCR, and authenticate using PKCE.

Stdio-Specific Fields

[[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 = "/path/to/process-github-push.sh"
timeout = 30

[[layers]]

Reusable ACP-invocable units used by [[commands]]. 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"

[[commands]]

Custom session commands triggered with /run <name>. Uses the exact same schema as [[layers]] (same LayerConfig struct) — see the field table above, 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"

[[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 context_gatherer"
workdir = "."

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

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

Disabling compression: if [[compression.pressure_levels]] is empty, compression is disabled entirely and the compression-model validation is skipped. Independently, max_session_tokens_threshold (see Performance & Limits) acts as a hard token ceiling separate from these pressure levels.

[[compression.pressure_levels]]

Default pressure levels:

[compression.decision]

Model used for compression decisions and summary generation.

[compression]
hints_enabled = true
hints_pressure_threshold = 0.7
hints_min_interval = 5
knowledge_retention = 10

[[compression.pressure_levels]]
threshold = 60000
target_ratio = 2.0

[[compression.pressure_levels]]
threshold = 120000
target_ratio = 4.0

[[compression.pressure_levels]]
threshold = 160000
target_ratio = 8.0

[compression.decision]
model = "openai:gpt-5-mini"
max_tokens = 16000
temperature = 0.3
top_p = 1.0
top_k = 0
max_retries = 1
retry_timeout = 30
ignore_cost = false

[supervisor]

The out-of-band control plane around the agent loop. It hosts learning (distill + recall), orientation memory, deterministic detectors, and the verify-gate. 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. Breaking change: the former top-level [learning] table now lives at [supervisor.learning] — there is no migration.

[supervisor.learning]

Cross-session adaptive learning. Extracts lessons from sessions and injects them into future sessions. See Learning Guide for full details.

[supervisor.learning.store] (MCP backend only)

[supervisor.learning.retrieve] (MCP backend only)

[supervisor.orientation]

Durable understanding of the subject (decisions, structure, constraints), stored in the same backend as lessons under memory_type = "orientation" and recalled as working assumptions to verify, never as truth.

[supervisor.detectors]

Deterministic, free, every-turn signals that decide when (rarely) to wake the model. Fused with the agent's own <sup>…</sup> self-report token.

[supervisor.gate]

Verify-gate on self-reported completion.

[supervisor.condense]

Task-aware narrowing of oversized tool outputs. One cheap-model call per round selects, by line ranges over a numbered copy, what the current task needs; kept lines are reconstructed verbatim (never rewritten). Full originals are spilled to session files first (lossless — the condensed result carries the path). The mcp_response_tokens_threshold prefix-cut still applies afterwards as the hard ceiling.

[supervisor]
enabled = true
model = "anthropic:claude-haiku-4-5"

[supervisor.learning]
enabled = true
model = "anthropic:claude-haiku-4-5"
backend = "file"
min_messages_for_intermediate = 3
max_inject = 5

[supervisor.orientation]
enabled = true
max_inject = 5
decay_days = 90

[supervisor.detectors]
loop_threshold = 3
no_progress_window = 5
self_report = true

[supervisor.gate]
enabled = true
max_iterations = 2

[supervisor.condense]
enabled = true
tokens_threshold = 2000
model = "anthropic:claude-haiku-4-5"

[registry]

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

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)

Project-level guardrails are configured in .agents/guardrails.toml in the working directory, not in the main config file. That file holds four distinct mechanisms — [[guard]], [[hook]], [[validator]], and [[pipe]]. Only [[pipe]] is detailed below; see Guardrails for the full reference.

Do not confuse the guardrail [[hook]] (a post-result script in .agents/guardrails.toml) with the top-level [[hooks]] config above (webhook HTTP listeners for daemon mode). They are entirely separate concepts.

[[pipe]] — Pre-Model Input Transform

Preprocesses user input through an external script before the model sees it. At most one [[pipe]] may match per message.

# .agents/guardrails.toml
[[pipe]]
name = "prepare"
command = "./prepare.sh"
when = "first"
match = "^/deploy"
roles = ["developer:general"]

Environment variables set when spawning: OCTOMIND_ROLE, OCTOMIND_WORKDIR, PIPE_NAME, PIPE_RUN_COUNT, SESSION_MESSAGE_COUNT. Timeout: 300 seconds.

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. Arrays of tables (e.g., [[mcp.servers]]) are concatenated
4. Same-name entries are deduplicated (last wins)
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 mcp persist command, which writes to <config_dir>/mcp-<name>.toml with auto_bind = ["<role>"]. These persisted servers are automatically available on the next startup without manual server_refs edits.

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.