Configuration Reference

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

Root-Level Settings

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: CLI --model > taps override > role.model > config.model When you run octomind run developer:general, the model is resolved in this order:

1. --model CLI flag (if provided)
2. [taps] override for "developer:general" (if configured)
3. Global model in config

Empty by default. Only applies to tap agents (tags with :). Plain role names use role.model or 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 help. 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 no longer a builtin — it's an external stdio server backed by octofs. See MCP Tools for the tool 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

[[pipelines]]

Deterministic script-driven processing steps that run before workflows.

[[pipelines.steps]]

Substeps are nested as [[pipelines.steps.substeps]] with the same schema.

[[pipelines]]
name = "context_pipeline"
description = "Gather context before AI processing"

[[pipelines.steps]]
name = "detect_files"
type = "once"
command = "./scripts/detect-files.sh"
timeout = 30

[[pipelines.steps]]
name = "enrich"
type = "once"
command = "./scripts/enrich-context.py"
timeout = 60

[[workflows]]

Multi-step AI processing workflows.

[[workflows.steps]]

Substeps are nested as [[workflows.steps.substeps]] with the same schema.

[[workflows]]
name = "developer_workflow"
description = "Two-stage workflow: refine task, then research context"

[[workflows.steps]]
name = "refine"
type = "once"
layer = "task_refiner"

[[workflows.steps]]
name = "research"
type = "once"
layer = "task_researcher"

[[layers]]

AI processing layers used by workflows and commands. Layers delegate to roles via ACP protocol — the actual model, system prompt, and MCP configuration live in [[roles]], not here.

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

[[layers]]
name = "task_researcher"
description = "Gathers information and context needed for development tasks through code analysis"
command = "octomind acp task_researcher"
input_mode = "last"
output_mode = "append"
output_role = "assistant"

[[commands]]

Custom session commands triggered with /run <name>. Uses the same schema as [[layers]].

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

[compression]

Automatic context compression system.

[[compression.pressure_levels]]

| Field | Type | Description | | threshold | u64 | Token count threshold to trigger compression | | target_ratio | f64 | Compression strength (2.0 = 50% reduction, 4.0 = 75%, 8.0 = 87.5%) |

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 = "anthropic:claude-haiku-4-5"
max_tokens = 16000
temperature = 0.3
top_p = 1.0
top_k = 0
max_retries = 1
retry_timeout = 30
ignore_cost = false

[learning]

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

[learning.store] (MCP backend only)

[learning.retrieve] (MCP backend only)

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

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

Available in system and welcome fields: