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| xAI | SuperGrok or X Premium device-code login. The browser URL is prefilled with the device code. |
39| GitHub Copilot | GitHub Copilot token flow. |
40
41OAuth tokens are stored in `$ZOT_HOME/auth.json` and refreshed when refresh is
42available.
43
44## API-key providers
45
46These providers can use environment variables. Simple API-key providers can
47also be configured through `/login`. Providers that require extra cloud setup
48show instructions and should be configured with environment variables.
49
50| Provider | Environment variable | Stored key |
51| --- | --- | --- |
52| Anthropic | `ANTHROPIC_API_KEY` | `anthropic` |
53| OpenAI | `OPENAI_API_KEY` | `openai` |
54| OpenAI Responses | `OPENAI_API_KEY` | `openai-responses` |
55| Kimi | `KIMI_API_KEY` or `MOONSHOT_API_KEY` | `kimi` |
56| Google Gemini | `GEMINI_API_KEY` or `GOOGLE_API_KEY` | `google` |
57| DeepSeek | `DEEPSEEK_API_KEY` | `deepseek` |
58| Moonshot AI | `MOONSHOT_API_KEY` | `moonshotai` |
59| Moonshot AI China | `MOONSHOT_API_KEY` | `moonshotai-cn` |
60| Groq | `GROQ_API_KEY` | `groq` |
61| xAI | `XAI_API_KEY` | `xai` |
62| Cerebras | `CEREBRAS_API_KEY` | `cerebras` |
63| Together AI | `TOGETHER_API_KEY` | `together` |
64| Hugging Face | `HF_TOKEN` | `huggingface` |
65| OpenRouter | `OPENROUTER_API_KEY` | `openrouter` |
66| Mistral | `MISTRAL_API_KEY` | `mistral` |
67| ZAI | `ZAI_API_KEY` | `zai` |
68| Xiaomi MiMo | `XIAOMI_API_KEY` | `xiaomi` |
69| Xiaomi Token Plan Amsterdam | `XIAOMI_TOKEN_PLAN_AMS_API_KEY` | `xiaomi-token-plan-ams` |
70| Xiaomi Token Plan China | `XIAOMI_TOKEN_PLAN_CN_API_KEY` | `xiaomi-token-plan-cn` |
71| Xiaomi Token Plan Singapore | `XIAOMI_TOKEN_PLAN_SGP_API_KEY` | `xiaomi-token-plan-sgp` |
72| MiniMax | `MINIMAX_API_KEY` | `minimax` |
73| MiniMax China | `MINIMAX_CN_API_KEY` or `MINIMAX_API_KEY` | `minimax-cn` |
74| Fireworks | `FIREWORKS_API_KEY` | `fireworks` |
75| Vercel AI Gateway | `AI_GATEWAY_API_KEY` | `vercel-ai-gateway` |
76| OpenCode Zen | `OPENCODE_API_KEY` | `opencode` |
77| OpenCode Go | `OPENCODE_API_KEY` | `opencode-go` |
78| GitHub Copilot token | `COPILOT_GITHUB_TOKEN` or `GITHUB_COPILOT_TOKEN` | `github-copilot` |
79| Cloudflare Workers AI | `CLOUDFLARE_API_KEY` | `cloudflare-workers-ai` |
80| Cloudflare AI Gateway | `CLOUDFLARE_API_KEY` | `cloudflare-ai-gateway` |
81| Azure OpenAI Responses | `AZURE_OPENAI_API_KEY` | `azure-openai-responses` |
82
83Example:
84
85```bash
86export OPENROUTER_API_KEY=...
87zot --provider openrouter
88```
89
90## Cloud providers
91
92### Amazon Bedrock
93
94Bedrock is configured with AWS credentials, not a generic zot API-key entry.
95Use one of these credential sources:
96
97```bash
98# AWS profile
99export AWS_PROFILE=your-profile
100
101# IAM access keys
102export AWS_ACCESS_KEY_ID=AKIA...
103export AWS_SECRET_ACCESS_KEY=...
104export AWS_SESSION_TOKEN=... # only for temporary credentials
105
106# Bedrock API key bearer token
107export AWS_BEARER_TOKEN_BEDROCK=bedrock-api-key-...
108
109# Region
110export AWS_REGION=us-east-1
111```
112
113ECS task roles, IRSA, and other AWS SDK credential-chain sources are also
114supported.
115
116Example:
117
118```bash
119AWS_BEARER_TOKEN_BEDROCK=bedrock-api-key-... AWS_REGION=us-east-1 \
120  zot --provider amazon-bedrock --model anthropic.claude-sonnet-4-5-20250929-v1:0
121```
122
123Some Bedrock models require regional inference-profile IDs for on-demand
124throughput, such as `us.` or `eu.` prefixed model IDs. zot rewrites known
125families automatically where possible. Explicit profile IDs and ARNs are left
126unchanged.
127
128### Google Vertex AI
129
130Vertex can use a Google API key when available:
131
132```bash
133export GOOGLE_CLOUD_API_KEY=...
134zot --provider google-vertex
135```
136
137For service-account or application-default credentials, set the standard
138Google environment variables used by your deployment.
139
140### Cloudflare AI Gateway
141
142Cloudflare AI Gateway needs a Cloudflare token plus account and gateway IDs:
143
144```bash
145export CLOUDFLARE_API_KEY=...
146export CLOUDFLARE_ACCOUNT_ID=...
147export CLOUDFLARE_GATEWAY_ID=...
148zot --provider cloudflare-ai-gateway
149```
150
151### Cloudflare Workers AI
152
153Workers AI needs a Cloudflare token and account ID:
154
155```bash
156export CLOUDFLARE_API_KEY=...
157export CLOUDFLARE_ACCOUNT_ID=...
158zot --provider cloudflare-workers-ai
159```
160
161### Azure OpenAI Responses
162
163```bash
164export AZURE_OPENAI_API_KEY=...
165export AZURE_OPENAI_BASE_URL=https://your-resource.openai.azure.com
166export AZURE_OPENAI_API_VERSION=v1 # optional, v1 is the default
167zot --provider azure-openai-responses
168```
169
170The provider uses Azure's Responses API. If deployment names differ from zot
171model IDs, map them without changing the catalog:
172
173```bash
174export AZURE_OPENAI_DEPLOYMENT_NAME_MAP='gpt-5.6-luna=luna-preview,gpt-5.6-sol=sol-preview'
175```
176
177## Auth file
178
179Credentials are stored in `$ZOT_HOME/auth.json` with user-only permissions
180when zot creates the file.
181
182Example:
183
184```json
185{
186  "anthropic": { "api_key": "sk-ant-..." },
187  "openai": { "api_key": "sk-..." },
188  "google": { "api_key": "..." },
189  "additional_api_key_creds": {
190    "openrouter": { "api_key": "..." },
191    "mistral": { "api_key": "..." }
192  }
193}
194```
195
196The top-level keys are used for providers with dedicated credential fields.
197Other API-key providers are stored under `additional_api_key_creds`. Prefer
198`/login` so zot writes the correct schema.
199
200## Custom providers and models
201
202Use `$ZOT_HOME/models.json` for private models, deployment aliases, local
203servers, or OpenAI-compatible gateways that are not in the built-in catalog.
204User entries override built-in entries with the same provider and model ID, and
205adding a `models.json` no longer hides the built-in catalog: your entries are
206merged on top of the baked-in and live-discovered models.
207
208A top-level provider key that is not a built-in id defines a custom provider.
209Give it a provider-level `baseUrl` and an `api` wire format (`openai` for
210OpenAI-compatible chat completions, the default, or `anthropic` for the
211Anthropic messages API). A model-level `baseUrl` overrides the provider-level
212one for that model, and an unknown `api` value falls back to `openai` with a
213warning.
214
215```json
216{
217  "providers": {
218    "my-company": {
219      "baseUrl": "https://llm.mycompany.com/v1",
220      "api": "openai",
221      "models": [
222        { "id": "company-llm-v2", "name": "Company LLM v2" }
223      ]
224    }
225  }
226}
227```
228
229Custom providers are first-class: they appear in `--list-models`, `/model`, and
230`/login`. `models.json` never stores secrets. Supply the key through `/login`,
231`--api-key`, or a derived environment variable in upper snake case, so
232`my-company` reads `MY_COMPANY_API_KEY`. Because many self-hosted gateways do
233not expose a model-list endpoint, custom provider keys are accepted and stored
234without a verification probe; an invalid key surfaces on the first model call.
235
236## Credential resolution
237
238For each request, zot checks credentials in this order:
239
2401. Explicit CLI key, such as `--api-key`.
2412. Provider-specific environment variables (including derived custom-provider
242   variables such as `MY_COMPANY_API_KEY`).
2433. `$ZOT_HOME/auth.json`, including custom provider keys saved by `/login`.
244
245`models.json` itself never stores credentials; it only describes models and
246their endpoints.
247
248Bedrock then uses the AWS SDK credential chain for the actual request.