Configuration

The harness is configured through environment variables — supplied via a per-user credential store, project .env files, or your shell. minima config manages the per-user store.

Managing credentials

minima config                       # list every configurable key (secrets masked)
minima config set <KEY> <value>     # store a credential
minima config get <KEY>             # print a stored value

You don't have to drop to the CLI — the same is available inside the interactive TUI via the /config slash command:

/config                     # open the config editor / list keys
/config set <KEY> <value>   # store a credential
/config get <KEY>           # print a stored value

Secrets are stored keychain-first: the OS keychain (macOS Keychain, Linux Secret Service, Windows Credential Manager) via keytar when available, otherwise a ~/.minima-harness/config.env file written mode 0600. Non-secret values (URLs) always live in the file. minima config set reports which backend it used.

Precedence

When the harness starts it loads configuration in this order — earlier wins, and lower layers never overwrite something already set:

1. CLI flags — --budget, --model, and friends. The user acting now.
2. Real shell environment — anything already exported in your shell.
3. Project .env files in the current directory — .env.harness, then .env. Only fills keys not already set.
4. Project config — .minima/config.toml, the one committed layer. Allowlisted keys only, and it may only move a value toward the safer side (see below).
5. Per-user store — OS keychain + ~/.minima-harness/config.env, materialized into the environment with set-default semantics (lowest precedence).

Project config (.minima/config.toml)

Every layer above is uncommitted, and therefore trusted because you wrote it. .minima/config.toml is the exception: it is checked in, so it arrives with git clone — written by someone else. That inversion is what the rules below exist for.

# .minima/config.toml — committed, so it may only tighten what you already allow.
[budget]
limit_usd = 2.00        # only ever LOWERS your ceiling
mode = "enforce"        # only ever gets STRICTER
 
[routing]
candidates = ["claude-haiku-4-5", "gemini-2.5-flash"]   # intersected with your pool
 
[compaction]
artifact_spill = true   # neutral — plainly shadows, like any other setting

Three rules hold:

1. The allowlist is the gate. Keys not on the list below are ignored — not blocked, ignored, and the harness says so on startup. A repo cannot set your API keys, and cannot reach any variable outside the four in the table: not a feature flag, not a permission, not a search path.
2. A project file may only move a value toward the safer side. Not a spend special case: every allowlisted key declares a direction, or is neutral and plainly shadows.
3. The clamp runs in the loader, before anything reaches the environment — so no part of the harness downstream can ever observe an unclamped value.

The clamp cuts across precedence in one direction only, and it stops at the flags: --budget, --budget-enforce and --model are you acting right now, so they win over a project file the way they win over everything else.

Thinking level, judge sampling and the default model are deliberately not on the list — not because they are dangerous, but because nobody can yet name their safer side. The list grows by argument, not by default. Search paths are directional too (narrowing is safe, widening is not), which is why the default list is legislated in code rather than configured here.

A file that will not parse is reported and skipped: config never blocks startup. MINIMA_TUI_PROJECT_CONFIG=0 ignores the file entirely.

Environment variables

Mubit / Minima routing

Harness features

These are on by default — set the variable to 0 to opt out. Every one fails open: with the feature off the harness behaves exactly as it did before it existed.

Two variables work the other way — they grant something the harness refuses by default:

Opt-in features live behind the experimental umbrella — see Experimental features.

LLM provider keys

Set a key for any provider you want the harness to be able to run. The first environment variable listed for a provider wins.

Default model catalog

Out of the box the harness seeds this catalog; /model lets you pin one or add your own.

When routing (not pinned), Minima chooses from the candidate set gemini-2.5-flash, claude-haiku-4-5, claude-sonnet-4-6, gemini-2.5-pro, claude-opus-4-8 by default.

Config files at a glance