Models

Configuring AI providers, model selection, and automatic failover

What it does. Picks which AI model answers each message — globally, per-agent, or per-task — and falls back to a backup model if the primary provider has a hiccup.

Who it is for. Anyone setting up an agent. The plain-language section covers picking a default; the reference section covers per-agent overrides, fallback chains, and key rotation.

Comis ships with native support for every provider in the @earendil-works/pi-ai catalog — currently 27 hosted providers (Anthropic, OpenAI, Google, Mistral, Groq, OpenRouter, DeepSeek, xAI, Cerebras, Amazon Bedrock, Azure OpenAI Responses, Vercel AI Gateway, Cloudflare AI Gateway / Workers AI, GitHub Copilot, Hugging Face, Fireworks, Together (via OpenRouter), Moonshot, Minimax, Z.ai, Kimi, OpenCode, and more). The catalog is queried at runtime — adding a new provider to pi-ai automatically lights it up across the daemon, web wizard, CLI wizard, and comis models list with zero comis code changes.

Plus you can register custom OpenAI-compatible endpoints (any HTTP service that speaks the OpenAI chat-completions API) for proxies and self-hosted gateways.

You can set a default model for all agents, override it per agent, and configure automatic failover so your agents keep working even if one provider goes down.

Discovering available providers and models

The catalog is dynamic. Two CLI commands surface it:

# List all providers with model counts and key status
comis providers list

# Browse the full model catalog
comis models list

# Filter to one provider
comis models list --provider openrouter

# Machine-readable
comis providers list --format json
comis models list --format json

Each command tries the daemon’s models.list_providers / models.list RPC first, and falls back to the local pi-ai static catalog when the daemon isn’t running (so the wizard still works pre-init).

In the web dashboard, the same catalog drives:

• Setup Wizard › Provider step — provider grid populated from models.list_providers
• Setup Wizard › Model dropdown — per-provider model list from models.list
• Models view › Catalog tab — full searchable model catalog
• Agents view › Edit agent — provider and model dropdowns

There is no hardcoded provider/model list in comis source. The pi-ai catalog is the single source of truth, accessed via getProviders() and getModels(provider) from @earendil-works/pi-ai.

Custom providers (proxies and self-hosted)

For any endpoint not in the pi-ai catalog — your own gateway, a private deployment, an OpenAI-compatible proxy — register a custom provider entry under providers.entries.<id> with type: "openai" and your custom baseUrl. The daemon’s built-in-provider guard rejects redundant entries that try to re-create a built-in provider with the catalog’s default URL (those should use the built-in path: env_set + agent provider/model directly).

Choosing a model

You set a default AI model globally, and every agent uses that model unless you override it. The default is Claude Sonnet from Anthropic, but you can switch to any supported provider at any time.

You can also create model aliases — friendly shorthand names that map to specific provider and model combinations. Instead of typing a long model ID every time, you can just use a name like claude or gpt4.

Three levels of configuration

Comis gives you three levels of control over which model your agents use. Each level overrides the one above it:

Level 1: Global defaults

Set the default model and provider for all agents. This is the simplest way to get started — configure it once and every agent uses it.

Option	Type	Default	What it does
models.defaultModel	string	"" (falls back to claude-sonnet-4-5-20250929)	Default model for all agents
models.defaultProvider	string	"" (falls back to anthropic)	Default provider for all agents
models.aliases	array	[]	Friendly names for model/provider pairs
models.scanOnStartup	boolean	false	Scan providers for available models on startup

~/.comis/config.yaml

models:
  defaultModel: "claude-sonnet-4-5-20250929"
  defaultProvider: "anthropic"
  aliases:
    - alias: "claude"
      provider: "anthropic"
      modelId: "claude-sonnet-4-5-20250929"
    - alias: "gpt4"
      provider: "openai"
      modelId: "gpt-4o"
    - alias: "gemini"
      provider: "google"
      modelId: "gemini-2.0-flash"

With aliases configured, you can reference models by their short name anywhere in the configuration. For example, setting an agent’s model to claude would use anthropic/claude-sonnet-4-5-20250929.

Level 2: Per-agent override

Override the global default for specific agents. This is useful when different agents have different needs — your main conversational agent might use Claude, while a code-focused agent uses GPT-4o, a fast triage agent uses Groq, and a local-only agent uses Ollama.

Option	Type	Default	What it does
agents.*.model	string	"default"	Model for this agent (or "default" to use global)
agents.*.provider	string	"default"	Provider for this agent (or "default" to use global)

~/.comis/config.yaml

models:
  defaultModel: "claude-sonnet-4-5-20250929"
  defaultProvider: "anthropic"

agents:
  default:
    model: "default"                       # Global default (Claude Sonnet)
    provider: "default"

  code-helper:
    model: "gpt-4o"                        # Long-context coding agent
    provider: "openai"

  quick-lookup:
    model: "gemini-2.5-flash"              # Speed for quick answers
    provider: "google"

  triage:
    model: "llama-3.3-70b"                 # Cerebras for sub-second classification
    provider: "cerebras"

  private-notes:
    model: "llama3.1:8b"                   # Local Ollama, no key required
    provider: "ollama"

