Skip to main content
Polpo is fully provider-agnostic. Every agent on the team can use a different model from a different provider, Polpo itself runs on its own model, and you can configure fallback chains, cost limits, and custom endpoints — all from a single config file. Under the hood, Polpo uses the @mariozechner/pi-ai library which provides a unified interface to 22+ LLM providers and hundreds of models, with built-in cost tracking, streaming, and OAuth support.

​
Model Format

Models are specified as a provider:model string: 
{
  "name": "architect",
  "model": "anthropic:claude-sonnet-4-6"
}
The format is always provider:model-id, where provider is one of the supported providers and model-id is the model identifier within that provider.

​
Auto-Inference

If you omit the provider prefix, Polpo infers it from the model name: 
{
  "model": "claude-sonnet-4-6"
}
The inference engine matches on known prefixes:
PrefixInferred Provider
claude-anthropic
gpt-, o1-, o3-, o4-, chatgpt-, codex-openai
gemini-google
mistral-, codestral-, devstral-mistral
llama-, llama3groq
grok-xai
deepseek-openrouter
gpt-oss-cerebras
glm-zai
minimax-minimax
kimi-kimi-coding
amazon., us., eu.amazon-bedrock
hf:huggingface
big-pickleopencode
If the model name doesn’t match any known prefix, you must specify the provider explicitly.
For clarity and to avoid ambiguity, always use the explicit provider:model format in production configurations. Auto-inference is a convenience for quick prototyping.

​
Model Resolution Order

Polpo resolves which model to use through a layered system. Each layer can override the one below it.

​
For Agents

  1. Agent’s model field in the config
  2. POLPO_MODEL environment variable
{
  "agents": [
    {
      "name": "coder",
      "model": "anthropic:claude-sonnet-4-6"
    }
  ]
}

​
For Polpo Itself

Polpo uses its own model for conversations (via /v1/chat/completions and TUI chat), plan generation, question detection, deadlock resolution, and escalation decisions:
  1. settings.orchestratorModel in polpo.json
  2. POLPO_MODEL environment variable
{
  "settings": {
    "orchestratorModel": "anthropic:claude-sonnet-4-6"
  }
}
The orchestrator model can also be a ModelConfig with fallbacks: 
{
  "settings": {
    "orchestratorModel": {
      "primary": "anthropic:claude-sonnet-4-6",
      "fallbacks": ["openai:gpt-4o", "google:gemini-2.5-pro"]
    }
  }
}

​
For the Judge

The assessment system’s LLM-as-Judge uses a separate model that can be overridden independently: 
POLPO_JUDGE_MODEL=anthropic:claude-sonnet-4-6
When not set, it uses the same resolution chain as the orchestrator model.

​
For Escalation

When a task fails and escalates, the model can be upgraded for the retry: 
{
  "retryPolicy": {
    "escalateAfter": 2,
    "fallbackAgent": "senior-dev",
    "escalateModel": "anthropic:claude-opus-4-6"
  }
}

​
API Key Resolution

For each provider, Polpo resolves the API key with this priority:
  1. providers config in polpo.json (supports ${ENV_VAR} references)
  2. Standard environment variable for the provider (e.g. ANTHROPIC_API_KEY)
  3. Stored OAuth profiles from polpo auth login (with automatic token refresh)
{
  "providers": {
    "anthropic": "${ANTHROPIC_API_KEY}",
    "openai": {
      "apiKey": "${OPENAI_API_KEY}"
    }
  }
}
The shorthand "anthropic": "sk-..." sets just the API key. The object form adds baseUrl for custom endpoints.

​
OAuth Authentication

For 5 providers (Anthropic, OpenAI Codex, GitHub Copilot, Google Gemini CLI, Google Antigravity), you can use your existing subscription instead of provisioning a separate API key: 
polpo auth login anthropic     # Use your Claude Pro/Max subscription
polpo auth login github-copilot # Use your Copilot subscription
polpo auth status               # View stored credentials
OAuth tokens are stored securely in ~/.polpo/auth-profiles.json with automatic refresh. When you have multiple profiles for the same provider (e.g., personal + work accounts), Polpo rotates between them automatically — prioritizing OAuth over API keys and distributing usage evenly.

Full Authentication Guide

OAuth setup, profile rotation, billing disable, session stickiness, and the /model command.
API key validation happens at startup. Polpo checks that every model referenced by an agent, the orchestrator, and the judge has a corresponding API key or OAuth profile. Missing keys emit a warning but don’t block startup.

​
Mixing Providers

Each agent can use a completely different provider. A single plan can mix Anthropic, OpenAI, Google, and local models: 
{
  "providers": {
    "anthropic": "${ANTHROPIC_API_KEY}",
    "openai": "${OPENAI_API_KEY}",
    "google": "${GEMINI_API_KEY}",
    "ollama": {
      "baseUrl": "http://localhost:11434/v1",
      "api": "openai-completions"
    }
  },
  "agents": [
    {
      "name": "architect",
      "model": "anthropic:claude-opus-4-6",
      "role": "System design and architecture"
    },
    {
      "name": "coder",
      "model": "anthropic:claude-sonnet-4-6",
      "role": "Implementation"
    },
    {
      "name": "reviewer",
      "model": "openai:o3",
      "role": "Code review with deep reasoning"
    },
    {
      "name": "fast-worker",
      "model": "groq:llama-3.3-70b-versatile",
      "role": "Quick tasks, boilerplate"
    },
    {
      "name": "local-helper",
      "model": "ollama:qwen2.5-coder:32b",
      "role": "Offline tasks, no API cost"
    }
  ],
  "settings": {
    "orchestratorModel": "google:gemini-2.5-pro"
  }
}

​
Default Model

When no model is configured, Polpo will prompt you to configure one via polpo setup. Set a model on your agents or use the POLPO_MODEL env var.