Setup helper

Use the official AtmoRouter helper to configure coding agents, get IDE setup instructions, find model IDs, and check an API key without running inference. It previews automatic configuration changes and backs up existing settings. The optional Codex bridge runs only when explicitly started and forwards normal paid inference.

Run the helper

Install Node.js 22 or newer, then run this command in your terminal. No npm account or repository access is required.

npx @atmorouter/helper

The official npm package is @atmorouter/helper. Use npx @atmorouter/[email protected] to select version 0.2.3 explicitly. Version 0.2.3 includes post-setup Budgets and retry guidance. The same package is available from the versioned website archive below.

Download the package · SHA-256 checksum

Choose a model and preview a connection

Replace YOUR_MODEL_ID with an ID returned by the models command:

npx @atmorouter/[email protected] models --search claude
npx @atmorouter/[email protected] configure --target opencode --model YOUR_MODEL_ID
npx @atmorouter/[email protected] configure --target claude --model YOUR_MODEL_ID --write

The wizard lists live text models and previews a plan. Configuration files are written only after confirmation or an explicit --write --yes. Existing JSON or YAML settings are merged and changed files get a timestamped backup. Malformed documents, JSONC, and ambiguous existing configuration require a manual merge.

Keep credentials in your environment

The helper does not print or save your API key. Set ATMOROUTER_API_KEY using your shell or secret manager. OpenCode reads that variable. For Claude Code, also set ANTHROPIC_AUTH_TOKEN to the same key before launching the agent.

# POSIX shell; set ATMOROUTER_API_KEY privately first
export ANTHROPIC_AUTH_TOKEN="$ATMOROUTER_API_KEY"

# PowerShell
$env:ANTHROPIC_AUTH_TOKEN = $env:ATMOROUTER_API_KEY

# Optional zero-inference key check (uses the environment, never a key argument)
npx @atmorouter/[email protected] check-key

GET /v1/models has a public catalog response and adds private combos for a valid owner key; ordinary catalog entries alone cannot validate a key. The explicit key check sends an empty Chat Completions body: a valid active key is rejected locally with HTTP 400 “model is required”, before model lookup, billing, or upstream inference. An invalid key returns 401. A 429 is inconclusive; wait and try later.

Troubleshooting and restoring settings

Use --version to check the installed version and --help to list commands. A network error means the catalog or gateway could not be reached. Invalid JSON, JSONC, or existing credential settings require a manual merge; the helper leaves those files unchanged. To undo an applied change, stop the agent and restore its timestamped .atmorouter-backup-* file after preserving any later edits. For support, share the helper version, agent version, model ID, and error message; never share a key or an unredacted settings file.

Automatic configuration

Targets claude, opencode, omp (Oh My Pi), and continue merge their JSON or YAML configuration. Oh My Pi uses ~/.omp/agent/models.yml with api: openai-completions and an environment variable name for the key. Continue uses ~/.continue/config.yaml; manually set its ATMOROUTER_API_KEY secret in ~/.continue/.env for the IDE. The helper writes a secret reference and never writes the key. Targets openai and anthropic print shell snippets.

npx @atmorouter/[email protected] targets
npx @atmorouter/[email protected] configure --target omp --model YOUR_MODEL_ID
npx @atmorouter/[email protected] configure --target continue --model YOUR_MODEL_ID

Guided IDE setup

Targets cursor, vscode, cline, and roo print steps for your client UI. Cursor custom keys apply to Chat, not Tab completion; use its OpenAI base URL override where available. In VS Code Copilot Chat, use Manage Language Models → Add Models → Custom Endpoint; the older OpenAI Compatible setting is deprecated. Cline and Roo use OpenAI Compatible, and Roo requires native tool calling from the model. Enter credentials in each client's own settings.

antigravity prints an unsupported-integration diagnostic. Antigravity's native IDE has no documented custom endpoint or authenticated SDK path suitable for this helper; it is not listed as compatible.

Codex through a local bridge

The public gateway does not implement /v1/responses. The optional helper bridge listens on localhost and translates a limited Responses subset to Chat Completions. Set ATMOROUTER_API_KEY, then explicitly launch it:

# Print setup instructions only
npx @atmorouter/[email protected] configure --target codex --model YOUR_MODEL_ID

# Launch your installed Codex CLI with a temporary localhost bridge
npx @atmorouter/[email protected] codex --model YOUR_MODEL_ID

# Or start a standalone bridge and follow its printed instructions
npx @atmorouter/[email protected] bridge --port 43187

The bridge supports stateless text, function tools, and streaming. Unsupported built-in tools and stateful Responses features are rejected; complete Responses compatibility, images, and audio are not promised. The launcher disables hosted web search for this run and preserves Codex permission defaults. Reasoning summaries and encrypted reasoning output are unavailable. Calls are billed normally to your AtmoRouter key. Previewing configure --target codex does not start a server or write settings.

Client documentation

Cursor API keys · VS Code language models · Oh My Pi · Continue secrets · Cline · Roo Code

Set a price budget before using your client

The setup helper configures your client; it does not create or change price budgets. After automatic setup, a preview, manual IDE configuration, or bridge setup, open Budgets dashboard. Select the actual API key used by the client and save an all-model percentage rule for broad coverage. Illustrative examples only: 20% below official rates or 50% below official rates; review the rates and choose your own limit. A family or exact-model rule provides narrower coverage. Account and key rules both apply; the strictest input and output limits win. Client setup and key checks do not prove that an offer is currently available within your limits.

Market prices and tiers vary. A “From” price is a snapshot of the cheapest advertised offer, not a guaranteed execution price. Routing can wait up to 30 seconds for capacity within your caps. This wait is fixed; generation time is additional. Allow time for both in your client timeout. The local bridge defaults to a 120-second total timeout.

Handle waiting and retries in your harness

For 429 or temporary availability failures, honor Retry-After when present; otherwise use bounded exponential backoff with jitter. Avoid blind retries and duplicate in-flight requests. After a timeout or interrupted stream, review the client outcome and usage before deciding to resend. Never raise price caps automatically.

Correct invalid requests before retrying. For authentication errors, check the key and account eligibility. For insufficient balance, review Billing; adding funds does not fix pricing availability. A price_limit_unavailable refusal calls for waiting for capacity within your caps or deliberately reviewing your budget. See Budgets for price limits and Errors & retries for error-specific actions.