OpenCode Setup

Add a custom Flatrouter provider in OpenCode and call models over the OpenAI-compatible protocol.

OpenCode is an open-source coding agent that lets you configure custom model providers. Flatrouter connects over the OpenAI-compatible protocol — the approach OpenCode's docs describe for compatible third-party services. For provider fields and the /connect flow, treat the OpenCode provider docs as the source of truth.

Requirements

OpenCode installed and able to start
A Flatrouter account and an API key (get one here)
The full model ID you want, confirmed in the Flatrouter model catalog

How to connect

The recommended path is a custom flatrouter provider over the OpenAI-compatible protocol. That lets you pin the endpoint, API key and the models that should show up in OpenCode.

Protocol	Base URL	When to use it
OpenAI-compatible (recommended)	`https://api.flatrouter.com/v1`	Adding a custom provider and models in OpenCode
Native Anthropic	`https://api.flatrouter.com/anthropic`	Only when you use Anthropic's native provider

Keep the protocol matched

The full example below uses the OpenAI-compatible protocol, so the package is @ai-sdk/openai-compatible and the base URL must be https://api.flatrouter.com/v1. Do not put the Anthropic endpoint in this config.

Setup

Step 1: put the API key in an environment variable

Store the Flatrouter API key in an environment variable so it never lands in a config file or a git repo:

export FLATROUTER_API_KEY="your Flatrouter API key"

OpenCode can read env vars with {env:VAR_NAME}. Make sure the variable is set in the session before you reopen the terminal or start OpenCode.

Step 2: add credentials with `/connect` (optional)

In OpenCode, type /connect, pick Other in the provider list, enter a unique provider ID such as flatrouter, then paste the API key when prompted.

That is OpenCode's official interactive path for a custom compatible provider. If you want an explicit model list, endpoint and default model, still finish the opencode.json step below.

Step 3: configure the custom provider

Add this to the opencode.json OpenCode uses. If the file already exists, merge the flatrouter entry under provider — do not wipe other providers.

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "flatrouter": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "flatrouter",
      "options": {
        "baseURL": "https://api.flatrouter.com/v1",
        "apiKey": "{env:FLATROUTER_API_KEY}"
      },
      "models": {
        "<full model ID>": {
          "name": "Flatrouter model"
        }
      }
    }
  }
}

Replace <full model ID> with the complete ID copied from the Flatrouter model catalog. Do not shorten, rewrite or guess IDs. To add more models, keep adding keys under models.

Step 4: set a default model (optional)

OpenCode refers to models as provider/model-id. To make one of your Flatrouter models the default, add a top-level model in the same file:

{
  "model": "flatrouter/<full model ID>"
}

<full model ID> must match a key in the models object from the previous step. If you skip a default, pick the flatrouter model in OpenCode's model picker instead.

Step 5: verify

Start or restart OpenCode and check that the flatrouter provider and its models appear. Select one and send a short message such as "hi, reply connected". A normal reply usually means the API key, endpoint and model ID are right.

Adding models

Model IDs, tool calling, context length, price and availability change over time. Read the live data in the Flatrouter model catalog and paste the full ID as-is.

To add several models:

{
  "provider": {
    "flatrouter": {
      "models": {
        "<first full model ID>": {
          "name": "Model one"
        },
        "<second full model ID>": {
          "name": "Model two"
        }
      }
    }
  }
}

Model limits

OpenCode lets you set limit.context and limit.output on a model entry. Fill those in only when you can confirm the numbers from the catalog or the model vendor. Do not guess.

FAQ

Q: OpenCode cannot find the flatrouter provider or models

Check that opencode.json is valid JSON, that the provider ID is flatrouter, and that each model ID is a key under models. Restart OpenCode after edits, then reopen the model picker.

Q: Invalid API key or auth failure

Confirm FLATROUTER_API_KEY is set in the terminal session that launched OpenCode, and check the spelling of {env:FLATROUTER_API_KEY}. Copy the key again from the Flatrouter console, with no extra spaces or newlines.

Q: Requests hit the wrong endpoint or throw a protocol error

OpenAI-compatible config must use both @ai-sdk/openai-compatible and https://api.flatrouter.com/v1. Use https://api.flatrouter.com/anthropic only with Anthropic's native provider. Do not mix the two.

Q: The model ID is filled in but the model will not run

Confirm the ID came from the Flatrouter model catalog and was copied in full. Also check that the model is available on your account, and that quota, permissions or a temporary outage are not blocking it.

Q: Does the API key get written into opencode.json?

This setup uses {env:FLATROUTER_API_KEY}, so the key itself is not stored in the JSON. Do not commit a file that contains a real API key.

Q: Should I use /connect or opencode.json?

/connect is the fast interactive path. opencode.json is better when you want a precise endpoint and model list. If you use both, keep the provider ID, API key and model config in sync.

On this page