A single Comis instance can mix all five at once — each agent picks independently, and key resolution is handled by the Secret Manager.

Level 3: Per-task routes

For advanced use cases, you can route specific tasks to different models. For example, use a cheaper model for summarization and your primary model for everything else.

~/.comis/config.yaml

agents:
  default:
    model: "claude-sonnet-4-5-20250929"
    provider: "anthropic"
    modelRoutes:
      summarization: "gemini-2.0-flash"
      classification: "gpt-4o-mini"

Task routes are optional and most users do not need them. They are available for specific optimization scenarios where different tasks benefit from different models.

Automatic failover

What happens when your AI provider goes down or returns errors? Comis can automatically try backup models so your agents keep working.

Fallback models

You can specify an ordered list of backup models. If the primary model fails, Comis tries the next one in the list, and so on until one succeeds or all options are exhausted.

Auth profiles

You can configure multiple API keys per provider. Comis rotates between them automatically, which is useful for:

• Rate limit management — If one key hits its rate limit, Comis switches to another.
• Redundancy — If one key is revoked or expired, others keep working.

Comis supports three key selection strategies that it manages internally: explicit ordering, round-robin rotation, and last-known-good preference.

Cooldown behavior

After a model fails, Comis waits before trying it again. The wait time increases with each failure using exponential backoff:

• First failure: 1 minute cooldown
• Second failure: 5 minutes
• Third failure: 25 minutes
• Maximum: 1 hour cap

This prevents your agent from hammering a broken provider and racking up error counts.

Failover configuration

Option	Type	Default	What it does
modelFailover.fallbackModels	array	[]	Ordered list of backup models to try
modelFailover.authProfiles	array	[]	API key profiles for rotation
modelFailover.allowedModels	array	[]	Model allowlist (empty = allow all)
modelFailover.maxAttempts	number	6	Maximum total attempts across all models and keys
modelFailover.cooldownInitialMs	number	60000	Initial cooldown after failure (1 minute)
modelFailover.cooldownMultiplier	number	5	Cooldown multiplier for exponential backoff
modelFailover.cooldownCapMs	number	3600000	Maximum cooldown duration (1 hour)

~/.comis/config.yaml

agents:
  default:
    model: "claude-sonnet-4-5-20250929"
    provider: "anthropic"

    modelFailover:
      fallbackModels:
        - provider: "openai"
          modelId: "gpt-4o"
        - provider: "google"
          modelId: "gemini-2.0-flash"

      authProfiles:
        - keyName: "ANTHROPIC_API_KEY"
          provider: "anthropic"
        - keyName: "ANTHROPIC_API_KEY_2"
          provider: "anthropic"
        - keyName: "OPENAI_API_KEY"
          provider: "openai"

      maxAttempts: 6
      cooldownInitialMs: 60000
      cooldownMultiplier: 5
      cooldownCapMs: 3600000

In this example, if the primary Claude model fails, Comis tries GPT-4o next, then Gemini Flash. It also has two Anthropic API keys and rotates between them if one hits a rate limit.

Model capability matrix

Different model families support different features. The capability matrix governs how Comis builds the request body for each provider.

Family	Context window (typical)	Prompt cache	Tool use	Vision	Reasoning blocks
Anthropic Claude (Sonnet/Opus/Haiku 4.x)	200K	Ephemeral 5m / 1h	Yes	Yes	Yes
OpenAI GPT-4o family	128K	Implicit (provider-managed)	Yes	Yes	No
OpenAI GPT-5.4 family	200K+	Implicit	Yes	Yes	Optional
Google Gemini 2.5 / 3	1M	Explicit CachedContent	Yes	Yes	No
Mistral Large / Codestral	128K	None	Yes (strict ID mode)	Pixtral only	No
Groq (Llama / Mixtral)	128K	None	Yes	No	No
Ollama (local)	Varies by model	None	If model supports	If model supports	If model supports
OpenRouter	Per upstream	Per upstream	Per upstream	Per upstream	Per upstream
Cerebras (Llama)	128K	None	Yes	No	No
xAI Grok	128K	None	Yes	Limited	No
DeepSeek	64K-128K	None	Yes	No	No

The exact context window per concrete model is resolved at runtime from the pi-ai catalog (getModels(provider)). To see the live catalog: comis models list (or filter to one provider with comis models list --provider <id>). The capability matrix above is a reference summary — concrete per-model capabilities (cost, max tokens, vision support, reasoning) are queryable directly via comis models list --format json or the models.list RPC.

Key rotation

You can configure multiple API keys per provider to spread usage across accounts or handle key expiration gracefully. When a key hits a rate limit or returns an authentication error, Comis automatically switches to the next available key.

Keys are managed through the Secret Manager. Each authProfile entry maps a secret name to a provider, and Comis handles the rotation logic automatically.

Start with a single model and no failover. Add fallback models and key rotation only when you need higher availability or are hitting rate limits regularly.

Safety

Budget protection, circuit breakers, and cost controls.

Routing

How messages are directed to specific agents.