Providers

Source: https://pi.dev/docs/latest/providers

Pi supports subscription providers via OAuth and API-key providers via environment variables or ~/.pi/agent/auth.json. Built-in catalogs ship with Pi; configured providers may refresh newer catalogs and cache them in ~/.pi/agent/models-store.json for offline use.

Subscription Providers

Run /login and select: ChatGPT Plus/Pro (Codex), Claude Pro/Max, GitHub Copilot, xAI (Grok/X subscription), OpenRouter, or Radius. /logout clears credentials. Tokens live in auth.json and auto-refresh.

• OpenAI Codex requires ChatGPT Plus or Pro.
• Claude Pro/Max: third-party harness usage draws from Anthropic "extra usage" and is billed per token, not against plan limits.
• GitHub Copilot: Enter for github.com, or enter a GitHub Enterprise Server domain. "Model not supported" is fixed by enabling the model in VS Code Copilot Chat.
• xAI: /login xai → Use a subscription; XAI_API_KEY remains available under Use an API key.
• OpenRouter: /login openrouter → Sign in with OpenRouter runs a PKCE flow that mints a user-controlled API key billed from OpenRouter credits (it does not expire automatically).
• Radius: a dynamic pi-messages gateway. /login radius stores OAuth tokens; the catalog refreshes independently into models-store.json. Custom Radius gateways can be declared in models.json with "oauth": "radius" plus a gateway baseUrl.

API Key Providers

Set an environment variable before startup, or store a key with /login.

Authoritative source: packages/ai/src/env-api-keys.ts in earendil-works/pi-mono.

Auth File

~/.pi/agent/auth.json is created with 0600 permissions and takes priority over environment variables.

{
  "anthropic": { "type": "api_key", "key": "sk-ant-..." },
  "openai": { "type": "api_key", "key": "sk-..." }
}

An API-key credential can carry provider-scoped environment values in an env object. These are used before process environment variables when resolving the credential key, provider/model headers, and provider configuration such as Cloudflare account IDs, Azure settings, Vertex project/location, Bedrock settings, PI_CACHE_RETENTION, and HTTP_PROXY/HTTPS_PROXY:

{
  "cloudflare-ai-gateway": {
    "type": "api_key",
    "key": "$CLOUDFLARE_API_KEY",
    "env": {
      "CLOUDFLARE_API_KEY": "...",
      "CLOUDFLARE_ACCOUNT_ID": "account-id",
      "CLOUDFLARE_GATEWAY_ID": "gateway-id"
    }
  }
}

OAuth credentials are also stored here after /login and managed automatically.

Key Resolution Syntax

{ "type": "api_key", "key": "!op read 'op://vault/item/credential'" }
{ "type": "api_key", "key": "$MY_API_KEY" }
{ "type": "api_key", "key": "${KEY_PREFIX}_${KEY_SUFFIX}" }
{ "type": "api_key", "key": "$$literal-dollar" }
{ "type": "api_key", "key": "$!literal-bang" }

A leading ! executes the whole value as a command and uses stdout (cached for the process lifetime). $VAR/${VAR} interpolate, including inside larger literals; $FOO_BAR is the variable FOO_BAR, so use ${FOO}_BAR when BAR is literal. Missing variables leave the value unresolved. Plain uppercase strings such as MY_API_KEY are literals.

Cloud Providers

Azure OpenAI: AZURE_OPENAI_API_KEY plus AZURE_OPENAI_BASE_URL (*.ai.azure.com, *.cognitiveservices.azure.com, or *.openai.azure.com; root endpoints auto-normalize to /openai/v1) or AZURE_OPENAI_RESOURCE_NAME. Optional AZURE_OPENAI_API_VERSION and AZURE_OPENAI_DEPLOYMENT_NAME_MAP=gpt-4=my-gpt4,....

Amazon Bedrock: /login amazon-bedrock for an API key, or ambient AWS credentials — AWS_PROFILE, IAM keys (AWS_ACCESS_KEY_ID/AWS_SECRET_ACCESS_KEY), or AWS_BEARER_TOKEN_BEDROCK. AWS_REGION defaults to us-east-1. ECS task roles (AWS_CONTAINER_CREDENTIALS_*) and IRSA (AWS_WEB_IDENTITY_TOKEN_FILE) are supported. Prompt caching is automatic for Claude models whose ID contains a recognizable model name; for application inference profiles set AWS_BEDROCK_FORCE_CACHE=1. Proxy support: AWS_ENDPOINT_URL_BEDROCK_RUNTIME, AWS_BEDROCK_SKIP_AUTH=1, AWS_BEDROCK_FORCE_HTTP1=1.

Cloudflare AI Gateway: CLOUDFLARE_API_KEY, CLOUDFLARE_ACCOUNT_ID, CLOUDFLARE_GATEWAY_ID. Routes to OpenAI (/openai, native IDs), Anthropic (/anthropic, native IDs), and Workers AI (Unified API /compat, workers-ai/@cf/... IDs). The Cloudflare token is sent as cf-aig-authorization. Upstream auth modes: Workers AI, unified billing, stored BYOK, or inline BYOK (needs an extra upstream Authorization header). Prefer unified billing or stored BYOK.

Cloudflare Workers AI: CLOUDFLARE_API_KEY + CLOUDFLARE_ACCOUNT_ID. Pi sets x-session-affinity for prefix-caching discounts.

Google Vertex AI: Application Default Credentials (gcloud auth application-default login) plus GOOGLE_CLOUD_PROJECT and GOOGLE_CLOUD_LOCATION, or GOOGLE_APPLICATION_CREDENTIALS pointing at a service-account key.

llama.cpp: /login llama.cpp, manage models with /llama, select with /model — see references/llama-cpp.md.

Custom Providers

Via models.json for anything speaking a supported API (references/models.md); via extensions for custom APIs or OAuth flows (references/custom-provider.md).

Resolution Order

1. CLI --api-key
2. auth.json entry (API key or OAuth token)
3. Environment variable
4. Custom provider keys from models.json