Providers

The default model is anthropic/claude-sonnet-4-6. You can switch to any supported provider, a local Ollama instance, or a custom OpenAI-compatible endpoint by changing the spec.model block in your role YAML.

Standard Providers

Change provider and name, then install the matching extra if needed:

spec:
  model:
    provider: anthropic
    name: claude-sonnet-4-6

Install all provider extras at once with pip install initrunner[all-models].

Provider Snippets

Anthropic (pip install initrunner[anthropic]):

spec:
  model:
    provider: anthropic
    name: claude-sonnet-4-6

OpenAI (no extra required):

spec:
  model:
    provider: openai
    name: gpt-5-mini

Google (pip install initrunner[google]):

spec:
  model:
    provider: google
    name: gemini-2.5-flash

Groq (pip install initrunner[groq]):

spec:
  model:
    provider: groq
    name: llama-4-scout-17b-16e

Mistral (pip install initrunner[mistral]):

spec:
  model:
    provider: mistral
    name: mistral-large-latest

Cohere (pip install initrunner[all-models]):

spec:
  model:
    provider: cohere
    name: command-a

Bedrock (pip install initrunner[all-models]):

spec:
  model:
    provider: bedrock
    name: us.anthropic.claude-sonnet-4-6-v1:0

xAI (pip install initrunner[all-models]):

spec:
  model:
    provider: xai
    name: grok-4

CLI Provider Switching

Instead of editing YAML, you can switch providers with the configure command:

# Interactive — pick provider and model from menus
initrunner configure role.yaml

# Non-interactive
initrunner configure role.yaml --provider anthropic --model claude-sonnet-4-6

# Configure an installed role by name
initrunner configure code-reviewer --provider groq

# Revert to the original provider/model
initrunner configure code-reviewer --reset

For installed roles (from InitHub or OCI), overrides are stored in registry.json so the original YAML stays pristine. Overrides survive hub updates and reinstalls.

Post-install adaptation: After initrunner install, the CLI checks whether you have the API key required by the role's provider. If the key is missing, it lists your available providers and offers one-step adaptation. Pass --yes to auto-adapt non-interactively.

See CLI Reference: Configure Options for the full flag reference.

Dashboard Provider Setup

You can configure API keys directly from the web dashboard — no terminal required. The provider setup form is available in three places:

• Launchpad zero-state — shown on fresh installs before any agents are created
• Agent creation page — prompted when no provider is configured
• System page — full provider management panel with status indicators

The dashboard supports all standard providers (OpenAI, Anthropic, Google, Groq, Mistral, Cohere, Bedrock, xAI) plus OpenRouter. Key validation is available for OpenAI and Anthropic — the dashboard checks the key before saving.

For programmatic use, two API endpoints are available:

• GET /api/providers/status — returns configuration state for all providers
• POST /api/providers/save-key — saves an API key for a provider (accepts optional base_url for custom endpoints)

Model Selection

PROVIDER_MODELS in templates.py maintains curated model lists for each provider. The interactive wizard (initrunner init -i) and setup command (initrunner setup) present these as a numbered menu. The --model flag on init, setup, and create bypasses the interactive prompt. Custom model names are always accepted — the curated list is a convenience, not a restriction.

For Ollama, the wizard also queries the local Ollama server for installed models and shows those if available.

Ollama (Local Models)

Set provider: ollama. No API key is needed — the runner defaults to http://localhost:11434/v1:

spec:
  model:
    provider: ollama
    name: llama3.2

Override the URL if Ollama is on a different host or port:

spec:
  model:
    provider: ollama
    name: llama3.2
    base_url: http://192.168.1.50:11434/v1

Docker note: If the runner is inside Docker and Ollama is on the host, use http://host.docker.internal:11434/v1 as the base_url.

See Ollama for a full Ollama setup guide.

OpenRouter / Custom Endpoints

Any OpenAI-compatible API works. Set provider: openai, point base_url at the endpoint, and tell the runner which env var holds the API key:

spec:
  model:
    provider: openai
    name: anthropic/claude-sonnet-4
    base_url: https://openrouter.ai/api/v1
    api_key_env: OPENROUTER_API_KEY

This also works for vLLM, LiteLLM, Azure OpenAI, or any other service that exposes the OpenAI chat completions format.

Embedding endpoints: api_key_env works for all embedding providers (standard and custom) via ingest.embeddings.api_key_env or memory.embeddings.api_key_env. When set, InitRunner validates the key at startup and fails fast with an actionable error if it's missing. See Ingestion: Embedding Options for details.

