1# zot providers
2
3zot ships with built-in providers and a model catalog. You can select models
4with `/model`, list them with `zot --list-models`, and add private models in
5`$ZOT_HOME/models.json`.
6
7## Login methods
8
9Use `/login` in interactive mode.
10
11- `api key`: stores an API key in `$ZOT_HOME/auth.json` when the provider uses a normal key.
12- `subscription`: stores OAuth credentials for subscription-backed providers.
13
14Use `/logout` to remove stored credentials.
15
16Some providers need more than a single pasted key. For those providers,
17`/login` shows setup instructions instead of opening a localhost browser form.
18This avoids broken browser flows in SSH, containers, and `kubectl exec`
19sessions.
20
21Setup-instruction providers:
22
23- Amazon Bedrock
24- Google Vertex AI
25- Cloudflare Workers AI
26- Cloudflare AI Gateway
27- Azure OpenAI Responses
28
29## Subscription providers
30
31These providers support subscription login:
32
33| Provider | Notes |
34| --- | --- |
35| Anthropic | Claude Pro/Max OAuth credentials. |
36| OpenAI Codex | ChatGPT Plus/Pro Codex subscription route. Separate from the OpenAI API-key provider. |
37| Kimi | Kimi subscription login. |
38| GitHub Copilot | GitHub Copilot token flow. |
39
40OAuth tokens are stored in `$ZOT_HOME/auth.json` and refreshed when refresh is
41available.
42
43## API-key providers
44
45These providers can use environment variables. Simple API-key providers can
46also be configured through `/login`. Providers that require extra cloud setup
47show instructions and should be configured with environment variables.
48
49| Provider | Environment variable | Stored key |
50| --- | --- | --- |
51| Anthropic | `ANTHROPIC_API_KEY` | `anthropic` |
52| OpenAI | `OPENAI_API_KEY` | `openai` |
53| OpenAI Responses | `OPENAI_API_KEY` | `openai-responses` |
54| Kimi | `KIMI_API_KEY` or `MOONSHOT_API_KEY` | `kimi` |
55| Google Gemini | `GEMINI_API_KEY` or `GOOGLE_API_KEY` | `google` |
56| DeepSeek | `DEEPSEEK_API_KEY` | `deepseek` |
57| Moonshot AI | `MOONSHOT_API_KEY` | `moonshotai` |
58| Moonshot AI China | `MOONSHOT_API_KEY` | `moonshotai-cn` |
59| Groq | `GROQ_API_KEY` | `groq` |
60| xAI | `XAI_API_KEY` | `xai` |
61| Cerebras | `CEREBRAS_API_KEY` | `cerebras` |
62| Together AI | `TOGETHER_API_KEY` | `together` |
63| Hugging Face | `HF_TOKEN` | `huggingface` |
64| OpenRouter | `OPENROUTER_API_KEY` | `openrouter` |
65| Mistral | `MISTRAL_API_KEY` | `mistral` |
66| ZAI | `ZAI_API_KEY` | `zai` |
67| Xiaomi MiMo | `XIAOMI_API_KEY` | `xiaomi` |
68| Xiaomi Token Plan Amsterdam | `XIAOMI_TOKEN_PLAN_AMS_API_KEY` | `xiaomi-token-plan-ams` |
69| Xiaomi Token Plan China | `XIAOMI_TOKEN_PLAN_CN_API_KEY` | `xiaomi-token-plan-cn` |
70| Xiaomi Token Plan Singapore | `XIAOMI_TOKEN_PLAN_SGP_API_KEY` | `xiaomi-token-plan-sgp` |
71| MiniMax | `MINIMAX_API_KEY` | `minimax` |
72| MiniMax China | `MINIMAX_CN_API_KEY` or `MINIMAX_API_KEY` | `minimax-cn` |
73| Fireworks | `FIREWORKS_API_KEY` | `fireworks` |
74| Vercel AI Gateway | `AI_GATEWAY_API_KEY` | `vercel-ai-gateway` |
75| OpenCode Zen | `OPENCODE_API_KEY` | `opencode` |
76| OpenCode Go | `OPENCODE_API_KEY` | `opencode-go` |
77| GitHub Copilot token | `COPILOT_GITHUB_TOKEN` or `GITHUB_COPILOT_TOKEN` | `github-copilot` |
78| Cloudflare Workers AI | `CLOUDFLARE_API_KEY` | `cloudflare-workers-ai` |
79| Cloudflare AI Gateway | `CLOUDFLARE_API_KEY` | `cloudflare-ai-gateway` |
80| Azure OpenAI Responses | `AZURE_OPENAI_API_KEY` | `azure-openai-responses` |
81
82Example:
83
84```bash
85export OPENROUTER_API_KEY=...
86zot --provider openrouter
87```
88
89## Cloud providers
90
91### Amazon Bedrock
92
93Bedrock is configured with AWS credentials, not a generic zot API-key entry.
94Use one of these credential sources:
95
96```bash
97# AWS profile
98export AWS_PROFILE=your-profile
99
100# IAM access keys
101export AWS_ACCESS_KEY_ID=AKIA...
102export AWS_SECRET_ACCESS_KEY=...
103export AWS_SESSION_TOKEN=... # only for temporary credentials
104
105# Bedrock API key bearer token
106export AWS_BEARER_TOKEN_BEDROCK=bedrock-api-key-...
107
108# Region
109export AWS_REGION=us-east-1
110```
111
112ECS task roles, IRSA, and other AWS SDK credential-chain sources are also
113supported.
114
115Example:
116
117```bash
118AWS_BEARER_TOKEN_BEDROCK=bedrock-api-key-... AWS_REGION=us-east-1 \
119  zot --provider amazon-bedrock --model anthropic.claude-sonnet-4-5-20250929-v1:0
120```
121
122Some Bedrock models require regional inference-profile IDs for on-demand
123throughput, such as `us.` or `eu.` prefixed model IDs. zot rewrites known
124families automatically where possible. Explicit profile IDs and ARNs are left
125unchanged.
126
127### Google Vertex AI
128
129Vertex can use a Google API key when available:
130
131```bash
132export GOOGLE_CLOUD_API_KEY=...
133zot --provider google-vertex
134```
135
136For service-account or application-default credentials, set the standard
137Google environment variables used by your deployment.
138
139### Cloudflare AI Gateway
140
141Cloudflare AI Gateway needs a Cloudflare token plus account and gateway IDs:
142
143```bash
144export CLOUDFLARE_API_KEY=...
145export CLOUDFLARE_ACCOUNT_ID=...
146export CLOUDFLARE_GATEWAY_ID=...
147zot --provider cloudflare-ai-gateway
148```
149
150### Cloudflare Workers AI
151
152Workers AI needs a Cloudflare token and account ID:
153
154```bash
155export CLOUDFLARE_API_KEY=...
156export CLOUDFLARE_ACCOUNT_ID=...
157zot --provider cloudflare-workers-ai
158```
159
160### Azure OpenAI Responses
161
162```bash
163export AZURE_OPENAI_API_KEY=...
164export AZURE_OPENAI_BASE_URL=https://your-resource.openai.azure.com
165export AZURE_OPENAI_API_VERSION=2024-02-01 # optional
166zot --provider azure-openai-responses
167```
168
169If your Azure deployment names differ from zot model IDs, add model overrides
170in `$ZOT_HOME/models.json`.
171
172## Auth file
173
174Credentials are stored in `$ZOT_HOME/auth.json` with user-only permissions
175when zot creates the file.
176
177Example:
178
179```json
180{
181  "anthropic": { "api_key": "sk-ant-..." },
182  "openai": { "api_key": "sk-..." },
183  "google": { "api_key": "..." },
184  "additional_api_key_creds": {
185    "openrouter": { "api_key": "..." },
186    "mistral": { "api_key": "..." }
187  }
188}
189```
190
191The top-level keys are used for providers with dedicated credential fields.
192Other API-key providers are stored under `additional_api_key_creds`. Prefer
193`/login` so zot writes the correct schema.
194
195## Custom providers and models
196
197Use `$ZOT_HOME/models.json` for private models, deployment aliases, local
198servers, or OpenAI-compatible gateways that are not in the built-in catalog.
199User entries override built-in entries with the same provider and model ID.
200
201## Credential resolution
202
203For each request, zot checks credentials in this order:
204
2051. Explicit CLI key, such as `--api-key`.
2062. Provider-specific environment variables.
2073. `$ZOT_HOME/auth.json`.
2084. Custom provider credentials from `$ZOT_HOME/models.json`, when configured.
209
210Bedrock then uses the AWS SDK credential chain for the actual request.