Model Aliases & Runtime Model Override

Define semantic model aliases (fast, smart, local) in a global config file and override models at runtime without editing role YAML files.

Quick start

1. Create ~/.initrunner/models.yaml:

aliases:
  fast: openai:gpt-4o-mini
  smart: anthropic:claude-sonnet-4-6
  local: ollama:llama3.2:latest
  cheap: groq:llama-3.3-70b-versatile

2. Use aliases anywhere:

# CLI --model flag
initrunner run role.yaml -p "Summarize this" --model fast
initrunner run --model smart
initrunner run role.yaml --serve --model local

# Environment variable
export INITRUNNER_MODEL=fast
initrunner run role.yaml -p "Summarize this"

Aliases are not resolved inside a role file's model block. In a role file, write model: openai:gpt-5-mini or set provider: explicitly. See Role YAML models.

Alias file format

The alias file lives at ~/.initrunner/models.yaml (or $INITRUNNER_HOME/models.yaml):

aliases:
  <alias-name>: <provider>:<model-name>

Each alias target must contain at least one : separator. Additional colons stay in the model name (e.g. ollama:llama3.2:latest is valid — provider is ollama, model is llama3.2:latest).

Invalid alias targets (missing :) are skipped with a warning.

If the file is missing, empty, or unparseable, no aliases are loaded and everything works via explicit provider:model strings as before.

Runtime model override

The --model flag (or INITRUNNER_MODEL env var) overrides the model defined in the role file. Available on these commands:

The flag accepts either an alias name or an explicit provider:model string:

# Alias
initrunner run role.yaml -p "hello" --model fast

# Explicit provider:model
initrunner run role.yaml -p "hello" --model openai:gpt-4o

When the override is applied, temperature and max_tokens from the original role config are preserved. If the provider changes, base_url and api_key_env are cleared (since they're typically provider-specific).

Precedence

Model resolution follows this order (highest to lowest):

1. --model CLI flag / INITRUNNER_MODEL env var
2. Role YAML model (a provider:model string, or a mapping with an explicit provider; aliases are not resolved here)
3. run.yaml defaults (ephemeral mode and new / flow new / doctor)
4. API key env-var auto-detection

The --dry-run flag operates at a different layer: the agent is built with the real model (alias/override applied), then TestModel replaces it at runner execution time.

Role YAML models

Aliases are not resolved inside a role YAML model block. Use an alias with --model, INITRUNNER_MODEL, or run.yaml instead.

In a role file, write the model in one of the two forms the loader resolves:

# String shorthand containing a colon
model: openai:gpt-5-mini

# Mapping with an explicit provider
model:
  provider: openai
  name: gpt-5-mini
  temperature: 0.3

A model mapping with no provider is treated as a partial config. The tuning fields (temperature, max_tokens, context_window, fallback, thinking) are kept, but name is dropped and the provider and model are auto-detected from INITRUNNER_MODEL, run.yaml, or an API key env var. Both of these silently ignore the model you named:

# Wrong: "fast" is dropped, the model is auto-detected
model:
  name: fast

# Wrong: a colon in "name" is not split when the block is a mapping
model:
  name: openai:gpt-4o-mini

To use an alias with a role file, pass it at run time:

initrunner run role.yaml -p "hello" --model fast

Ephemeral mode aliases

The run command's --model flag and run.yaml model field both support aliases:

# CLI
initrunner run --model fast

# ~/.initrunner/run.yaml
model: fast

When an alias resolves to provider:model, the provider is extracted automatically — you don't need to specify --provider separately.

Edge cases