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 reads provider and model metadata from the @earendil-works/pi-ai catalog — currently 35 providers, including 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 AI, Moonshot, Minimax, Z.ai, Kimi, OpenCode, and more. Every static-key scheme in the current catalog is bridged through Comis’s Secret Manager; OAuth and ambient cloud credentials use their provider-specific paths.

Catalog discovery and runtime authentication are separate. A provider added by a future pi-ai release appears automatically in model lists and pickers, but a new credential scheme may still require a Comis update before the provider can make requests. Amazon Bedrock supports a managed bearer, an AWS profile, or the host AWS credential chain. For Google Vertex AI, use GOOGLE_CLOUD_API_KEY with GOOGLE_CLOUD_PROJECT and GOOGLE_CLOUD_LOCATION; ADC-only Vertex authentication is not currently bridged through the daemon’s scrubbed environment.

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 agent-scoped credential 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

With a running daemon, providers list evaluates the same credential chain the runtime uses for the selected agent, including encrypted static secrets and OAuth profiles. Use --agent <id> to select a non-default agent. Without the daemon, the catalog still works, but credentials that are not visible in the CLI process are reported as unknown, never as missing.

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:

• Models view › Catalog tab — full searchable model catalog
• Agents view › Edit agent — provider and model dropdowns

Provider and model discovery is not hardcoded in Comis source. The pi-ai catalog is the source of truth, accessed via getProviders() and getModels(provider). Credential names are an explicit, tested mapping because Comis removes provider secrets from process.env after loading them.

Amazon Bedrock

Set an agent’s provider to amazon-bedrock, then choose one authentication mode:

• Managed Bedrock API key: run comis secrets set AWS_BEARER_TOKEN_BEDROCK. The bearer is resolved from the Secret Manager before ambient AWS credentials and requires bedrock:CallWithBearerToken.
• AWS profile: store the profile with comis secrets set AWS_PROFILE, or select it in the interactive wizard. The AWS SDK resolves that named profile normally.
• Ambient credential chain: configure environment access keys, AWS SSO, web identity, IMDS, or ECS task-role credentials for the Comis process. Nothing needs to be copied into the Comis credential store.

The interactive wizard asks for a region in every mode and stores it as AWS_REGION. Region resolution is: stored AWS_REGION, ambient AWS_REGION, ambient AWS_DEFAULT_REGION, the region in a model ARN, then us-east-1. Pinning the region avoids a misleading access error when the model is enabled somewhere other than the fallback region.

Bedrock accepts several model-id forms:

• Raw foundation-model ids, such as anthropic.claude-* or amazon.nova-*.
• Cross-region inference-profile ids prefixed with us., eu., or global..
• Application inference-profile ARNs.

The calling identity needs bedrock:InvokeModel and bedrock:InvokeModelWithResponseStream. Managed Bedrock API keys additionally need bedrock:CallWithBearerToken. Model availability and access are regional, so an AccessDeniedException or ResourceNotFoundException should be checked against both the resolved region and the configured model id.

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.