mirror of
https://github.com/badlogic/pi-mono.git
synced 2026-11-05 23:37:25 +00:00
30a1d1849d
Entries of only +name/-name modify the inherited tool selection, so "defaultTools": ["+codemode"] enables codemode without repeating the defaults. Project entries layer on top of user settings. Document how to enable codemode without MCP and how to use classifier models from it.
188 lines
6.2 KiB
Markdown
188 lines
6.2 KiB
Markdown
# Provider Authentication
|
|
|
|
Most hosted providers support one or both of these authentication methods:
|
|
|
|
- Sign in through a browser or device flow backed by OAuth.
|
|
- Provide an API key.
|
|
|
|
Use `/login [provider]` to see the methods supported by a provider. Amazon Bedrock and Google Vertex AI can also use ambient cloud credentials.
|
|
|
|
## Authenticate interactively
|
|
|
|
Run `/login` and select a provider. Pi guides you through its OAuth or API-key flow and saves the resulting credential in [`auth.json`](configuration.md#agent-directory).
|
|
|
|
On a remote or headless machine, an OAuth callback may not reach the local process. When prompted, paste the final redirect URL or authorization code back into Pi.
|
|
|
|
Run `/logout` and select a provider to remove its stored credential. This does not unset environment variables, remove authentication from `models.json`, or revoke the credential at the provider.
|
|
|
|
`auth.json` can contain API keys and OAuth tokens. Keep it private and do not commit it.
|
|
|
|
Radius authentication uses its gateway catalog and caches refreshed model metadata for later offline startup. A custom Radius gateway configured in `models.json` uses its own catalog rather than inheriting the public `radius.pi.dev` catalog.
|
|
|
|
## Use an API key from the environment
|
|
|
|
Environment variables are useful in CI and anywhere Pi should not store the key. Set the variable before starting Pi:
|
|
|
|
```bash
|
|
export ANTHROPIC_API_KEY=sk-ant-...
|
|
pi
|
|
```
|
|
|
|
This table covers providers with a single primary API-key variable. Providers that need additional configuration or support ambient credentials are covered under [Cloud providers](#cloud-providers).
|
|
|
|
| Provider | Environment variable |
|
|
|---|---|
|
|
| Anthropic | `ANTHROPIC_API_KEY` |
|
|
| Ant Ling | `ANT_LING_API_KEY` |
|
|
| OpenAI | `OPENAI_API_KEY` |
|
|
| DeepSeek | `DEEPSEEK_API_KEY` |
|
|
| NVIDIA NIM | `NVIDIA_API_KEY` |
|
|
| Google Gemini | `GEMINI_API_KEY` |
|
|
| GitHub Copilot | `COPILOT_GITHUB_TOKEN` |
|
|
| Mistral | `MISTRAL_API_KEY` |
|
|
| Groq | `GROQ_API_KEY` |
|
|
| Cerebras | `CEREBRAS_API_KEY` |
|
|
| xAI | `XAI_API_KEY` |
|
|
| OpenRouter | `OPENROUTER_API_KEY` |
|
|
| Vercel AI Gateway | `AI_GATEWAY_API_KEY` |
|
|
| ZAI Coding Plan (Global) | `ZAI_API_KEY` |
|
|
| ZAI Coding Plan (China) | `ZAI_CODING_CN_API_KEY` |
|
|
| OpenCode Zen and Go | `OPENCODE_API_KEY` |
|
|
| Radius | `RADIUS_API_KEY` |
|
|
| TypeSafe ([classifier models](models.md#use-classifier-models)) | `TYPESAFE_API_KEY` |
|
|
| Hugging Face | `HF_TOKEN` |
|
|
| Fireworks | `FIREWORKS_API_KEY` |
|
|
| Together AI | `TOGETHER_API_KEY` |
|
|
| Baseten | `BASETEN_API_KEY` |
|
|
| Kimi For Coding | `KIMI_API_KEY` |
|
|
| Meta | `META_API_KEY` |
|
|
| MiniMax | `MINIMAX_API_KEY` |
|
|
| MiniMax (China) | `MINIMAX_CN_API_KEY` |
|
|
| Moonshot AI (Global and China) | `MOONSHOT_API_KEY` |
|
|
| Qwen Token Plan and Individual | `QWEN_TOKEN_PLAN_API_KEY` |
|
|
| Qwen Token Plan (China) | `QWEN_TOKEN_PLAN_CN_API_KEY` |
|
|
| Xiaomi MiMo | `XIAOMI_API_KEY` |
|
|
| Xiaomi MiMo Token Plan (China) | `XIAOMI_TOKEN_PLAN_CN_API_KEY` |
|
|
| Xiaomi MiMo Token Plan (Amsterdam) | `XIAOMI_TOKEN_PLAN_AMS_API_KEY` |
|
|
| Xiaomi MiMo Token Plan (Singapore) | `XIAOMI_TOKEN_PLAN_SGP_API_KEY` |
|
|
|
|
Anthropic also recognizes `ANTHROPIC_OAUTH_TOKEN` as an API credential and `ANTHROPIC_AUTH_TOKEN` as bearer authentication.
|
|
|
|
## Load an API key from a command
|
|
|
|
To use a secret manager without writing the resolved key to disk, set a provider's `key` in `auth.json` to a command prefixed with `!`:
|
|
|
|
```json
|
|
{
|
|
"anthropic": {
|
|
"type": "api_key",
|
|
"key": "!security find-generic-password -ws 'anthropic'"
|
|
}
|
|
}
|
|
```
|
|
|
|
Pi runs the command when the key is first needed and caches its standard output for the process lifetime. Empty output, a timeout, or a nonzero exit leaves the key unresolved until Pi restarts.
|
|
|
|
## Cloud Providers
|
|
|
|
The providers below need additional settings or can use credentials supplied by their cloud platform.
|
|
|
|
A stored API-key credential can include an `env` object. Its values take priority over the process environment for that provider:
|
|
|
|
```json
|
|
{
|
|
"cloudflare-workers-ai": {
|
|
"type": "api_key",
|
|
"key": "...",
|
|
"env": {
|
|
"CLOUDFLARE_ACCOUNT_ID": "account-id"
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
### Azure OpenAI
|
|
|
|
Set an API key plus either a base URL or resource name:
|
|
|
|
```bash
|
|
export AZURE_OPENAI_API_KEY=...
|
|
export AZURE_OPENAI_BASE_URL=https://your-resource.ai.azure.com
|
|
# Or:
|
|
export AZURE_OPENAI_RESOURCE_NAME=your-resource
|
|
```
|
|
|
|
Resource root URLs under `ai.azure.com`, `cognitiveservices.azure.com`, and `openai.azure.com` are normalized to the OpenAI API path.
|
|
|
|
### Amazon Bedrock
|
|
|
|
Bedrock can use a bearer token or an ambient AWS credential source:
|
|
|
|
```bash
|
|
# Named profile
|
|
export AWS_PROFILE=your-profile
|
|
|
|
# IAM keys
|
|
export AWS_ACCESS_KEY_ID=AKIA...
|
|
export AWS_SECRET_ACCESS_KEY=...
|
|
# Required for temporary credentials
|
|
export AWS_SESSION_TOKEN=...
|
|
|
|
# Bedrock bearer token
|
|
export AWS_BEARER_TOKEN_BEDROCK=...
|
|
|
|
# Region, when not supplied by the profile or AWS SDK configuration
|
|
export AWS_REGION=us-west-2
|
|
# AWS_DEFAULT_REGION is also supported
|
|
```
|
|
|
|
Pi also supports ECS task credentials and IRSA through the standard `AWS_CONTAINER_CREDENTIALS_*` and `AWS_WEB_IDENTITY_TOKEN_FILE` variables.
|
|
|
|
### Cloudflare AI Gateway
|
|
|
|
The gateway requires a token, account ID, and gateway ID:
|
|
|
|
```bash
|
|
export CLOUDFLARE_API_KEY=...
|
|
export CLOUDFLARE_ACCOUNT_ID=...
|
|
export CLOUDFLARE_GATEWAY_ID=...
|
|
```
|
|
|
|
The account and gateway IDs can come from the process environment or the credential's `env` object in `auth.json`.
|
|
|
|
`CLOUDFLARE_API_KEY` authenticates Pi to the gateway. Upstream access can use Cloudflare unified billing, credentials stored in the gateway, or an `Authorization` header configured for the provider in `models.json`.
|
|
|
|
### Cloudflare Workers AI
|
|
|
|
Workers AI requires a token and account ID:
|
|
|
|
```bash
|
|
export CLOUDFLARE_API_KEY=...
|
|
export CLOUDFLARE_ACCOUNT_ID=...
|
|
```
|
|
|
|
The account ID can also be stored in the credential's `env` object.
|
|
|
|
### Google Vertex AI
|
|
|
|
Use a Google Cloud API key:
|
|
|
|
```bash
|
|
export GOOGLE_CLOUD_API_KEY=...
|
|
```
|
|
|
|
To use Application Default Credentials, configure a project and location:
|
|
|
|
```bash
|
|
export GOOGLE_CLOUD_PROJECT=your-project
|
|
# GCLOUD_PROJECT is also supported
|
|
export GOOGLE_CLOUD_LOCATION=us-central1
|
|
```
|
|
|
|
Then authenticate:
|
|
|
|
```bash
|
|
gcloud auth application-default login
|
|
```
|
|
|
|
To use a service-account key file instead, set `GOOGLE_APPLICATION_CREDENTIALS` along with the project and location.
|