​

Providers

​

Table of Contents

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

​

Subscriptions

• ChatGPT Plus/Pro (Codex)
• Claude Pro/Max
• GitHub Copilot
• xAI (Grok/X subscription)
• Radius
• Cursor (experimental) 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

​

Codex Fast Mode

​

Claude Pro/Max

​

GitHub Copilot

• Press Enter for github.com, or enter your GitHub Enterprise Server domain
• When using COPILOT_GITHUB_TOKEN instead of /login, Atomic uses the token’s proxy-ep when present, honors COPILOT_API_TARGET or GITHUB_COPILOT_BASE_URL overrides, derives the tenant-specific GHE routing host from GITHUB_SERVER_URL=*.ghe.com, derives https://api.enterprise.githubcopilot.com from other non-github.com server URLs, and otherwise falls back to the public Copilot routing hub https://api.githubcopilot.com instead of the account-specific individual endpoint.
• If you get “model not supported”, enable it in VS Code: Copilot Chat → model selector → select model → “Enable”
• GitHub Copilot models are populated dynamically from Copilot’s live CAPI /models catalog when Copilot auth is available. Atomic synthesizes only picker-enabled, non-disabled chat entries with plain ids (for example github-copilot/claude-sonnet-5 and github-copilot/mai-code-1-flash-picker); namespaced enterprise deployments containing / are skipped rather than exposed as github-copilot/* models. Models that advertise long-context limits, such as github-copilot/gpt-5.5, github-copilot/claude-opus-4.8, and github-copilot/gemini-3.1-pro-preview, expose an opt-in long-context choice through --context-window, the /model selection flow, per-model defaultContextWindows, SDK, and RPC controls. The long-context option advertises the model’s full context window (for example 1m or 1.05m — GitHub’s max_context_window_tokens), matching how the native openai/* and anthropic/* providers report these models and what the chat footer shows. GitHub’s lower server-side prompt cap (max_prompt_tokens, for example 936k or 922k) is retained internally as the effective input budget that drives compaction thresholds and overflow recovery, and GitHub’s live output cap (max_output_tokens) replaces Atomic’s bundled maxTokens fallback for provider requests. If CAPI advertises capabilities.supports.reasoning_effort as an array, Atomic also gates /model and thinking-level cycling to only those live levels for both dynamic Copilot models and bundled pi-ai Copilot models; budget-only or boolean-only reasoning metadata leaves the existing thinking map untouched. Active interactive sessions refresh from this metadata as soon as the catalog is applied, so a startup fallback model does not keep stale reasoning levels until restart. This lets Atomic display the branded context window, request the catalog-advertised output budget, and avoid offering unsupported Copilot reasoning levels.
• Selecting long context sets Atomic’s displayed window to the model’s full capacity while compaction triggers against the effective prompt-token budget, and makes Copilot requests include X-GitHub-Api-Version: 2026-06-01. Atomic does not send a body field, contextTier, or model-id variant; GitHub automatically applies the server-side long_context tier when prompt tokens exceed the default budget.
• Long-context Copilot requests consume more AI credits and require Copilot long-context/usage-based billing entitlement. A prompt that reaches the model’s normal prompt cap is compacted and retried automatically. Only when GitHub rejects a prompt below that cap — for example because the account lacks the long-context/usage-based billing entitlement and is dropped to a smaller server tier — does Atomic surface a friendly entitlement/server-cap/cost hint rather than silently truncating context.
• Gemini models (github-copilot/gemini-3.1-pro-preview, github-copilot/gemini-3.5-flash, …) are served through Copilot’s CAPI gateway, which re-translates the OpenAI request into Google’s GenAI format and enforces Gemini’s stricter FunctionDeclaration schema (it rejects a tool-parameter anyOf/oneOf whose branch is a complex object, returning 400 invalid request body). Atomic automatically sanitizes outbound tool/function JSON Schemas for these models into the supported subset — resolving object/array-bearing unions to their most expressive branch, converting const/literal unions to enum, collapsing nullable unions to nullable, and dropping non-portable keywords such as additionalProperties, patternProperties, format, and numeric/length bounds. Gemini also serializes array/object tool-call arguments as flattened indexed keys (keywords[0], keywords[1], …); Atomic reconstructs these back into proper arrays/objects before validation so tool calls (including structured_output and MCP tools) don’t fail and loop. Both transforms are transparent and scoped to GitHub Copilot Gemini models only; no configuration is required and other providers/models are unaffected.
• Claude/Anthropic Messages models served through GitHub Copilot use Copilot SSE transport. If Copilot cleanly ends a /v1/messages stream after Anthropic terminal stop-reason evidence but omits the required message_stop event, Atomic adds that one terminal event before provider parsing so the turn can finish normally, including when the final complete SSE frame reaches EOF without a trailing blank-line separator. The repair covers public Copilot hosts and GHE tenant routes such as copilot-api.<enterprise>.ghe.com, and is otherwise limited to closed, non-error Copilot Anthropic event streams; malformed, truncated, already well-formed, non-Copilot/look-alike host, non-SSE, Gemini, and OpenAI-style streams continue through the normal parser and retry behavior.

​

xAI (Grok/X subscription)

​

Radius

​

Cursor (experimental)

• Cursor uses private, undocumented APIs and Cursor CLI-compatible headers. Atomic keeps the transport isolated and labels this provider experimental because Cursor may change the protocol without notice; use may conflict with Cursor’s terms of service or provider-side account policies.
• Image input is supported only for known multimodal Cursor Claude, Composer, Gemini, GPT, and Kimi model families (IDs beginning claude-, composer-, gemini-, gpt-, or kimi-), plus grok-4.3. Text-only Cursor models still reject images with a clear error.
• For image-capable Cursor models, Atomic serializes user images and mixed text/image MCP tool results into Cursor’s private request format. Image payloads must be non-empty standard base64; MIME-style line wrapping whitespace is accepted and stripped before serialization.
• Model metadata is cached token-free in ~/.atomic/agent/cursor-model-catalog.json and can be used at startup before fresh credentials are available. Estimated labels are used only when no valid cache exists and allowed live GetUsableModels discovery failures occur; refresh-time discovery is best-effort so rotated credentials are still persisted.
• Cursor’s private model discovery does not return token-limit metadata. Atomic preserves any positive limits Cursor does send, then resolves a model’s context window and max output tokens from its bundled @earendil-works/pi-ai model catalog by matching the Cursor model ID’s family/version. Explicit 1M Cursor ids or labels on any fast/thinking sibling for the same family are treated as a 1,000,000-token context floor even when the closest reference match advertises a smaller base window. Cursor-only models with no pi-ai match (for example composer-* and default/Auto) keep a conservative 200k context / 64k output estimate. This only sets limits; it never changes which Cursor models are listed.
• Cursor thinking levels are derived from the discovered variants for each model group. Atomic exposes xhigh only when Cursor advertises an xhigh or max variant, and exposes the distinct max level only when Cursor advertises an actual max variant. If an older saved xhigh or max selection is restored for a model that currently has only lower-effort variants, the request falls back to the nearest concrete Cursor variant instead of sending an invalid id.
• The implementation avoids a localhost proxy and keeps credentials OAuth-only. Cursor’s HTTP/2 transport uses the bundled @bastani/atomic-natives Rust/N-API client, so it does not require Node.js on PATH. The native client currently opens request-scoped HTTP/2 sessions; pooling may be added in a future release.
• Cursor request encoding intentionally omits a previousWorkspaceUris current-directory entry by default so local absolute working-directory paths are not sent as workspace context. HTTP/2 Connect request/framing code is isolated, buffered across arbitrary chunks, tested with injected fakes, and uses a minimal production protobuf codec with field-order-independent exec ids, protobuf Value plus raw UTF-8/JSON tool arguments, historical tool-result correlation, checkpoint token-details parsing, paused-stream abort/idle cleanup, catalog-aware fast/thinking model grouping, and credential/PKCE-redacted protocol errors.

​

API Keys

​

Environment Variables or Auth File

export ANTHROPIC_API_KEY=sk-ant-...
atomic

​

Auth File

{
  "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": "..." }
}

{
  "cloudflare-ai-gateway": {
    "type": "api_key",
    "key": "$CLOUDFLARE_API_KEY",
    "env": {
      "CLOUDFLARE_API_KEY": "...",
      "CLOUDFLARE_ACCOUNT_ID": "account-id",
      "CLOUDFLARE_GATEWAY_ID": "gateway-id"
    }
  }
}

​

Key Resolution

• 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" }
  

​

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

atomic --provider amazon-bedrock --model us.anthropic.claude-sonnet-4-20250514-v1:0

export AWS_BEDROCK_FORCE_CACHE=1
atomic --provider amazon-bedrock --model arn:aws:bedrock:us-east-1:123456789012:application-inference-profile/abc123

# 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

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"

​

Cloudflare Workers AI

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

​

Google Vertex AI

gcloud auth application-default login
export GOOGLE_CLOUD_PROJECT=your-project
export GOOGLE_CLOUD_LOCATION=us-central1

​

llama.cpp

​

Custom Providers

​

Resolution Order

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