# AtmoRouter — Setup helper

Source: https://atmorouter.dev/docs/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`](https://www.npmjs.com/package/@atmorouter/helper). Use `npx @atmorouter/helper@0.2.3` 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](https://atmorouter.dev/downloads/atmorouter-helper-0.2.3.tgz) · [SHA-256 checksum](https://atmorouter.dev/downloads/atmorouter-helper-0.2.3.tgz.sha256)

## Choose a model and preview a connection

Replace `YOUR_MODEL_ID` with an ID returned by the models command:

```
npx @atmorouter/helper@0.2.3 models --search claude
npx @atmorouter/helper@0.2.3 configure --target opencode --model YOUR_MODEL_ID
npx @atmorouter/helper@0.2.3 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/helper@0.2.3 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/helper@0.2.3 targets
npx @atmorouter/helper@0.2.3 configure --target omp --model YOUR_MODEL_ID
npx @atmorouter/helper@0.2.3 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/helper@0.2.3 configure --target codex --model YOUR_MODEL_ID

# Launch your installed Codex CLI with a temporary localhost bridge
npx @atmorouter/helper@0.2.3 codex --model YOUR_MODEL_ID

# Or start a standalone bridge and follow its printed instructions
npx @atmorouter/helper@0.2.3 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](https://cursor.com/help/models-and-usage/api-keys) · [VS Code language models](https://code.visualstudio.com/docs/agent-customization/language-models) · [Oh My Pi](https://github.com/can1357/oh-my-pi) · [Continue secrets](https://docs.continue.dev/customize/deep-dives/secrets) · [Cline](https://docs.cline.bot/provider-config/openai-compatible) · [Roo Code](https://docs.roocode.com/providers/openai-compatible)

## 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](https://atmorouter.dev/dashboard/budgets). 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](https://atmorouter.dev/docs/budgets) for price limits and [Errors & retries](https://atmorouter.dev/docs/errors) for error-specific actions.