6  Providers

6.1 Overview

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

6.2 Subscriptions

Use /login in interactive mode, then select a provider:

6.2.1 OpenAI Codex

  • Requires ChatGPT Plus or Pro subscription
  • Officially endorsed by OpenAI: Codex for OSS

6.2.2 Claude Pro/Max

Anthropic subscription auth is active for Claude Pro/Max accounts. Third-party harness usage draws from extra usage and is billed per token, not against Claude plan limits.

6.2.3 GitHub Copilot

  • Press Enter for github.com, or enter your GitHub Enterprise Server domain
  • If you get “model not supported”, enable it in VS Code: Copilot Chat → model selector → select model → “Enable”

6.2.4 xAI (Grok/X Subscription)

Run /login xai, then select “Use a subscription”. XAI_API_KEY remains available through “Use an API key”.

6.2.5 OpenRouter

Run /login openrouter, then select “Sign in with OpenRouter” to open the OpenRouter PKCE authorization flow. The authorization creates a user-controlled OpenRouter API key billed from your OpenRouter credits.

Note

On remote/headless machines (e.g., over SSH) the browser cannot reach the loopback callback. Paste the final redirect URL (or the authorization code) into the login prompt instead.

6.2.6 Radius

Radius is a dynamic pi-messages gateway. /login radius stores OAuth tokens in auth.json; the gateway catalog is refreshed independently and cached in models-store.json. Custom Radius gateways can be declared in models.json with "oauth": "radius" and a gateway baseUrl.

6.3 API Keys

6.3.1 Environment Variables

Use /login in interactive mode to store an API key in auth.json, or set credentials via environment variable:

export ANTHROPIC_API_KEY=sk-ant-...
pi

6.3.2 Full Provider Table

Provider Environment Variable auth.json key
Anthropic ANTHROPIC_API_KEY anthropic
Ant Ling ANT_LING_API_KEY ant-ling
Azure OpenAI Responses AZURE_OPENAI_API_KEY azure-openai-responses
OpenAI OPENAI_API_KEY openai
DeepSeek DEEPSEEK_API_KEY deepseek
NVIDIA NIM NVIDIA_API_KEY nvidia
Google Gemini GEMINI_API_KEY google
Amazon Bedrock AWS_BEARER_TOKEN_BEDROCK amazon-bedrock
Mistral MISTRAL_API_KEY mistral
Groq GROQ_API_KEY groq
Cerebras CEREBRAS_API_KEY cerebras
Cloudflare AI Gateway CLOUDFLARE_API_KEY (+ account ID, gateway ID) cloudflare-ai-gateway
Cloudflare Workers AI CLOUDFLARE_API_KEY (+ account ID) cloudflare-workers-ai
xAI XAI_API_KEY xai
OpenRouter OPENROUTER_API_KEY openrouter
Vercel AI Gateway AI_GATEWAY_API_KEY vercel-ai-gateway
ZAI Coding Plan (Global) ZAI_API_KEY zai
ZAI Coding Plan (China) ZAI_CODING_CN_API_KEY zai-coding-cn
OpenCode Zen OPENCODE_API_KEY opencode
OpenCode Go OPENCODE_API_KEY opencode-go
Radius RADIUS_API_KEY radius
Hugging Face HF_TOKEN huggingface
Fireworks FIREWORKS_API_KEY fireworks
Together AI TOGETHER_API_KEY together
Kimi For Coding KIMI_API_KEY kimi-coding
MiniMax MINIMAX_API_KEY minimax
MiniMax (China) MINIMAX_CN_API_KEY minimax-cn
Qwen Token Plan QWEN_TOKEN_PLAN_API_KEY qwen-token-plan
Qwen Token Plan (China) QWEN_TOKEN_PLAN_CN_API_KEY qwen-token-plan-cn
Xiaomi MiMo XIAOMI_API_KEY xiaomi
Xiaomi MiMo Token Plan (China) XIAOMI_TOKEN_PLAN_CN_API_KEY xiaomi-token-plan-cn
Xiaomi MiMo Token Plan (Amsterdam) XIAOMI_TOKEN_PLAN_AMS_API_KEY xiaomi-token-plan-ams
Xiaomi MiMo Token Plan (Singapore) XIAOMI_TOKEN_PLAN_SGP_API_KEY xiaomi-token-plan-sgp

