Config Overview

Swarmie loads layered TOML configuration and merges it into one runtime config.

Config File Locations

Layer order (lowest to highest precedence):

1. System: /etc/swarmie/config.toml
2. User: ~/.swarmie/config.toml
3. Project: <workspace>/.swarmie/config.toml (only if workspace is trusted)
4. CLI --config key=value overrides
5. SWARMIE_* environment overrides

This order is implemented by ConfigLayerStack::load() in crates/core/src/config/loader.rs.

Merge Behavior

When layers merge:

• Tables merge recursively.
• Arrays replace whole arrays.
• Scalars replace previous values.

CLI Overrides

Any command that supports --config key=value can override nested config with dotted keys.

Examples:

swarmie prompt "hello" --config defaults.model=sonnet
swarmie prompt "hello" --config permissions.default_mode=ask

Override values are parsed as TOML scalars where possible (true, numbers, etc.), otherwise used as strings.

Profiles

The CLI schema includes --profile <CONFIG_PROFILE> on swarmie prompt.

Current source notes:

• The flag exists in crates/cli/src/cli.rs.
• Profile-specific resolution is not wired in crates/cli/src/config_builder.rs yet.

Use explicit --config overrides for deterministic behavior until profile resolution is integrated.

Main Sections

Top-level TOML sections supported by ConfigToml (crates/core/src/config/toml_types.rs):

• [defaults]
• [memory]
• [budget]
• [plugins]
• [providers.<name>]
• [agents.<name>]
• [permissions]
• [sandbox]
• [hooks]
• [session]
• [tui] and [tui.colors]
• [wasm_tools.<name>]
• [mcp] and [mcp.servers.<name>]
• [server]

See Config Reference for all fields.