OpenCode

OpenCode is an open-source terminal coding agent. It reaches the AI Gateway as a custom OpenAI-compatible provider, so one access key covers every model you add to its config.

What you’ll need

OpenCode installed.
An access key from app.ngrok.ai.

Add the gateway as a provider

Export your access key so OpenCode can read it:

export NGROK_AI_GATEWAY_KEY="ng-xxxxx-g1-xxxxx"

Add the gateway as a provider in ~/.config/opencode/opencode.json, or in an opencode.json beside your project:

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "ngrok": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "ngrok AI Gateway",
      "options": {
        "baseURL": "https://gateway.ngrok.ai/v1",
        "apiKey": "{env:NGROK_AI_GATEWAY_KEY}"
      },
      "models": {
        "gpt-5.5": {
          "name": "GPT-5.5 (via ngrok)",
          "limit": { "context": 1050000, "output": 128000 }
        },
        "claude-sonnet-5-5": {
          "name": "Claude Sonnet 5.5 (via ngrok)",
          "limit": { "context": 1000000, "output": 128000 }
        }
      }
    }
  }
}

Each key in models is the model name OpenCode sends to the gateway. Use any model ID from the model catalog, or provider:model to pin a provider. The limit values are optional, but they let OpenCode track how much context is left.

Test the connection

Start OpenCode, run /models, and pick one of the models under ngrok AI Gateway. Or send a single prompt from the command line:

opencode run -m "ngrok/gpt-5.5" "Explain what a hash map is in two sentences."

The -m value is your provider ID, a slash, then the model key from opencode.json. Confirm the request in AI Gateway observability in app.ngrok.ai.

Use a model you run yourself

To reach a model on your own machine, register it as a custom provider, then add its provider:model name to models, such as ollama:llama3.2. See Use a model you run yourself for the full setup.

Next steps

Restrict providers and models: Scope what an access key can call
Configure fallback models: Try another model when the first one fails
Observability: See which model served each request

Concepts

Getting Started With

SDKs

Agents

Guides

Observability

Examples

Reference

API Reference

What you’ll need

Add the gateway as a provider

Test the connection

Use a model you run yourself

Next steps

​What you’ll need

​Add the gateway as a provider

​Test the connection

​Use a model you run yourself

​Next steps

What you’ll need

Add the gateway as a provider

Test the connection

Use a model you run yourself

Next steps