Providers

Pi supports subscription-based providers via OAuth and API key providers via environment variables or 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.

Subscriptions
API Keys
Auth File
Cloud Providers
llama.cpp
Custom Providers
Resolution Order

Subscriptions

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

ChatGPT Plus/Pro (Codex)
Claude Pro/Max
GitHub Copilot
xAI (Grok/X subscription)
OpenRouter (OAuth-minted API key billed from OpenRouter credits)
Radius

Use /logout to clear credentials. Tokens are stored in ~/.pi/agent/auth.json and auto-refresh when expired. OpenRouter instead mints a user-controlled API key that does not expire automatically.

OpenAI Codex

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

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.

Claude SDK OAuth

The claude-sdk-oauth provider routes LLM calls through the official Claude Agent SDK - it spawns the real Claude Code engine - while senpi executes every tool itself. Subscription usage flows through Anthropic's official Claude Code surface.

Run /login claude-sdk-oauth to sign in with your Claude Pro/Max subscription (PKCE, same OAuth client as the Claude Code CLI). An existing Anthropic OAuth credential is offered as an import.
Multiple accounts: each /login claude-sdk-oauth adds another named account. CLAUDE_CODE_OAUTH_TOKEN (and _2.._N) are honored as read-only env accounts. /claude-account lists, adds, removes, and pins accounts; --claude-account <name> pins one for the session; claudeSdkOauthProvider.pinnedAccount pins one in settings.
Session affinity: one senpi session sticks to one account (rendezvous hashing), which keeps Anthropic's prompt cache warm - accounts never rotate mid-session except on automatic failover. Rate limits and auth errors block the account (with cooldown) and retry on the next account, before any visible output; once output has started, the error surfaces instead of replaying.
Default lane: ambient - with no tokenInjection setting the provider inherits the environment like the upstream extension (Claude Code CLI login or ANTHROPIC_API_KEY). Managed lanes (oauth-slots, config-dir) are opt-in via one settings line until the live subscription spike proves a managed default.
Settings (claudeSdkOauthProvider):
- systemPromptMode — controls how the system prompt is delivered. full (default) sends senpi's composed system prompt verbatim; the lane no longer rebuilds from the SDK claude_code preset, so all prompt regions (project rules, response-language instructions, etc.) reach the model. preset-append is the previous behaviour (deprecated, kept for one release; emits a one-time warning). override loads the system prompt from a file (systemPromptFile). The legacy appendSystemPrompt key still works: false → preset-append, true/unset → full; setting both keys makes systemPromptMode win and warns.
- In full and override modes, settingSources defaults to [] on every lane because senpi's prompt already carries project context — loading the SDK's own CLAUDE.md would double-inject it. The CLI always prepends its own "You are a Claude agent, built on Anthropic's Claude Agent SDK." block, which senpi cannot suppress; full means the prompt is delivered intact, not that it is the only system-prompt text.
- settingSources (filesystem settings load only in the ambient lane, so they cannot override your selected account), strictMcpConfig, pinnedAccount, tokenInjection (oauth-slots | config-dir | ambient), resumeMode (auto default | off restores per-turn sessions), systemPromptFile.
To prevent the Claude Code provider from loading on startup, disable the builtin by id in global ~/.senpi/agent/settings.json or project .senpi/settings.json:
```
{
  "disabledBuiltinExtensions": ["claude-sdk-oauth"]
}
```
Restart senpi after changing this setting. Project settings override global settings, so a project-level disabledBuiltinExtensions list must also include claude-sdk-oauth to preserve a global opt-out. The setting prevents the provider extension from loading while leaving unrelated built-ins enabled. Remove the id (or remove the setting) to enable it again.

Environment overrides (precedence: env > project settings > global settings > default; no new CLI flags):

Variable	Purpose
`SENPI_CLAUDE_SDK_OAUTH_SYSTEM_PROMPT_MODE`	`full` \| `preset-append` \| `override`
`SENPI_CLAUDE_SDK_OAUTH_SYSTEM_PROMPT_FILE`	Path to the system prompt file (used with `override` mode)
`SENPI_CLAUDE_SDK_OAUTH_RESUME`	`auto` (default) \| `off` — disables session reuse, restoring per-turn SDK queries
`SENPI_CLAUDE_SDK_OAUTH_TOKEN_INJECTION`	`oauth-slots` \| `config-dir` \| `ambient`
`SENPI_CLAUDE_SDK_OAUTH_SETTING_SOURCES`	Overrides `settingSources`
`SENPI_CLAUDE_SDK_OAUTH_PINNED_ACCOUNT`	Overrides `pinnedAccount`

Every SENPI_* variable is stripped from the Claude Code subprocess environment on all three lanes; other inherited variables are preserved.

