Configuration

Layered TOML config, budget enforcement, retry policy, session persistence.

Configuration layers: defaults → global config → project config → env vars → CLI flags. Secrets (API keys) are always environment variables, never config files.

Config file

Meerkat loads config from TOML files in two locations:

Location	Scope	Example path
.rkat/config.toml	Project (checked into repo or gitignored)	./my-project/.rkat/config.toml
~/.rkat/config.toml	Global (user-wide defaults)	~/.rkat/config.toml

Precedence: defaults → global config → project config → env vars → CLI flags.

Minimal example

.rkat/config.toml

[agent]
model = "claude-opus-4-6"
max_tokens_per_turn = 16384

[shell]
program = "bash"
timeout_secs = 30

Generating a config file

rkat config init          # Creates .rkat/config.toml with defaults
rkat config init --global # Creates ~/.rkat/config.toml

Budget controls

Budget limits cap resource usage per agent run. When a limit is reached the agent completes its current turn, then stops.

max_tokens · integer

Total input + output tokens across all turns.

max_duration · string

Maximum wall-clock runtime. Accepts "30s", "5m", "2h".

max_tool_calls · integer

Maximum total tool invocations.

.rkat/config.toml

[budget]
max_tokens = 50000
max_duration = "5m"
max_tool_calls = 50

Retry policy

Failed LLM calls are retried automatically with exponential backoff and jitter.

.rkat/config.toml

[retry]
max_retries = 3
initial_delay_ms = 500
max_delay_ms = 10000
multiplier = 2.0

Error	Retried?
RateLimited	Yes (uses retry-after header when available)
ServerOverloaded	Yes
NetworkTimeout	Yes
ConnectionReset	Yes
ServerError (5xx)	Yes
InvalidRequest	No
AuthenticationFailed	No
ContentFiltered	No

Session persistence

Sessions record conversation history so agents can resume where they left off.

JSONL (default)

Sessions are stored as JSONL files, one per session.

.rkat/config.toml

[store]
sessions_path = "/custom/path/to/sessions"

Requires the jsonl-store feature flag (enabled by default).

redb (embedded database)

Durable embedded storage using redb. Requires the session-store feature flag.

In-memory (testing)

Ephemeral storage that lives only in process memory. Requires the memory-store feature flag.

Managing sessions

rkat sessions list [--limit N]
rkat sessions show <SESSION_ID>

Logging

Meerkat uses the tracing crate. Configure via RUST_LOG:

export RUST_LOG=info                    # Session lifecycle, turns, completions
export RUST_LOG=meerkat=debug,info      # Debug Meerkat, info for dependencies
export RUST_LOG=trace                   # Wire-level protocol details

Advanced configuration

These features have their own dedicated guides:

Feature	Config section	Guide
Hooks	[hooks]	Hooks guide
Memory and compaction	[compaction]	Memory guide
Sub-agents	[sub_agents]	Sub-agents guide
Inter-agent comms	[comms]	Comms guide
MCP servers	.rkat/mcp.toml	MCP reference
Shell security	[shell]	Built-in tools

See also

• Providers - API key and model setup
• CLI configuration - CLI-specific config details