config

Don't own: tap registry artifacts — agent manifests, capabilities, deps, and skills belong to octomind:tap and are the preferred home for reusable role plus MCP wiring. Workflow pipelines belong to octomind:workflow. Secrets management beyond pointing at the right environment variable name.

A role that other people or projects should be able to run belongs in a tap manifest with capabilities = [...], not hand-wired [[roles]] plus [[mcp.servers]] in a local config. Say so when a user asks for something that is really a tap agent, and route to octomind:tap. Local config is for machine-specific settings: models, keys, limits, personal roles, and overrides.

Strictness

The file is strict: [model], [skills], [timing], [compression], [supervisor] and every [supervisor.*] mechanic table are required, and a missing section or key is a hard parse error, not a silent default. An omitted field inside a present section can still take its code default, which is why learning is on out of the box only because the shipped template sets enabled = true. An older file that fails on missing sections usually needs octomind config --upgrade, not hand edits; never change version.

[[layers]] and [[commands]] share one schema where input_mode, output_mode, and output_role have no defaults; omitting any of them fails config loading. Only workdir is optional.

Model settings

[model] is the complete baseline profile (name, reasoning_effort, max_tokens, temperature, top_p, top_k, max_retries, retry_timeout, request_timeout_seconds); [roles.model], [compression.model], and [supervisor.model] override only the fields they set. Model priority, highest first: CLI --model or /model, the role's model, a [taps] entry (model name only, tap agents only), then [model].name. Sampling values are dropped for models that reject them, so changing temperature does nothing on current Claude models — say so instead of tuning it.

Environment and secrets

Two .env files load in precedence order — user-scope alongside config.toml, then project-local ./.env, which wins. Both override the system environment, and an empty value counts as not set. Put an API key in a .env file and reference the variable name; never paste a secret value into config.toml or into your reply.

Internal exploration commands

• octomind config --show — effective merged config
• octomind config --validate — parse and validate; the verifier for every edit
• octomind config --upgrade — migrate an older config version
• octomind vars — resolved template placeholder values
• octomind complete run — every available role tag