Session reuse. By default one long-lived SDK query spans the entire senpi session instead of a fresh one per turn, so conversations continue with only the new delta sent. Reuse fails closed to a fresh session on compaction, branch/fork navigation, account failover, an aborted turn, or any configuration change. Idle sessions retire after 30 minutes (max 32 resident); a session with an in-flight turn is never evicted. After a senpi process restart the lane always starts fresh. Set resumeMode: "off" (or SENPI_CLAUDE_SDK_OAUTH_RESUME=off) to restore the old per-turn behaviour. Accepted values are "auto" (default) and "off"; any other value is silently ignored.
Account state is exposed to desktop/automation clients: RPC get_provider_accounts, account_pin, account_remove and the auth_accounts_changed / account_failover events, mirrored through the app-server protocol. Token material is never included.

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"

xAI (Grok/X subscription)

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

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
OPENROUTER_API_KEY remains available through Use an API key

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.

API Keys

Environment Variables or Auth File

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

export ANTHROPIC_API_KEY=sk-ant-...
pi

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` (+ `CLOUDFLARE_ACCOUNT_ID`, `CLOUDFLARE_GATEWAY_ID`)	`cloudflare-ai-gateway`
Cloudflare Workers AI	`CLOUDFLARE_API_KEY` (+ `CLOUDFLARE_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`
Alibaba Token Plan (ap-southeast-1)	`ALIBABA_TOKEN_PLAN_API_KEY`	`alibaba-token-plan`

Reference for environment variables and auth.json keys: const envMap in packages/ai/src/env-api-keys.ts.

Auth File

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

{
  "anthropic": { "type": "api_key", "key": "sk-ant-..." },
  "ant-ling": { "type": "api_key", "key": "..." },
  "openai": { "type": "api_key", "key": "sk-..." },
  "deepseek": { "type": "api_key", "key": "sk-..." },
  "nvidia": { "type": "api_key", "key": "nvapi-..." },
  "google": { "type": "api_key", "key": "..." },
  "opencode": { "type": "api_key", "key": "..." },
  "opencode-go": { "type": "api_key", "key": "..." },
  "together": { "type": "api_key", "key": "..." },
  "qwen-token-plan":  { "type": "api_key", "key": "sk-sp-..." },
  "qwen-token-plan-cn": { "type": "api_key", "key": "sk-sp-..." },
  "xiaomi": { "type": "api_key", "key": "..." },
  "xiaomi-token-plan-cn":  { "type": "api_key", "key": "..." },
  "xiaomi-token-plan-ams": { "type": "api_key", "key": "..." },
  "xiaomi-token-plan-sgp": { "type": "api_key", "key": "..." },
  "alibaba-token-plan": { "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. These values are used before process environment variables when resolving the credential key, provider/model headers, and provider configuration such as Cloudflare account IDs, Azure OpenAI 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"
    }
  }
}

Use this when pi should use different provider settings than the project shell environment.

Key Resolution

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

Shell command: "!command" at the start 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. Interpolation works inside larger literals.
```
{ "type": "api_key", "key": "$MY_ANTHROPIC_KEY" }
{ "type": "api_key", "key": "${KEY_PREFIX}_${KEY_SUFFIX}" }
```
$FOO_BAR is the variable FOO_BAR; use ${FOO}_BAR when BAR is literal text. Missing environment variables make the value unresolved.

Escapes: "$$" emits a literal "$"; "$!" emits a literal "!" without triggering command execution.

{ "type": "api_key", "key": "$$literal-dollar-prefix" }
{ "type": "api_key", "key": "$!literal-bang-prefix" }

Literal value: Used directly. Plain uppercase strings such as MY_API_KEY are literals; use $MY_API_KEY for environment variables.
```
{ "type": "api_key", "key": "sk-ant-..." }
{ "type": "api_key", "key": "public" }
```

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

Cloud Providers

Azure OpenAI

export AZURE_OPENAI_API_KEY=...
export AZURE_OPENAI_BASE_URL=https://your-resource.ai.azure.com
# also supported: https://your-resource.cognitiveservices.azure.com
# also supported: https://your-resource.openai.azure.com
# root endpoints are auto-normalized to /openai/v1
# 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

Amazon Bedrock

Use /login amazon-bedrock to store a Bedrock API key, or configure one of the ambient AWS credential sources below:

# 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 (defaults to us-east-1)
export AWS_REGION=us-west-2

Also supports ECS task roles (AWS_CONTAINER_CREDENTIALS_*) and IRSA (AWS_WEB_IDENTITY_TOKEN_FILE).

pi --provider amazon-bedrock --model us.anthropic.claude-sonnet-4-20250514-v1:0

Prompt caching is enabled automatically for Claude models whose ID contains a recognizable model name (base models and system-defined inference profiles). For application inference profiles (whose ARNs don't contain the model name), set AWS_BEDROCK_FORCE_CACHE=1 to enable cache points:

export AWS_BEDROCK_FORCE_CACHE=1
pi --provider amazon-bedrock --model arn:aws:bedrock:us-east-1:123456789012:application-inference-profile/abc123

If you are connecting to a Bedrock API proxy, the following environment variables can be used:

# Set the URL for the Bedrock proxy (standard AWS SDK env var)
export AWS_ENDPOINT_URL_BEDROCK_RUNTIME=https://my.corp.proxy/bedrock

# Set if your proxy does not require authentication
export AWS_BEDROCK_SKIP_AUTH=1

# Set if your proxy only supports HTTP/1.1
export AWS_BEDROCK_FORCE_HTTP1=1

Cloudflare AI Gateway

CLOUDFLARE_API_KEY can be set via /login. The account ID and gateway slug can be set as environment variables or in the API key credential's env object in auth.json.

export CLOUDFLARE_API_KEY=...           # or use /login
export CLOUDFLARE_ACCOUNT_ID=...
export CLOUDFLARE_GATEWAY_ID=...        # create at dash.cloudflare.com → AI → AI Gateway
pi --provider cloudflare-ai-gateway --model "claude-sonnet-4-5"

Routes to OpenAI, Anthropic, and Workers AI through Cloudflare AI Gateway. Workers AI uses the Unified API (/compat) and prefixed model IDs (workers-ai/@cf/...). OpenAI uses the OpenAI passthrough route (/openai) with native OpenAI model IDs such as gpt-5.1. Anthropic uses the Anthropic passthrough route (/anthropic) with native Anthropic model IDs such as claude-sonnet-4-5.

AI Gateway authentication uses CLOUDFLARE_API_KEY as cf-aig-authorization. Upstream authentication can be one of:

Mode	Request auth	Upstream auth
Workers AI	Cloudflare token only	Cloudflare-native
Unified billing	Cloudflare token only	Cloudflare handles upstream auth and deducts credits
Stored BYOK	Cloudflare token only	Cloudflare injects provider keys stored in the AI Gateway dashboard
Inline BYOK	Cloudflare token plus upstream `Authorization` header	The request supplies the upstream provider key

For normal pi usage, prefer unified billing or stored BYOK. Inline BYOK requires configuring an additional upstream Authorization header for the Cloudflare AI Gateway provider, for example via a models.json provider/model override.

Cloudflare Workers AI

CLOUDFLARE_API_KEY can be set via /login. CLOUDFLARE_ACCOUNT_ID can be set as an environment variable or in the API key credential's env object in auth.json.

export CLOUDFLARE_API_KEY=...           # or use /login
export CLOUDFLARE_ACCOUNT_ID=...
pi --provider cloudflare-workers-ai --model "@cf/moonshotai/kimi-k2.6"

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

Google Vertex AI

Uses Application Default Credentials:

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.

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.

See llama.cpp for server setup, model directory layout, environment variables, and command usage.

Custom Providers

Via models.json: Add Ollama, LM Studio, vLLM, or any provider that speaks a supported API (OpenAI Completions, OpenAI Responses, Anthropic Messages, Google Generative AI). See models.md.

Via extensions: For providers that need custom API implementations or OAuth flows, create an extension. See custom-provider.md and examples/extensions/custom-provider-gitlab-duo.

Resolution Order

When resolving credentials for a provider:

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

Navigation Menu

Providers

Table of Contents

Subscriptions

OpenAI Codex

Claude Pro/Max

Claude SDK OAuth

GitHub Copilot

xAI (Grok/X subscription)

OpenRouter

Radius

API Keys

Environment Variables or Auth File

Auth File

Key Resolution

Cloud Providers

Azure OpenAI

Amazon Bedrock

Cloudflare AI Gateway

Cloudflare Workers AI

Google Vertex AI

llama.cpp

Custom Providers

Resolution Order

FilesExpand file tree

providers.md

Latest commit

History

providers.md

File metadata and controls

Providers

Table of Contents

Subscriptions

OpenAI Codex

Claude Pro/Max

Claude SDK OAuth

GitHub Copilot

xAI (Grok/X subscription)

OpenRouter

Radius

API Keys

Environment Variables or Auth File

Auth File

Key Resolution

Cloud Providers

Azure OpenAI

Amazon Bedrock

Cloudflare AI Gateway

Cloudflare Workers AI

Google Vertex AI

llama.cpp

Custom Providers

Resolution Order