Fallback Chain

Since v2026.4.17, spec.model.fallback accepts a list of provider:model strings (or aliases). When set, the runner wraps the primary and fallbacks in PydanticAI's FallbackModel so runs survive single-provider outages (5xx, 429, auth failures, connection resets) without any call-site changes.

spec:
  model:
    provider: anthropic
    name: claude-sonnet-4-6
    fallback:
      - openai:gpt-5-mini
      - groq:llama-4-scout-17b-16e

Model aliases defined in ~/.initrunner/models.yaml are accepted in the fallback list too:

spec:
  model:
    provider: anthropic
    name: claude-sonnet-4-6
    fallback:
      - smart
      - fast

Validation happens at load time. Every entry is resolved and the matching provider SDK import is probed; a missing extra fails fast, not at first failover. When a run exhausts the chain, the error string lists every provider's failure in order.

Restrictions. Ollama and custom-base_url providers are rejected in the fallback list because aliases can't carry a base_url. If you need a local fallback, promote the Ollama model to the primary and put cloud providers in the fallback chain, or use an explicit OpenAI-compatible endpoint alias.

Model Aliases & Runtime Override

You can define semantic aliases (fast, smart, local) in ~/.initrunner/models.yaml and override the model at runtime with --model or INITRUNNER_MODEL. See Model Aliases for full details.

# Override model at runtime
initrunner run role.yaml -p "hello" --model fast

# Use alias in role YAML (provider auto-resolved)
spec:
  model:
    name: fast

Model Config Reference

Embedding Configuration

When using RAG (spec.ingest) or memory (spec.memory), InitRunner needs an embedding model to generate vectors. The embedding provider is resolved separately from the agent's LLM provider.

Default Resolution

The embedding model is determined by the agent's spec.model.provider unless overridden:

Important: Anthropic does not offer an embeddings API. If your agent uses provider: anthropic, you still need OPENAI_API_KEY set for embeddings. This only applies when using RAG or memory — pure chat agents don't need it.

Overriding the Embedding Model

Set embeddings.provider and embeddings.model in your ingest or memory config:

spec:
  model:
    provider: anthropic
    name: claude-sonnet-4-6
  ingest:
    sources: ["./docs/**/*.md"]
    embeddings:
      provider: openai
      model: text-embedding-3-large

Custom Embedding Endpoints

For self-hosted or third-party embedding services, use base_url and api_key_env:

spec:
  ingest:
    embeddings:
      provider: openai
      model: my-embedding-model
      base_url: https://my-embedding-service.example.com/v1
      api_key_env: MY_EMBEDDING_API_KEY

Embedding Config Reference

See Ingestion: Embedding Models for the full embedding model reference and RAG Guide: Embedding Model Options for a comparison table.

Full Role Example

A complete role definition showing model, tools, ingestion, triggers, and guardrails:

apiVersion: initrunner/v1
kind: Agent
metadata:
  name: support-agent
  description: Answers questions from the support knowledge base
  tags:
    - support
    - rag
spec:
  role: |
    You are a support agent. Use search_documents to find relevant
    articles before answering. Always cite your sources.
  model:
    provider: openai
    name: gpt-5-mini
    temperature: 0.1
    max_tokens: 4096
  ingest:
    sources:
      - "./knowledge-base/**/*.md"
      - "./docs/**/*.pdf"
    chunking:
      strategy: fixed
      chunk_size: 512
      chunk_overlap: 50
  tools:
    - type: filesystem
      root_path: ./src
      read_only: true
    - type: mcp
      transport: stdio
      command: npx
      args: ["-y", "@anthropic/mcp-server-filesystem"]
  triggers:
    - type: file_watch
      paths: ["./knowledge-base"]
      extensions: [".html", ".md"]
      prompt_template: "Knowledge base updated: {path}. Re-index."
    - type: cron
      schedule: "0 9 * * 1"
      prompt: "Generate weekly support coverage report."
  guardrails:
    max_tokens_per_run: 50000
    max_tool_calls: 20
    timeout_seconds: 300
    max_request_limit: 50

Architecture

YAML role files define the agent. The loader parses and validates them, then constructs a PydanticAI agent wired with the configured tools, stores, and audit logger. The runner executes the agent in one of three modes: single-shot, interactive REPL, or trigger-driven daemon. For multi-agent workflows, a flow definition orchestrates multiple agents with inter-agent delegation and health monitoring.