Configuration reference

auto-model-router is configured through $AUTO_MODEL_ROUTER_HOME/config.yml (defaults to ~/.auto-model-router/config.yml). The file is a deep-partial overlay on the built-in defaults: set only the keys you want to change. Most per-turn knobs hot-reload — edits apply on the next turn with no restart. The listening socket (server.*), the OpenRouter client (openrouter.*), and the agentdox bridge (context.*) are captured at boot and need a session restart.

All values below are the shipped defaults.

openrouter — upstream & attribution

openrouter.apiKey

OpenRouter key. The router routes only within the models this key is entitled to under your OpenRouter guardrails (fetched via /models/user). Default: empty — borrowed from omp's credential store, or OPENROUTER_API_KEY.

openrouter.title / openrouter.referer

App attribution for OpenRouter's Activity/Apps ranking. title is the display name; referer is the identity requests are grouped by. Default: auto-model-router and the project URL.

openrouter.timeoutMs

Per-request timeout. Agent turns are long. Default: 600000 (10 min).

tiers — the complexity ladder

Each complexity tier sets a quality floor and a price ceiling. A model priced above a tier's ceiling is excluded before ranking; within the tier, score = (quality/100) ^ qualityExponent / effectiveUsd picks the winner. hard has no ceiling — quality is the point of the top tier.

tiers.trivial

minQuality 0, maxInputPerMtok $0.30, qualityExponent 0 (cheapest above the floor).

tiers.simple

minQuality 40, maxInputPerMtok $1.50, qualityExponent 0.

tiers.moderate

minQuality 60, maxInputPerMtok $4.00, qualityExponent 1.

tiers.hard

minQuality 72, no price ceiling, qualityExponent 3.

tiers.<tier>.capabilityFloorUsd

Optional. Pick the highest-quality candidate whose cold-cache cost fits this cap, ignoring quality-per-dollar. Buys quality with money deliberately. Default: unset.

tiers.<tier>.pin

Force a specific slug set for the tier. Default: none.

filters — the eligible catalog

filters.includeFree

Include $0 models. Default: false — free models are rate-limited enough that retries cost more than they save.

filters.requireToolSupport

Default: true.

filters.minTrust / minTrustSamples

Demote models whose measured reliability falls below the floor once enough samples exist. Default: 0.7 over 12 samples.

filters.contextHeadroom

Require a context window this multiple of the estimated prompt. Default: 1.25.

filters.latencyWeight

Inflate a model's effective cost by expected wait (TTFT + completion time). Default: 0 (off) — opt in after establishing a baseline.

filters.maxExpectedWaitMs

Absolute expected-wait ceiling: a hard drop for models proven slower than this (≥ latencyMinSamples), regardless of price — the soft penalty above is multiplicative and capped, so it cannot demote a slow-but-cheap model. New models keep their cold-start turns. Default: unset (off).

escalation — mid-stream recovery

escalation.enabled

Default: true.

escalation.probeTokens

Hold this many tokens before committing, to catch a bad start. Default: 48.

escalation.maxAttempts

Original try plus retries. Each retry beyond the first can abandon generated tokens. Default: 3.

escalation.triggers

malformed_tool_args, refusal, empty_completion, repeat_tool_call, missing_expected_tool_call.

escalation.probeTiers

trivial, simple, moderate — never hard, which has nowhere to escalate to.

hysteresis — cache-aware stickiness

hysteresis.holdTurns / holdTurnsAfterEscalation

Hold the current tier for N turns to protect the warm cache. Default: 2, and 4 after an escalation.

hysteresis.switchMargin

Expected saving must beat the forfeited cache discount by this factor to switch. Default: 1.3.

hysteresis.maxDowngradePerTurn

Step tiers down at most this fast. Default: 1.

hysteresis.breakHoldOnMechanical

Let a mechanical tool-result continuation break a hold that sits above the fresh classification. Default: false.

budget — spend caps

budget.perTurnUsd / perConversationUsd / rolling24hUsd

Optional ceilings, checked against the cold-cache forecast before dispatch. Default: no caps.

budget.onExceeded

downgrade or fail at the ceiling. Default: downgrade.

context — agentdox bridge (restart to change)

context.enabled

Inject one shared project-context block per conversation. Default: false — needs a URL and token.

context.baseUrl / token / defaultScope

agentdox endpoint, bearer, and fallback project scope.

context.memoryLimit / docsLimit / sessionLimit / briefChars

Bound what the server selects, so the block is ranked rather than byte-truncated. Default: 8 / 2 / 6 / 12000, inside a 24000-char cap.

compaction — prompt shrinking

compaction.enabled

Shrink stale, low-value context before dispatch. Default: false — elision is lossy, never implicit.

compaction.budgetTokens

Fire above this prompt size. Default: 40000.

compaction.floorRatio

Compact to this fraction of the budget. Below 1 overshoots and holds the plan (cache-friendly); 1 re-tightens every turn. Default: 1; 0.75 recommended once you have watched your ledger.

Inspecting decisions

auto-model-router stats            # spend and per-model distribution
auto-model-router explain          # candidates, rejections, forecasts for the last turn
auto-model-router models           # the eligible catalog per tier

The full type surface and every field's doc-comment live in src/config/types.ts.