Providers

Providers

Atomic supports subscription-based providers via OAuth and API-key providers via environment variables or the auth file. Built-in catalogs ship with Atomic; configured and native providers may refresh newer catalogs independently and cache them in ~/.atomic/agent/models-store.json for offline use.

Table of Contents

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

Subscriptions

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

• ChatGPT Plus/Pro (Codex)
• Claude Pro/Max
• GitHub Copilot
• OpenRouter
• Kimi Code
• xAI (Grok/X subscription)
• Radius

Use /login <provider> (for example /login openrouter or /login kimi-coding) to jump directly to a provider, then select subscription or API-key authentication when both are available. OpenRouter opens its provider-owned browser PKCE flow and asks whether it should mint a new API key; complete the browser redirect before returning to Atomic. Kimi Code displays its provider-owned device URL/code and polls until approval, then refreshes expired tokens automatically. Built-in and extension-provided OAuth use the same direct and isolated-session lifecycle: engine-only extensions expose only safe display metadata to the terminal, while acquisition, transactional persistence, model refresh, rollback, and logout remain engine-owned. Credentials and executable provider functions never cross to the isolated frontend.

Escape or Ctrl+C quietly cancels the matching login, including immediate/pre-device native aborts, and leaves the previously committed credential and catalog unchanged. Provider denial, device expiry, timeout, browser/network/protocol failure, malformed responses, token exchange, persistence, and post-login refresh failures remain visible. Atomic does not claim success until the provider flow and credential transaction complete.

Use /logout to clear credentials. Logout immediately invalidates authentication in the active interactive engine and removes the selected provider from both ~/.atomic/agent/auth.json and any effective legacy ~/.pi/agent/auth.json, so the provider remains logged out after restart. Environment variables, command-line credentials, and models.json configuration cannot be cleared by Atomic; when one of those sources still authenticates the provider, the logout status names the remaining source. Stored tokens auto-refresh when expired.

OpenAI Codex

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

If the Codex backend reports that an OAuth/auth token was invalidated or revoked, retry the request once in case the rejection is transient. If it persists, run /logout and select OpenAI ChatGPT Plus/Pro, then run /login, authenticate that subscription again, and retry the request. Atomic displays these recovery steps with the provider error; it does not automatically delete the stored credential or repeatedly retry a definitive authentication rejection.

Codex Fast Mode

Run /fast in interactive mode to enable OpenAI priority service tier separately for normal chat and workflow-stage sessions. The command is shown only when the current model scope includes a supported openai/* or openai-codex/* model. Workflow stages use the workflow setting, not the chat setting. When enabled for the active supported model, the UI appends fast after the model name in the chat footer and workflow stage model labels. Fast mode intentionally does not apply to github-copilot/*, Azure OpenAI, OpenRouter, or custom OpenAI-compatible providers. Use workflow fast mode deliberately because parallel workflow fan-out can multiply priority-tier usage.

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.

For gateway-issued Anthropic bearer credentials, set ANTHROPIC_AUTH_TOKEN without ANTHROPIC_API_KEY or ANTHROPIC_OAUTH_TOKEN. A populated bearer token counts as configured Anthropic authentication, so /model, saved/default selection, cycling, RPC catalogs, and isolated model pickers keep Anthropic models available. Atomic sends it as Authorization: Bearer … for normal turns, branch summaries, and Verbatim Compaction without replacing caller-supplied custom headers.

Claude Opus 5 is available from the bundled/dynamic Anthropic and Amazon Bedrock catalogs. With bearer-only Anthropic auth, select the exact anthropic/claude-opus-5-* entry through /model; Bedrock uses its catalog-advertised inference profile. xhigh appears only when the chosen entry advertises it. Bedrock requests retain adaptive thinking, prompt caching, and AWS validation/error details from the provider runtime.

ANTHROPIC_AUTH_TOKEN is specifically for Anthropic-compatible gateways that require a bearer header. It does not synthesize an API key or x-api-key, and callers may still add independent custom headers/base URLs through models.json or an extension. Empty environment variables do not count as configured. If token and API-key sources are both configured, normal credential resolution rules apply; avoid setting both accidentally.

GitHub Copilot

• Press Enter for github.com, or enter your GitHub Enterprise Server domain
• COPILOT_GITHUB_TOKEN is read as an API key when you prefer an environment variable over /login
• Models come from the bundled pi-ai GitHub Copilot catalog; an OAuth credential narrows the list to the ids your account can actually use
• 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.

Radius

Radius is a dynamic pi-messages gateway. /login radius stores OAuth tokens in auth.json; its model catalog refreshes independently and is cached in models-store.json. API-key authentication is also available through /login radius or RADIUS_API_KEY. Custom Radius gateways can be declared in models.json with "oauth": "radius" and the 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-...
atomic

After a successful API-key or OAuth login, Atomic refreshes provider credentials and model discovery in the active session. Newly authenticated models are immediately available in /model without restarting Atomic, including providers with dynamically discovered catalogs.

Remote pi.dev catalogs persist their ETag and are revalidated with If-None-Match; an empty 304 keeps the cached models and counts as a successful check. Atomic renders the cached snapshot immediately, preserves each provider’s last usable catalog on refresh failure, and prefers newer bundled data over stale remote overlays. See Custom Models.

Provider	Environment Variable	auth.json key
Anthropic	ANTHROPIC_API_KEY or bearer-only ANTHROPIC_AUTH_TOKEN	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
Google Vertex AI	GOOGLE_CLOUD_API_KEY	google-vertex
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	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
Moonshot AI	MOONSHOT_API_KEY	moonshotai
Moonshot AI (China)	MOONSHOT_API_KEY	moonshotai-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

Reference for environment variables and auth.json keys: findEnvKeys() / getEnvApiKey() in the installed @earendil-works/pi-ai dependency (node_modules/@earendil-works/pi-ai/dist/env-api-keys.d.ts). The private provider map those functions use is in node_modules/@earendil-works/pi-ai/dist/env-api-keys.js; Atomic does not include a separate packages/ai source directory in this monorepo.

Auth File

Store credentials in ~/.atomic/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": "..." }
}

The file is created with 0600 permissions (user read/write only). Auth file credentials take priority over environment variables.

API-key credentials may include provider-scoped env values. They take precedence over process environment variables while resolving the credential key, provider/model headers, and provider configuration such as Cloudflare account IDs, Azure settings, Vertex project/location, Bedrock settings, 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 Atomic should use provider settings different from 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
  { "type": "api_key", "key": "sk-ant-..." }
  { "type": "api_key", "key": "public" }
  

Legacy uppercase env-var-like values such as MY_API_KEY are migrated to $MY_API_KEY on startup only when that environment variable is present during migration; otherwise the value is preserved as a literal. The same explicit $ENV_VAR rule and guarded legacy migration apply to custom provider apiKey and header values in models.json; see Custom Models. 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.openai.azure.com
# also supported: https://your-resource.cognitiveservices.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

# 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).

atomic --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
atomic --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 must be set as environment variables.

export CLOUDFLARE_API_KEY=...           # or use /login
export CLOUDFLARE_ACCOUNT_ID=...
export CLOUDFLARE_GATEWAY_ID=...        # create at dash.cloudflare.com → AI → AI Gateway
atomic --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 Atomic 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 must be set as an environment variable.

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

Atomic 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

For router-mode discovery, load/unload management, and Hugging Face downloads with a local llama.cpp server, see llama.cpp. Configure it with /login llama.cpp or LLAMA_BASE_URL and manage models with /llama.

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 Custom models.

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

Resolution Order

When resolving credentials for a provider:

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