OpenCode with AtmoRouter: Custom Provider Setup Guide

To use AtmoRouter in OpenCode, add a custom OpenAI-compatible provider with the base URL https://atmorouter.dev/v1. Keep its API key in an environment variable and register the model IDs you want to select.

This guide assumes OpenCode is already installed. Its official provider documentation describes custom providers and their configuration fields.

Choose your model before editing configuration

Create an AtmoRouter key in API Keys, then copy a model ID from Models. Use the full ID, including the family prefix. Check the model's context and suitability for tool-based tasks before selecting it for an agent session.

For this guide, replace MODEL_ID_FROM_CATALOGUE in the JSON below with that exact ID. It is a placeholder, not a model that can receive requests.

Make the key available to OpenCode

Set an environment variable in the terminal that will start OpenCode. These examples use placeholders; substitute your own key privately.

bashexport ATMOROUTER_API_KEY="YOUR_ATMOROUTER_API_KEY"

In PowerShell, the equivalent is:

powershell$env:ATMOROUTER_API_KEY = "YOUR_ATMOROUTER_API_KEY"

An environment variable set this way belongs to the current shell and its child processes. Starting OpenCode from a different terminal or desktop launcher may not inherit it. Avoid putting the real key in a configuration file tracked by Git.

Add the provider

Merge this provider entry into your existing opencode.json configuration. Preserve other providers, settings and credentials. If you use JSONC, edit the existing JSONC file rather than creating a competing JSON configuration without checking which one will be loaded.

json{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "atmorouter": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "AtmoRouter",
      "options": {
        "baseURL": "https://atmorouter.dev/v1",
        "apiKey": "{env:ATMOROUTER_API_KEY}"
      },
      "models": {
        "MODEL_ID_FROM_CATALOGUE": {
          "name": "My AtmoRouter model"
        }
      }
    }
  }
}

The adapter choice is deliberate: this configuration targets Chat Completions. OpenCode's documentation distinguishes the OpenAI-compatible adapter from an adapter used for Responses-based integrations. Do not switch transports just because a model has a familiar name.

Select the model and verify one task

Start OpenCode from the terminal containing your environment variable. Use /models and select the entry under AtmoRouter. Test a short explanation, then a small file-reading task in a disposable project.

Check Usage logs after the test. Confirm that the expected model received the request and inspect its timing and cost. If no request appears, investigate the local client configuration and environment before assuming an inference problem.

Common mistakes

• Provider appears but requests fail authentication: the process may not have inherited ATMOROUTER_API_KEY, or the key may have been revoked.
• Model not found: replace the JSON placeholder with an exact catalogue ID.
• Unexpected API route: keep this provider on the Chat Completions adapter and use the /v1 base.
• Text works but tools fail: verify the chosen model's behavior with a minimal tool task before expanding the workflow.

The AtmoRouter helper can preview and write supported OpenCode configuration with backups. Review its proposed change first, especially if you maintain an existing configuration manually.

For a comparison of gateway choices, see OpenRouter vs AtmoRouter. For an editor extension, see Cline in VS Code.