Use with OpenRouter

Atomic Agent runs local models by default. OpenRouter is the escape hatch for the moments a local model cannot carry the task: a very long context, harder reasoning, or a frontier model you want to compare against. One key reaches hundreds of models from dozens of vendors, and Atomic Agent ships OpenRouter as a first-class provider rather than a generic endpoint.

What you need

An OpenRouter account with credits and an API key (sk-or-...).
Atomic Agent installed (the prebuilt binary bundles its own runtime; Node.js 25.7+ is needed only when running from source).

You bring your own key. Atomic Agent never proxies your traffic through our servers.

Quick start

Create a key at openrouter.ai/keys and add credits.
Install Atomic Agent:
Terminal window
```
curl -fsSL https://atomicagent.io/install | sh
```
On Windows:
Terminal window
```
irm https://atomicagent.io/install.ps1 | iex
```
Prefer an app over the terminal? Get the Atomic Agent desktop app instead. It ships the agent inside, so you can skip the install command.
Launch the agent:
Terminal window
```
atomic-agent
```
In the first-run setup, choose Cloud models, then OpenRouter. Paste your key, pick a chat model from the live catalog, and pick an embedding model. The agent verifies the key before saving it.

That is the whole setup. To change models later, open the LLM tab (/llm) and use its Cloud pane, or run /model. The catalog is fetched from OpenRouter and cached for an hour, so the list reflects what is actually available rather than a bundled snapshot that goes stale.

Configure by hand

If you prefer editing config directly, add an OpenRouter provider to <stateDir>/config.json (default ~/.atomic-agent/config.json):

{
  "llm": {
    "activeTextProvider": "openrouter",
    "providers": [
      { "id": "local-llama", "kind": "llama-server" },
      {
        "id": "openrouter",
        "kind": "openrouter",
        "defaultChatModel": "qwen/qwen3-max"
      }
    ]
  }
}

Keep the { "id": "local-llama", "kind": "llama-server" } entry in providers. The setup wizard writes one; if your config has no llm block yet, add it as shown. It serves embeddings by default, and the config is rejected if activeEmbeddingProvider names a provider that is not in the list.

For the OpenRouter entry itself, kind: "openrouter" is all you need. The base URL defaults to https://openrouter.ai/api, and defaultChatModel falls back to openrouter/auto if you leave it out, so a minimal entry is two fields.

Where the key goes

Secrets never belong in config.json. Put the key in the OPENROUTER_API_KEY environment variable, or in <stateDir>/.env, which the agent creates with mode 0600:

OPENROUTER_API_KEY=sk-or-...

A shell variable wins over the .env file, and an apiKey written directly into a provider entry wins over both. The first-run wizard writes the .env entry for you.

Keeping local as the default

Cloud access does not have to replace the local-first setup. A common arrangement is to keep both providers configured and switch when a task needs the extra capability:

{
  "llm": {
    "activeTextProvider": "local-llama",
    "providers": [
      { "id": "local-llama", "kind": "llama-server" },
      {
        "id": "openrouter",
        "kind": "openrouter",
        "defaultChatModel": "qwen/qwen3-max"
      }
    ]
  }
}

Switch between them mid-session without restarting the agent: use the LLM tab’s Cloud pane, /llm provider <id>, or /model. This mirrors how the agent is used in practice: local for the ordinary majority of turns, OpenRouter for the ones that need a frontier model.

Browsing the catalog

atomic-agent models search searches your configured providers’ model lists from the command line, which is useful for finding a model by capability rather than by name:

atomic-agent models search "1m cache" --provider openrouter --limit 10 --refresh

--provider takes the provider’s id from config.json (the examples above use openrouter, which is also what the setup wizard writes). Without --refresh the search runs against the catalog snapshot bundled with the release; --refresh pulls the live catalog first.

App attribution

Requests carry attribution headers (HTTP-Referer, X-Title, X-OpenRouter-Categories) identifying Atomic Agent, which is how usage shows up on OpenRouter’s app rankings. The headers are set by the provider and are the same for every user; they carry no personal identifier and nothing about the content of your requests.

Troubleshooting

401 or “no auth credentials found”. The key is missing or not visible to the process. Check OPENROUTER_API_KEY in your shell, or the .env line, and remember the shell wins over .env.
402 or “insufficient credits”. OpenRouter is prepaid; add credits in the dashboard. Free-tier models are rate-limited rather than free-flowing.
A model in the catalog fails at request time. Some models are gated per account or per region. Pick another from the catalog; the list is what OpenRouter serves, not what your account is entitled to.
First-run setup opens when you do not want it. It only opens on a fresh install with no configured backend. To skip it anyway, start with atomic-agent tui --skip-llama-setup, or set ATOMIC_AGENT_TUI_SKIP_LLAMA_SETUP=1.

Models — the full provider reference, including the other cloud kinds.
Configuration — config precedence and the .env format.
Local-First — what stays on your machine and what does not.
Claude Sonnet 5.5 vs Opus 5.5: benchmarks and pricing for Claude models you can reach through OpenRouter.