6.4 Auth File

Store credentials in ~/.pi/agent/auth.json:

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

The file is created with 0600 permissions (user read/write only). Auth file credentials take priority over environment variables.

API key credentials can also include provider-scoped environment values used before process environment variables when resolving credentials and provider configuration:

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

6.4.1 Key Resolution

The key field supports command execution, environment interpolation, and literals:

  • Shell command: "!command" executes the whole value as a command and uses stdout (cached for process lifetime)

    { "type": "api_key", "key": "!security find-generic-password -ws 'anthropic'" }
{ "type": "api_key", "key": "!op read 'op://vault/item/credential'" }

  • Environment interpolation: "$ENV_VAR" or "${ENV_VAR}" uses the value of the named variable

    { "type": "api_key", "key": "$MY_ANTHROPIC_KEY" }

  • Escapes: "$$" emits a literal $; "$!" emits a literal !

  • Literal value: Used directly. Plain uppercase strings such as MY_API_KEY are literals; use $MY_API_KEY for environment variables

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

6.5 Cloud Providers

6.5.1 Azure OpenAI

export AZURE_OPENAI_API_KEY=...
export AZURE_OPENAI_BASE_URL=https://your-resource.ai.azure.com
# Or use resource name instead of base URL
export AZURE_OPENAI_RESOURCE_NAME=your-resource
# Optional
export AZURE_OPENAI_API_VERSION=2024-02-01
export AZURE_OPENAI_DEPLOYMENT_NAME_MAP=gpt-4=my-gpt4,gpt-4o=my-gpt4o

6.5.2 Amazon Bedrock

# Option 1: AWS Profile
export AWS_PROFILE=your-profile

# Option 2: IAM Keys
export AWS_ACCESS_KEY_ID=AKIA...
export AWS_SECRET_ACCESS_KEY=...

# Option 3: Bearer Token
export AWS_BEARER_TOKEN_BEDROCK=...

# Optional region
export AWS_REGION=us-west-2

Also supports ECS task roles and IRSA. Prompt caching is enabled automatically for Claude models whose ID contains a recognizable model name.

6.5.3 Cloudflare AI Gateway

export CLOUDFLARE_API_KEY=...
export CLOUDFLARE_ACCOUNT_ID=...
export CLOUDFLARE_GATEWAY_ID=...

Routes to OpenAI, Anthropic, and Workers AI through Cloudflare AI Gateway.

6.5.4 Cloudflare Workers AI

export CLOUDFLARE_API_KEY=...
export CLOUDFLARE_ACCOUNT_ID=...

Pi automatically sets x-session-affinity for prefix caching discounts.

6.5.5 Google Vertex AI

gcloud auth application-default login
export GOOGLE_CLOUD_PROJECT=your-project
export GOOGLE_CLOUD_LOCATION=us-central1

Or set GOOGLE_APPLICATION_CREDENTIALS to a service account key file.

6.5.6 llama.cpp

Pi supports the llama.cpp router server. Configure it with /login llama.cpp, manage loaded models with /llama, and select a loaded model with /model.

6.6 Custom Providers

  • Via models.json: Add Ollama, LM Studio, vLLM, or any provider that speaks a supported API. See the Custom Models chapter.
  • Via extensions: For providers that need custom API implementations or OAuth flows, create an extension. See the Custom Providers chapter.

6.7 Resolution Order

When resolving credentials for a provider:

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

Auth file credentials take priority over environment variables. If you have both set, the auth file value wins.