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.
On this page and its reference
This page is provider setup: subscriptions, API keys, provider-specific configuration, and local llama.cpp. The exact contracts — provider stop reasons and credential resolution order — live in the Provider reference.Table of Contents
- Subscriptions
- Verify readiness before a session
- API Keys
- Auth File
- Provider Specific Config
- llama.cpp
- TypeSafe Jev
- Morph compaction
- Stop Reasons
- 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)
- Meta (Muse subscription)
- Radius
/login <provider>, such as /login openrouter or /login kimi-coding, to go directly to a provider. Select subscription or API-key authentication when both are available.
OpenRouter opens its browser PKCE flow and asks whether to mint a new API key. Complete the browser redirect before returning to Atomic. On remote or headless machines, the browser cannot reach the loopback callback; paste the final redirect URL or authorization code instead. Claude, ChatGPT Codex, and extension providers that set usesCallbackServer offer the same fallback.
Kimi Code displays its device URL/code and polls until approval, then refreshes expired tokens automatically.
Built-in and extension-provided OAuth work in both direct and isolated sessions. Login completes once credentials are saved; model-catalog refresh runs separately.
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, and persistence failures remain visible. Atomic claims success when the provider flow and credential persistence complete; it does not wait for model-catalog or ambient-availability refresh work.
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.
Type /logout to autocomplete providers with stored credentials, or use /logout kimi-coding to open a filtered selector; press Enter in the selector to remove the credential, or Escape to cancel.
Token Refresh
Atomic refreshes a stored OAuth token when fewer than five minutes of validity remain, so a long turn does not start with a token about to expire. Tokens outside this window are untouched. Concurrent sessions sharingauth.json, including workflow stages and subagents, coordinate token refresh rather than rotating the same credential independently. This holds when a session is slow or briefly unresponsive under heavy load. If a refresh reports a timeout, the token exchange keeps running and its result is saved when it arrives. Retry the request instead of signing in again. When Atomic exits normally (quitting an interactive session, SIGTERM, the end of an atomic -p run, or an atomic auth command), it waits up to three seconds for a token exchange still in flight and saves its result. If Atomic is killed or crashes during a token refresh, the provider may already have rotated the token; run /login <provider> to sign in again.
Running sessions pick up changes to auth.json made by another Atomic window, atomic auth, or another process’s token refresh without restarting. This applies to extension-provided OAuth too. Refresh runs automatically through the shared credential store; a failed refresh is reported as an OAuth error rather than starting a new login flow. If the provider rejects the stored login as revoked or expired (for example invalid_grant, OpenAI’s refresh_token_expired or refresh_token_reused, or HTTP 401), Atomic first uses a newer login that another session saved. When there is none, the error names the provider and tells you to run /login <provider>, because the provider has revoked or expired that login.
If a chat request is rejected with HTTP 401 or an invalid/revoked-token error before any response content arrives, Atomic rereads credentials and retries once only if the effective credential changed. It does not repeatedly retry the same rejected token or replay a partially delivered response. Explicit request credentials and runtime API-key overrides still take precedence over the auth file.
Verify Readiness Before a Session
Runatomic auth check --provider <provider> to verify the effective credential a provider would use without starting a session. You can pass --model <model> instead, including a provider/model ID, when that is the value your automation already has. The command prints ready, not_ready, or invalid; --json adds the resolved provider when one is found, credential type, and reason for a non-ready result.
Checks refresh expired OAuth credentials by default through the ordinary locked auth.json path. Use --no-refresh for a read-only probe: it neither creates nor mutates an auth file and reads Atomic’s primary ~/.atomic/agent/auth.json plus legacy ~/.pi/agent/auth.json paths with the normal precedence. Readiness output contains no credential material unless you explicitly ask for --credentials with --provider or an exact --model target. That opt-in treats stdout or the JSON credentials field as a credential export; it refuses an OAuth token with less than 30 minutes of life when --no-refresh prevents a refresh.
OpenAI API or ChatGPT sign-in
Run/login openai, then choose API key or Sign in with ChatGPT. The ChatGPT option authenticates the openai provider for requests to OpenAI’s Responses API; it is separate from /login openai-codex, which uses the Codex backend. Choose the provider/model identity appropriate to the account and endpoint you intend to use.
Complete the browser callback, or paste the full callback URL into the login dialog on a remote machine. If your browser cannot reach 127.0.0.1:1455, copy the final URL from its address bar, including code, state, and client_id, and paste it into Atomic. Atomic creates a global device identity on first use of this sign-in; project settings do not override it. A saved subscription credential does not verify model entitlement or remaining usage.
Apps using @bastani/pi-ai directly can pass { agentName: "my-app" } as the fourth argument to models.login() to set the OpenAI ChatGPT name hint or Codex browser-login originator. ChatGPT sign-in keeps Atomic as its default name.
Subscription and API key at the same time
openai and anthropic hold one credential each, so a subscription login there replaces the API key. To keep both, use the API-key-only providers openai-api and anthropic-api. They list the same chat models, send requests to the same endpoints, and read OPENAI_API_KEY or ANTHROPIC_API_KEY unless you save a key with /login openai-api or /login anthropic-api. They never offer subscription sign-in, and anthropic-api ignores ANTHROPIC_OAUTH_TOKEN and ANTHROPIC_AUTH_TOKEN.
For example, sign in with ChatGPT under openai and select openai/gpt-6-sol for subscription chat, while a workflow stage pinned to openai-api/gpt-6-sol bills the API key.
The GPT-6 Luna Decisions classifier (openai-decisions) has no login of its own. It uses the key saved for openai-api, then a key saved for openai, then OPENAI_API_KEY, and ignores a ChatGPT sign-in. See Classifier models.
OpenAI’s image models (openai-images, such as openai-images/gpt-image-2.5-flare) work the same way: no login of their own, the key saved for openai-api, then a key saved for openai, then OPENAI_API_KEY. A ChatGPT sign-in cannot call OpenAI’s Images API and is skipped, so with only that sign-in the image models stay unavailable until you save an API key with /login openai-api or set OPENAI_API_KEY. Generate images with them from codemode or a workflow tool step.
OpenAI Codex
- Requires ChatGPT Plus or Pro subscription
- Officially endorsed by OpenAI: Codex for OSS
/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.
For Codex requests, models.json headers or per-request SDK headers can override originator and User-Agent. The transport still supplies the authenticated bearer token and ChatGPT account ID.
GPT-6-Astra is selectable as openai-codex/gpt-6-astra. Atomic also derives the canonical openai-codex/gpt-6-astra-fast choice. The fast choice sends upstream model gpt-6-astra with service_tier: priority and keeps the first-party Codex transport identity described below. Access can still depend on the account, rollout, and minimum client policy even though Atomic lists the model.
GPT-6 Sol and GPT-6 Luna are selectable as openai/gpt-6-sol, openai/gpt-6-luna, openai-codex/gpt-6-sol, and openai-codex/gpt-6-luna. Each has a derived -fast choice, such as openai-codex/gpt-6-sol-fast, that sends the base upstream model with service_tier: priority. Copilot’s bundled catalog and account policy determine which Sol models are available; fast siblings require an exact advertised ID.
GPT-6.1 Sol is selectable as openai/gpt-6.1-sol and openai-codex/gpt-6.1-sol, with derived -fast siblings. For example, atomic --model openai-codex/gpt-6.1-sol-fast:high selects priority routing at high effort. Sol 6.1 supports low, medium, high, xhigh, and max; Codex’s minimal UI alias also sends low. off is unavailable. See Sol 6.1 limits and pricing.
GPT-6.1 Sol also has an -ultrafast choice on openai/*, openai-api/* and openai-codex/*, for example openai/gpt-6.1-sol-ultrafast.
ChatGPT sign-in through either openai or openai-codex gives GPT-6.1 Sol a 500,000-token context on Standard, Fast, and Ultrafast, without long-context fees. API-key sign-in through openai or openai-api keeps the 272,000-token default and API long-context pricing. Account aliases follow their own authentication method. Fast and Ultrafast choices work with either authentication method when the account supports the requested tier.
Fast and Ultrafast tiers
Atomic offers a tier only for the models that advertise it, following Codex’s per-model catalog and OpenAI’s published API pricing:- Fast (
service_tier: priority): every Codex model, and theopenai/*models listed on OpenAI’s Fast pricing tab. For example,openai/gpt-5-nano,openai/gpt-5-pro, andopenai/o1have no-fastchoice. - Ultrafast (
service_tier: "ultrafast"): GPT-6 Astra and GPT-6.1 Sol, asopenai/gpt-6-astra-ultrafastandopenai/gpt-6.1-sol-ultrafast(also underopenai-api/andopenai-codex/), plus GPT-5.6 Sol on the OpenAI API, asopenai/gpt-5.6-sol-ultrafast(also underopenai-api/). For example,atomic --model openai-codex/gpt-6-astra-ultrafast:high. Each keeps the base upstream model, following Codex’s tier-switching protocol. GPT-5.6 Sol Ultrafast is a limited preview, so most accounts get the fallback below.
400 Invalid service_tier argument), Atomic retries once at the default tier and warns that the choice ran at default instead of failing the turn. Other providers still fail the request. With an OpenAI API key, Atomic also warns when the response reports a slower tier than the one you chose. With ChatGPT sign-in, on openai/* or openai-codex/*, it does not, because the ChatGPT backend reports default for every tier, including Fast and Ultrafast requests it ran at that tier. The warning, for example ultrafast isn't available for gpt-5.6-sol on this account; ran at default, appears under the response in interactive sessions, on stderr in print mode, and in the message diagnostics in JSON mode.
A tier the model does not advertise is left out of the request, which then runs at standard processing instead of failing. flex is always passed through. With Codex, an explicit default sends no tier, as in Codex. With the OpenAI API, default is sent as requested.
Usage is priced at the tier that served the request, using OpenAI’s published per-model rates. Fast is usually twice Standard but varies by model: GPT-5.5 is 2.5x and GPT-4o is 1.7x. GPT-6 Astra Ultrafast is six times Standard: $60 input, $6 cached input, $75 cache write, and $300 output per million tokens up to 272,000 input tokens, and $120, $12, $150, and $450 above that (OpenAI API pricing). GPT-6.1 Sol Ultrafast uses OpenAI’s published $12 input and $60 output; its cache rates are not listed, so Atomic derives them at six times Standard. GPT-5.6 Sol Ultrafast has no published rates, so Atomic prices it at six times Standard ($24 input, $120 output). With an API key, if OpenAI reports a Fast request as served at Standard, the usage is priced at Standard; with ChatGPT sign-in it is priced at the tier you chose. With ChatGPT sign-in, Codex counts Fast against included limits at 2.5x and Astra Ultrafast at 8x, and bills purchased credits at 2x and 6x. Atomic’s displayed cost uses the API rates.
Auto routing excludes Ultrafast unless modelConstraints.allowedModels explicitly lists its exact provider/model ID. When explicitly allowed, it uses base-model benchmark evidence without an additional latency bonus. Normal and Fast choices keep their existing automatic selection behavior. Pick a fast identity only when the latency reduction is worth the higher usage and price.
Fast models
Fast inference is a model choice, not a mode. Where a provider supports it, Atomic adds a second selectable model whose canonical ID is the base model ID plus-fast — for example openai-codex/gpt-5.6-sol-fast. It appears in /model, in atomic --list-models, and in workflow model catalogs alongside its normal sibling, and it is persisted and restored by that exact ID. Select it anywhere you name a model, including with a thinking suffix: openai-codex/gpt-5.6-sol-fast:medium.
Four provider paths produce these variants:
- First-party OpenAI
openai/*and OpenAI Codexopenai-codex/*models that advertise Fast (see Fast and Ultrafast tiers) send the base upstream model ID plus the fixedservice_tier: priority. A renamed provider, proxy, Azure OpenAI, OpenRouter, or generic OpenAI-compatible provider does not receive a synthetic fast variant. - First-party xAI
xai/*models get a fast variant for every Grok model, such asxai/grok-4.7-fast. It sends the base upstream model ID with xAI’s Priority Processingservice_tier: priority. xAI has no separate-fastmodel IDs for current Grok models. OpenRouter, Vercel AI Gateway, and renamed or proxied xAI-compatible providers do not receive a synthetic fast variant. - First-party Anthropic
anthropic/*exposes fast mode for Claude Opus 5.5, Claude Opus 5, and Claude Opus 4.8:anthropic/claude-opus-5-5-fast,anthropic/claude-opus-5-fast, andanthropic/claude-opus-4-8-fast. Each sends the base upstream model ID withspeed: "fast"and thefast-mode-2026-02-01beta header. It works with API keys and Claude subscription logins. Amazon Bedrock, Google Vertex, GitHub Copilot, OpenRouter, and renamed or proxied Anthropic-compatible providers do not receive a synthetic fast variant. - GitHub Copilot exposes only the real fast sibling IDs the OAuth model catalog advertises for the signed-in account, and only when the corresponding base model exists in Atomic’s Copilot catalog. It sends those suffixed IDs verbatim with no OpenAI service-tier field. Copilot fast models require the account catalog metadata obtained through
/login; a rawCOPILOT_GITHUB_TOKENdoes not provide that metadata.
-fast identity even when the outbound request carries the base upstream model ID, so sessions, usage rows, fallback attempts, workflow metadata, and subagent labels all keep normal and fast apart. There is no separate fast badge anywhere in the UI: the model ID already says it.
A fast variant’s route owns two request fields: the upstream model ID and the service tier (speed for Anthropic). A before_provider_request hook may rewrite anything else, but replacing the payload with a non-object or changing either route-owned field is refused with an error naming the model and the remedy, because a model recorded, persisted, and billed as -fast must not go out as a different model or at an ordinary tier. Select the normal sibling instead when a request needs different routing. A model without a fast variant keeps unrestricted hook freedom, and an explicit per-request service tier still applies to it without granting fast-model identity.
Models served by an extension’s own stream function, including native provider registrations, do not get automatic fast variants. Their normal models and custom transport remain available.
Fast behavior comes from explicit route metadata attached when the variant is derived, never from the -fast or -ultrafast suffix. If a provider, a models.json custom model, or an extension already defines that exact variant ID, that model wins: it routes exactly as declared, Atomic suppresses the derived duplicate, and startup and --list-models name the collision. No synthetic variant is derived for Azure OpenAI, OpenRouter, or generic OpenAI-compatible providers. Ultrafast derivation is restricted to first-party OpenAI and Codex models that advertise the tier; an extension-owned transport does not get it.
Provider-owned names ending in -fast remain ordinary exact IDs. Vercel AI Gateway advertises openai/gpt-6-astra and openai/gpt-6-astra-fast; OpenRouter advertises openai/gpt-6-astra and openai/gpt-6-astra-pro. Their catalog prices and routing apply, not Atomic’s first-party fast routing. Check the live catalog before selecting one.
First-party Codex variants keep their exact priority or ultrafast routing across retries and transport changes. Renaming a provider or setting a service tier on a normal model does not grant variant identity.
Pick fast variants deliberately in workflows: parallel fan-out multiplies provider usage, and priority-tier requests are billed at a higher rate.
Anthropic fast mode delivers up to 2.5x higher output tokens per second at twice the standard token rates, with prompt-caching multipliers applied on top. Atomic prices each response by the speed Anthropic reports in its usage. Fast mode has its own rate limit; when it is exhausted Anthropic returns 429, which Atomic retries like any other rate limit rather than silently falling back to standard speed. Switching between a fast and a normal Claude model invalidates the prompt cache.
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. Run/login anthropic and choose subscription authentication. Browser login (default) uses a local callback and still accepts a pasted redirect URL. Choose Copy code login (headless) when your browser runs on another machine: complete sign-in in that browser, then paste the code#state value Anthropic displays into Atomic. This method does not need a reachable local callback.
Browser login tries loopback port 53692 first and uses a free port if it is unavailable. For SSH or container port forwarding, forward 53692 when it is free; otherwise use Copy code login (headless) or paste the final redirect URL.
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.
Anthropic workload identity federation
With no Anthropic key, bearer token, or login configured, Atomic uses workload identity federation whenANTHROPIC_FEDERATION_RULE_ID, ANTHROPIC_ORGANIZATION_ID, and ANTHROPIC_IDENTITY_TOKEN_FILE are all set. The Anthropic SDK exchanges the identity token for a short-lived access token and refreshes it, re-reading the token file each time, so keep that file fresh in long sessions. ANTHROPIC_SERVICE_ACCOUNT_ID and ANTHROPIC_WORKSPACE_ID are sent when set.
Keys, ANTHROPIC_AUTH_TOKEN, and custom authorization headers take precedence. Federation applies only to the anthropic provider, not to other Anthropic-compatible providers.
GitHub Copilot
- Press Enter for github.com, or enter your GitHub Enterprise Server domain
COPILOT_GITHUB_TOKENis read as an API key when you prefer an environment variable over/login- Models come from the bundled
pi-aiGitHub 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”
github-copilot/gpt-6.1-sol. Select it with atomic --model github-copilot/gpt-6.1-sol:high. It uses Copilot’s Responses endpoint and supports low, medium, high, xhigh, and max, not off or minimal.
Copilot metadata lists a 1,050,000-token context, 922,000-token input limit, and 128,000-token output limit; account policy still controls availability. Copilot Fast choices require exact account advertisement. Codex’s Ultrafast service tier does not apply to Copilot.
Atomic includes a provisional github-copilot/gpt-6-astra entry routed through Copilot’s Responses endpoint. Until Copilot publishes metadata, it uses Astra’s known text/image capabilities, 272,000 default context, 128,000 output limit, and low through max reasoning. Zero catalog costs mean Copilot pricing is unknown, not free. Copilot metadata takes precedence when present, and the OAuth account catalog still controls availability. This entry does not guarantee that Copilot has enabled Astra for your account.
github-copilot/gpt-6-astra-fast appears only when the OAuth account catalog advertises that exact fast ID. It sends gpt-6-astra-fast unchanged with no service_tier, unlike first-party OpenAI’s priority route. A raw COPILOT_GITHUB_TOKEN cannot supply that fast entitlement.
Endpoint routing for COPILOT_GITHUB_TOKEN
OAuth logins get their Copilot host from the token GitHub issues during login. Environment-token auth has no such exchange, so Atomic resolves the host itself, highest precedence first:
COPILOT_API_TARGET, thenGITHUB_COPILOT_BASE_URL— an explicit host or full URL- the
proxy-ep=segment embedded inCOPILOT_GITHUB_TOKEN GITHUB_SERVER_URL—<tenant>.ghe.comroutes tocopilot-api.<tenant>.ghe.com; any other non-github.comhost routes tohttps://api.enterprise.githubcopilot.comhttps://api.githubcopilot.com, the public routing hub, which resolves your plan’s host server-side
models.json provider baseUrl for github-copilot overrides all of the above. Without COPILOT_GITHUB_TOKEN the provider is left exactly as upstream pi-ai defines it.
Chat requests authenticated with a raw COPILOT_GITHUB_TOKEN, including github_pat_, ghp_, gho_, and ghu_ tokens, send Copilot-Integration-Id: copilot-developer-cli. A header supplied through models.json, modelOverrides, or per request takes precedence, including vscode-chat. Exchanged OAuth tokens containing tid= keep their OAuth headers.
Business and enterprise tokens sent to the individual host return 421 Misdirected Request; if you see that, set COPILOT_API_TARGET to the host your organization issues.
xAI (Grok/X subscription)
Run/login xai, then select Use a subscription. XAI_API_KEY remains available through Use an API key.
Atomic defaults xAI sessions to grok-4.7. GitHub Copilot also exposes Grok 4.7 when the account’s model policy enables it. Network-backed catalogs refresh and cache these newer entries independently of the bundled catalog snapshot.
xai/grok-4.7-fast and the other xai/*-fast choices request xAI Priority Processing for lower time-to-first-token and faster streaming. xAI bills priority at twice the standard token rates, and only when the response confirms the priority tier. When priority capacity is unavailable, xAI serves the request at the default tier and Atomic prices it at the standard rate.
Builtin workflows and subagents default to model: "auto", selecting an available model and supported effort for each task rather than using fixed role models or shipped fallback chains. This does not change your main-chat model. To choose the decision provider, use /settings → Router model. For explicit child models, fallback lists or provider restrictions, see Subagent reference and builtin workflow model options.
Meta (Muse subscription)
Run/login meta, then select Sign in with Meta to open the device authorization flow. The login mints a Model API key that is re-minted automatically about once a day. META_API_KEY remains available through Use an API key.
Radius
Radius is a dynamicpi-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.
Once a fetched or cached Radius catalog is available, it replaces the bundled defaults. Models disabled by your organization no longer appear; an empty gateway catalog leaves no Radius models to select. Ask your organization owner to enable models if the list is empty.
OpenRouter
Authenticate with/login openrouter or OPENROUTER_API_KEY.
With a key, Atomic lists only the OpenRouter chat models that key may use, with the key’s context size, max output, and prices. These come from OpenRouter’s /models/user endpoint and reflect guardrails and provider restrictions set in OpenRouter. Image and classifier models are not filtered.
Atomic refreshes the list in the background at interactive startup, when /model opens, after /login, and on atomic update --models. The last list is saved and used offline, in atomic -p, and in RPC mode. If you switch keys outside /login, the previous key’s list stays until the next refresh. A session saved with a model that the current key does not list still restores.
Regional endpoints filter models to their region. To use one, set the base URL in models.json:
/models/user or does not have that endpoint, for example a proxy configured as the OpenRouter base URL, Atomic lists every OpenRouter model.
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:
/model to use the authenticated cached snapshot immediately. Catalog refresh runs in the background with a 15-second deadline and falls back to cached models if the provider is slow or unavailable.
Logout returns without waiting for catalog refresh. Models can remain available if an environment variable or runtime key still authenticates the provider; remove that source separately. Earlier refreshes cannot undo a later login or logout.
On remote or headless machines, paste the authorization code or final redirect URL when the login prompt offers manual entry. A completed exchange returns to the editor or shows an error; it does not require deleting ~/.atomic or migrating existing OAuth credentials.
Catalog failures preserve the last usable models for each provider. See catalog freshness and precedence.
Z.AI and Z.AI Coding Plan (China) default to
glm-5.3 (zai/glm-5.3 and zai-coding-cn/glm-5.3), and both direct providers also expose the multimodal glm-5.3-flash. Baseten defaults to its directly selectable zai-org/GLM-5.3 and also exposes zai-org/GLM-5.3-Fast and the multimodal zai-org/GLM-5.3-Flash; OpenRouter exposes z-ai/glm-5.3 and z-ai/glm-5.3-flash. The full and Flash entries support low, high, and max reasoning; Baseten’s Fast entry also supports off. Use Baseten’s zai-org/GLM-5.2 or zai-org/GLM-5.3-Fast when fully disabled reasoning is required. Qwen Token Plan Individual defaults to qwen3.8-max and uses the international QWEN_TOKEN_PLAN_API_KEY shared with the existing Qwen Token Plan provider. These catalogs follow their upstream providers, so use --list-models for the current entries.
Xiaomi MiMo reasoning models on xiaomi and all three xiaomi-token-plan-* providers support only off (thinking disabled) and high (thinking enabled). Use these levels when selecting thinking; Xiaomi does not distinguish intermediate effort levels.
Kimi For Coding (kimi-coding) uses OpenAI Chat Completions at https://api.kimi.com/coding/v1. If a models.json override sets its baseUrl, include the /v1 suffix. Kimi Code models always think, so off is not a selectable thinking level.
Use the table above for environment-variable and auth.json names.
Auth File
Store credentials in~/.atomic/agent/auth.json:
qwen-token-plan-individual uses the same international endpoint and QWEN_TOKEN_PLAN_API_KEY as
qwen-token-plan, but limits the picker to the models documented for Individual subscriptions. The existing
provider keeps its broader catalog for backward compatibility. When using auth.json, store the credential
under the provider you select; an environment variable is shared by both international providers.
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:
Key Resolution
Thekey 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) - Environment interpolation:
"$ENV_VAR"or"${ENV_VAR}"uses the value of the named variable. Interpolation works inside larger literals.$FOO_BARis the variableFOO_BAR; use${FOO}_BARwhenBARis literal text. Missing environment variables make the value unresolved. - Escapes:
"$$"emits a literal"$";"$!"emits a literal"!"without triggering command execution. - Literal value: Used directly
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.
Provider Specific Config
The providers below have additional setup, need additional settings, or can use credentials supplied by their platform.NVIDIA NIM
NVIDIA’s built-in default isnvidia/nemotron-3.5-super-vl-120b-a12b. Saved and explicit model choices still take precedence. To select this model explicitly:
--list-models or /model to check the current catalog and replace a missing saved model. A catalog listing does not verify account access or serving availability.
Azure
Use theazure provider for OpenAI Responses models and Microsoft Foundry Chat Completions models, including azure/deepseek-v4-pro. The provider ID azure is the key in auth.json, models.json, and settings.json, and the prefix in model references:
low, medium, and high reasoning effort. Azure OpenAI models keep the azure-openai-responses API ID; Chat Completions models use openai-completions.
AZURE_OPENAI_API_VERSION configures Responses requests and defaults to v1. Chat Completions uses the normalized /openai/v1 endpoint.
Deployment names default to model IDs. Set AZURE_OPENAI_DEPLOYMENT_NAME_MAP when your deployments have different names; it applies to both APIs without changing the model ID shown in sessions.
Custom Azure deployments in models.json or extension registrations default to the Responses API when no API is specified and the model ID is not in the catalog. Set api: "openai-completions" at the provider or model level to use Chat Completions, for example for a Foundry model that Atomic does not include. Custom models require a baseUrl; AZURE_OPENAI_BASE_URL and AZURE_OPENAI_RESOURCE_NAME take priority over it when set:
azure-openai-responses remains accepted in model selections, saved sessions, and SDK lookups. Startup renames that provider in auth.json, settings.json, and models.json, including legacy Pi configuration paths. Existing azure entries win on collisions. Project configuration is migrated only after the project is trusted; session files are not rewritten. Use azure in new configuration.
Amazon Bedrock
AWS_CONTAINER_CREDENTIALS_*) and IRSA (AWS_WEB_IDENTITY_TOKEN_FILE).
amazon-bedrock provider. Atomic passes the chosen ID unchanged to Bedrock Converse and sends the selected low, medium, high, xhigh, or max setting as the OpenAI reasoning_effort field. The unprefixed ID is Codex’s direct/Mantle entry; global. and us. are Bedrock Runtime inference profiles. Bedrock does not advertise Astra Fast, so Atomic derives no fast sibling for these models. AWS’s public region and pricing pages did not list Astra when this catalog entry was added. Availability can vary by account and region, and Atomic records zero catalog cost until AWS publishes an authoritative rate.
Other Bedrock GPT models receive the selected thinking level as reasoning.effort; minimal maps to low. GPT-oss uses reasoning_effort and maps minimal to low and xhigh or max to high. For a custom application inference profile, give the model a recognizable GPT name in models.json so the reasoning setting is sent.
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:
Cloudflare AI Gateway
CLOUDFLARE_API_KEY can be set via /login. The account ID and gateway slug must be set as environment variables.
/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:
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.
Workers AI binding (no API token)
When Atomic’s engine runs inside a Cloudflare Worker in the gateway’s own account, requests can route through the Workers AI binding (env.AI) instead of HTTPS. Binding calls are pre-authenticated in-account, so this path needs no CLOUDFLARE_API_KEY at all. Atomic re-exports the transport as createGatewayBindingFetch from @bastani/atomic.
Declare the binding and gateway slug. The binding channel carries the account identity, so this route does not need an account ID:
streamSimple swaps in the binding transport. The extension must be created where env is in scope — an inline extension factory passed to the resource loader does that:
fetch(). createGatewayBindingFetch forwards each request untouched to https://workers-binding.ai/ai-gateway/gateways/{gateway}/{provider}/.... baseUrl and gateway options are ignored. Methods, headers (including the auth sentinel), query strings, non-JSON bodies, request streams, and response streams retain native fetch semantics; Cloudflare’s gateway recognizes and strips the sentinel. Bindings that only expose gateway(id).run(...) are not supported. Repeat the same pattern with @bastani/pi-ai/api/openai-completions (or openai-responses), setting the model baseUrl to ${bindingPrefix}/openai (or ${bindingPrefix}/compat) for those provider routes.
Cloudflare Workers AI
CLOUDFLARE_API_KEY can be set via /login. CLOUDFLARE_ACCOUNT_ID must be set as an environment variable.
x-session-affinity for prefix caching discounts.
Workers AI also lists Cloudflare’s Clef (@cf/cloudflare/clef) and Clef Flash (@cf/cloudflare/clef-flash) as classifiers. They use the same CLOUDFLARE_API_KEY and CLOUDFLARE_ACCOUNT_ID. Name the exact ID in routerModel, structured_output, or generateStructuredOutput(); like other classifiers they do not appear in /model or work with --model. See Structured decisions.
Google Vertex AI
Uses Application Default Credentials: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.
TypeSafe Jev
typesafe/jev-latest and typesafe/jev-1.14.0 are the built-in TypeSafe classifiers. jev-latest follows TypeSafe’s latest stable Jev; jev-1.14.0 pins Jev 1.14. Name one explicitly in compactionModel, routerModel, structured_output, or generateStructuredOutput() when you want it. An unset or auto compaction model or router uses the current chat model; saved credentials do not select a classifier. Jev is never an execution auto candidate, chat --model, or /model choice. Any other classifier works the same way only when the current model registry lists it. A models.dev listing does not register a classifier. See Compaction model for verbatim classifier compaction.
Both direct TypeSafe classifiers turn on TypeSafe’s long-context and image previews for every request, so they accept up to 262K tokens and PNG or JPEG images in images. Long requests are slower and less accurate than requests within TypeSafe’s default 64K. Each image must be 280 to 1568 pixels per side. Atomic adds an images field to the state that lists the images in order, so questions can refer to `images` or `images[0]`; a state with its own images field cannot send images. TypeSafe marks images as a preview whose format and accuracy can change.
Use /login typesafe to save an API key under typesafe in auth.json, or set TYPESAFE_API_KEY in Atomic’s process environment. Stored credentials take precedence over the environment key. /logout typesafe removes the saved TypeSafe credential; an environment key remains active until you unset it. Jev appears in /login but not /model, because it only makes structured decisions. Do not put the key in prompts, decision state, or settings.json.
Atomic also registers vercel-ai-gateway/typesafe-ai/jev, opencode/jev-1.13, and opencode/jev-1.13-free as classifiers. Use the corresponding gateway’s credentials (AI_GATEWAY_API_KEY or /login vercel-ai-gateway; /login opencode for Zen) and name the exact ID. They do not appear in the chat model selector. Gateway Jev uses its TypeSafe endpoint, not Chat Completions, keeps the gateway’s own context limit, and does not accept images. The old openrouter/~typesafe/jev-latest ID remains unregistered.
An explicit routerModel other than auto selects that exact registered chat or classifier model for workflow-stage and subagent model: "auto" routing. An unset or auto router uses the current chat model. General generateStructuredOutput() calls and the structured_output tool select their own model: an optional exact model, then fallbackModels, then the current chat model. Those calls resolve the ID through the current model registry and use the generic classify operation for a registered classifier, including typesafe/jev-latest. They do not inherit routerModel. A catalog entry does not prove that classify is available or entitled. User-issued /workflow commands launch directly.
Routers send one classify request for a registered classifier and can repair a malformed chat answer up to three times after the initial attempt, all within one structured-decision deadline taken from httpIdleTimeoutMs. Cancel the request to stop sooner; independent provider and enclosing tool-request limits still apply. A structured_output or generateStructuredOutput() classifier candidate is skipped, not repaired into a free-form value, when the schema is not a finite Choice. Missing credentials, an unavailable provider, an unsupported classify operation, a provider size rejection, a refusal, and a malformed classifier answer switch routing to the current chat model and advance a general structured-output chain. Cancellation does not. See structured decision limits.
HTTP 401 means check the key saved through /login typesafe or TYPESAFE_API_KEY, 422 means check the question/state contract, and 429 or 529 means wait before retrying explicitly. Configured credentials do not verify access or quota. See TypeSafe’s API and Choice reference.
Morph compaction
Use/login morph to save a Morph API key under morph in ~/.atomic/agent/auth.json, or set MORPH_API_KEY in Atomic’s process environment. Stored credentials take precedence over the environment key. Do not put the key in prompts or settings.json.
Then choose morph/morph-compactor through /settings → Compaction model, or set "compactionModel": "morph/morph-compactor" in global settings. Without credentials, the selector marks it as requires /login morph. Morph receives the compactable transcript, including serialized thinking; the preserved recent tail is not sent. Atomic retains the original surviving lines and enforces <keepContext> protection. Choose Morph only if it is permitted to receive your transcript.
Morph is a compactor, not a chat model. It does not appear in /model or automatic model routing. Missing credentials, HTTP errors, policy refusals, or unusable results advance directly to your configured fallback models without a Morph summary request. /logout morph removes the saved credential; an environment key remains active until you unset it. See Compaction model.