getcompanion-ai/co-mono
1
0
Fork 0
mirror of https://github.com/getcompanion-ai/co-mono.git synced 2026-04-15 11:02:17 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

docs(coding-agent): move OAuth details to docs/authentication.md, simplify README

Browse source
This commit is contained in:
Mario Zechner 2026-01-25 21:36:14 +01:00
parent e112d2a917
commit 1b705a92b8
2 changed files with 127 additions and 93 deletions
Download patch file Download diff file Expand all files Collapse all files

100
packages/coding-agent/README.md
View file

@ -22,7 +22,7 @@ Pi runs in four modes: interactive, print or JSON, RPC for process integration,
- [Windows Setup](#windows-setup)
- [Shell Aliases](#shell-aliases)
- [Terminal Setup](#terminal-setup)
- [API Keys & OAuth](#api-keys--oauth)
- [API Keys](#api-keys)
- [Quick Start](#quick-start)
- [Usage](#usage)
- [Slash Commands](#slash-commands)
@ -103,106 +103,20 @@ Adjust the path (`~/.zshrc`, `~/.bashrc`, etc.) to match your shell config.
Pi uses the [Kitty keyboard protocol](https://sw.kovidgoyal.net/kitty/keyboard-protocol/) for reliable modifier key detection. Kitty and iTerm2 work out of the box. Other terminals may need configuration. See [docs/terminal-setup.md](docs/terminal-setup.md).
### API Keys & OAuth
### API Keys
**Option 1: Auth file** (recommended)
Add API keys to `~/.pi/agent/auth.json`:
```json
{
"anthropic": { "type": "api_key", "key": "sk-ant-..." },
"openai": { "type": "api_key", "key": "sk-..." },
"google": { "type": "api_key", "key": "..." }
}
```
**Option 2: Environment variables**
| Provider | Auth Key | Environment Variable |
|----------|--------------|---------------------|
| Anthropic | `anthropic` | `ANTHROPIC_API_KEY` |
| OpenAI | `openai` | `OPENAI_API_KEY` |
| Azure OpenAI | `azure-openai-responses` | `AZURE_OPENAI_API_KEY` + `AZURE_OPENAI_BASE_URL` or `AZURE_OPENAI_RESOURCE_NAME` |
| Google | `google` | `GEMINI_API_KEY` |
| Mistral | `mistral` | `MISTRAL_API_KEY` |
| Groq | `groq` | `GROQ_API_KEY` |
| Cerebras | `cerebras` | `CEREBRAS_API_KEY` |
| xAI | `xai` | `XAI_API_KEY` |
| OpenRouter | `openrouter` | `OPENROUTER_API_KEY` |
| Vercel AI Gateway | `vercel-ai-gateway` | `AI_GATEWAY_API_KEY` |
| ZAI | `zai` | `ZAI_API_KEY` |
| OpenCode Zen | `opencode` | `OPENCODE_API_KEY` |
| MiniMax | `minimax` | `MINIMAX_API_KEY` |
| MiniMax (China) | `minimax-cn` | `MINIMAX_CN_API_KEY` |
Azure OpenAI also requires `AZURE_OPENAI_BASE_URL` or `AZURE_OPENAI_RESOURCE_NAME`. Optional: `AZURE_OPENAI_API_VERSION` (defaults to `v1`) and `AZURE_OPENAI_DEPLOYMENT_NAME_MAP` using comma-separated `model=deployment` pairs for overrides.
Auth file keys take priority over environment variables.
**OAuth Providers:**
Use `/login` to authenticate with subscription-based or free-tier providers:
| Provider | Models | Cost |
|----------|--------|------|
| Anthropic (Claude Pro/Max) | Claude models via your subscription | Subscription |
| GitHub Copilot | GPT-4o, Claude, Gemini via Copilot subscription | Subscription |
| Google Gemini CLI | Gemini 2.0/2.5 models | Free (Google account) |
| Google Antigravity | Gemini 3, Claude, GPT-OSS | Free (Google account) |
| OpenAI Codex (ChatGPT Plus/Pro) | Codex models via ChatGPT subscription | Subscription |
Set an API key via environment variable or `~/.pi/agent/auth.json`:
```bash
export ANTHROPIC_API_KEY=sk-ant-...
pi
/login # Select provider, authorize in browser
```
**Note:** `/login` replaces any existing API key for that provider with OAuth credentials in `auth.json`.
Supported environment variables: `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `AZURE_OPENAI_API_KEY`, `GEMINI_API_KEY`, `MISTRAL_API_KEY`, `GROQ_API_KEY`, `CEREBRAS_API_KEY`, `XAI_API_KEY`, `OPENROUTER_API_KEY`, `AI_GATEWAY_API_KEY`, `ZAI_API_KEY`, `MINIMAX_API_KEY`, `OPENCODE_API_KEY`, `AWS_PROFILE`.
**GitHub Copilot notes:**
- Press Enter for github.com, or enter your GitHub Enterprise Server domain
- If you get "model not supported" error, enable it in VS Code: Copilot Chat → model selector → select model → "Enable"
For OAuth providers (GitHub Copilot, Google Gemini CLI, Anthropic Pro/Max), use `/login` in interactive mode.
**Google providers notes:**
- Gemini CLI uses the production Cloud Code Assist endpoint (standard Gemini models)
- Antigravity uses a sandbox endpoint with access to Gemini 3, Claude (sonnet/opus thinking), and GPT-OSS models
- Both are free with any Google account, subject to rate limits
- Paid Cloud Code Assist subscriptions: set `GOOGLE_CLOUD_PROJECT` or `GOOGLE_CLOUD_PROJECT_ID` env var to your project ID
**OpenAI Codex notes:**
- Requires ChatGPT Plus/Pro OAuth (`/login openai-codex`)
- Prompt cache stored under `~/.pi/agent/cache/openai-codex/`
- Intended for personal use with your own subscription; not for resale or multi-user services. For production, use the OpenAI Platform API.
Credentials stored in `~/.pi/agent/auth.json`. Use `/logout` to clear.
**Troubleshooting (OAuth):**
- **Port 1455 in use:** Close the conflicting process or paste the auth code/URL when prompted.
- **Token expired / refresh failed:** Run `/login` again for the provider to refresh credentials.
- **Usage limits (429):** Wait for the reset window; pi will surface a friendly message with the approximate retry time.
**Amazon Bedrock:**
Amazon Bedrock supports multiple authentication methods:
```bash
# Option 1: AWS Profile (from ~/.aws/credentials)
export AWS_PROFILE=your-profile-name
# Option 2: IAM Access Keys
export AWS_ACCESS_KEY_ID=AKIA...
export AWS_SECRET_ACCESS_KEY=...
# Option 3: Bedrock API Key (bearer token)
export AWS_BEARER_TOKEN_BEDROCK=...
# Optional: Set region (defaults to us-east-1)
export AWS_REGION=us-east-1
pi --provider amazon-bedrock --model global.anthropic.claude-sonnet-4-5-20250929-v1:0
```
See [Supported foundation models in Amazon Bedrock](https://docs.aws.amazon.com/bedrock/latest/userguide/models-supported.html).
See [docs/authentication.md](docs/authentication.md) for auth file format, all providers, and OAuth details.
### Quick Start

120
packages/coding-agent/docs/authentication.md Normal file
View file

@ -0,0 +1,120 @@
# Authentication
Pi supports API keys (environment variables or auth file) and OAuth for subscription-based providers.
## Auth File
Store credentials in `~/.pi/agent/auth.json`:
```json
{
"anthropic": { "type": "api_key", "key": "sk-ant-..." },
"openai": { "type": "api_key", "key": "sk-..." },
"google": { "type": "api_key", "key": "..." }
}
```
Auth file keys take priority over environment variables.
## Environment Variables
| Provider | Auth Key | Environment Variable |
|----------|----------|---------------------|
| Anthropic | `anthropic` | `ANTHROPIC_API_KEY` |
| OpenAI | `openai` | `OPENAI_API_KEY` |
| Azure OpenAI | `azure-openai` | `AZURE_OPENAI_API_KEY` |
| Google | `google` | `GEMINI_API_KEY` |
| Mistral | `mistral` | `MISTRAL_API_KEY` |
| Groq | `groq` | `GROQ_API_KEY` |
| Cerebras | `cerebras` | `CEREBRAS_API_KEY` |
| xAI | `xai` | `XAI_API_KEY` |
| OpenRouter | `openrouter` | `OPENROUTER_API_KEY` |
| Vercel AI Gateway | `vercel-ai-gateway` | `AI_GATEWAY_API_KEY` |
| ZAI | `zai` | `ZAI_API_KEY` |
| OpenCode Zen | `opencode` | `OPENCODE_API_KEY` |
| MiniMax | `minimax` | `MINIMAX_API_KEY` |
| MiniMax (China) | `minimax-cn` | `MINIMAX_CN_API_KEY` |
### Azure OpenAI
Requires additional configuration:
```bash
export AZURE_OPENAI_API_KEY=...
export AZURE_OPENAI_BASE_URL=https://your-resource.openai.azure.com
# or
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-deployment,gpt-4o=my-gpt4o
```
### Amazon Bedrock
```bash
# Option 1: AWS Profile
export AWS_PROFILE=your-profile-name
# Option 2: IAM Access 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-east-1
```
Usage:
```bash
pi --provider amazon-bedrock --model us.anthropic.claude-sonnet-4-20250514-v1:0
```
See [Supported models in Amazon Bedrock](https://docs.aws.amazon.com/bedrock/latest/userguide/models-supported.html).
## OAuth Providers
Use `/login` in interactive mode to authenticate with subscription-based or free-tier providers:
| Provider | Models | Cost |
|----------|--------|------|
| Anthropic (Claude Pro/Max) | Claude models via subscription | Subscription |
| GitHub Copilot | GPT-4o, Claude, Gemini via Copilot | Subscription |
| Google Gemini CLI | Gemini 2.0/2.5 models | Free |
| Google Antigravity | Gemini 3, Claude, GPT-OSS | Free |
| OpenAI Codex (ChatGPT Plus/Pro) | Codex models via ChatGPT | Subscription |
```bash
pi
/login # Select provider, authorize in browser
```
Use `/logout` to clear credentials.
### GitHub Copilot
- Press Enter for github.com, or enter your GitHub Enterprise Server domain
- If you get "model not supported" error, enable it in VS Code: Copilot Chat → model selector → select model → "Enable"
### Google Providers
- **Gemini CLI**: Production Cloud Code Assist endpoint with standard Gemini models
- **Antigravity**: Sandbox endpoint with Gemini 3, Claude (sonnet/opus thinking), and GPT-OSS
- Both are free with any Google account, subject to rate limits
- Paid Cloud Code Assist subscriptions: set `GOOGLE_CLOUD_PROJECT` or `GOOGLE_CLOUD_PROJECT_ID` env var
### OpenAI Codex
- Requires ChatGPT Plus/Pro subscription
- Prompt cache stored under `~/.pi/agent/cache/openai-codex/`
- Personal use only; for production, use the OpenAI Platform API
## Troubleshooting
**Port 1455 in use:** Close the conflicting process or paste the auth code/URL when prompted.
**Token expired / refresh failed:** Run `/login` again to refresh credentials.
**Usage limits (429):** Wait for the reset window; pi shows the approximate retry time.