Skip to content
Atomic Agent logo Atomic Agent docs

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-...).
  • Node.js 25.7.0 or newer.

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

Quick start

  1. Create a key at openrouter.ai/keys and add credits.

  2. Install Atomic Agent:

    Terminal window
    curl -fsSL https://atomicagent.io/install | sh

    On Windows:

    Terminal window
    irm https://atomicagent.io/install.ps1 | iex

  3. 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 providers panel in the TUI — 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": "or",
    "providers": [
      {
        "id": "or",
        "kind": "openrouter",
        "defaultChatModel": "qwen/qwen3-max"
      }
    ]
  }
}

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:

<stateDir>/.env
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",
    "providers": [
      { "id": "local", "kind": "llama-server" },
      {
        "id": "or",
        "kind": "openrouter",
        "defaultChatModel": "qwen/qwen3-max"
      }
    ]
  }
}

Switch between them mid-session from the providers panel without restarting the agent. 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 queries the live OpenRouter catalog from the command line, which is useful for finding a model by capability rather than by name:

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

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.
  • The local models wizard appears even though OpenRouter is configured. 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.