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.

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:

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

Start here

Customization

Reference

Programmatic Usage

Platform Setup

Development

Changelog

Providers

Providers

Table of Contents

Subscriptions

OpenAI Codex

Codex Fast Mode

Claude Pro/Max

GitHub Copilot

xAI (Grok/X subscription)

Radius

API Keys

Environment Variables or Auth File

Auth File

Key Resolution

Cloud Providers

Azure OpenAI

Amazon Bedrock

Cloudflare AI Gateway

Cloudflare Workers AI

Google Vertex AI

llama.cpp

Custom Providers

Resolution Order

​Providers

​Table of Contents

​Subscriptions

​OpenAI Codex

​Codex Fast Mode

​Claude Pro/Max

​GitHub Copilot

​xAI (Grok/X subscription)

​Radius

​API Keys

​Environment Variables or Auth File

​Auth File

​Key Resolution

​Cloud Providers

​Azure OpenAI

​Amazon Bedrock

​Cloudflare AI Gateway

​Cloudflare Workers AI

​Google Vertex AI

​llama.cpp

​Custom Providers

​Resolution Order

Providers

Table of Contents

Subscriptions

OpenAI Codex

Codex Fast Mode

Claude Pro/Max

GitHub Copilot

xAI (Grok/X subscription)

Radius

API Keys

Environment Variables or Auth File

Auth File

Key Resolution

Cloud Providers

Azure OpenAI

Amazon Bedrock

Cloudflare AI Gateway

Cloudflare Workers AI

Google Vertex AI

llama.cpp

Custom Providers

Resolution Order