OpenCode

Add HopBase to OpenCode as a custom OpenAI-compatible provider in opencode.json.

OpenCode is an open-source coding agent for the terminal. It reaches HopBase through a custom provider in opencode.json, built on the @ai-sdk/openai-compatible package.

Setting	Value
`npm`	`@ai-sdk/openai-compatible`
`options.baseURL`	`https://api.hop-base.com/v1`
`options.apiKey`	`{env:HOPBASE_API_KEY}` (a key from the console)
Model ID	The exact ID returned by `GET /v1/models` for that key, such as `deepseek-v4.1-flash-1017`

Verified in production with OpenCode 1.19: opencode run replies through HopBase, and the agent's built-in tools (such as reading a file) work.

Pick the group that contains your model.

A HopBase key reaches only the models of the groups it includes. When you create the key in the console, select the group that serves the model you want — for example DeepSeek for deepseek-v4.1-flash-1017, DeepSeek Singapore Data Center for deepseek-v4.1-flash-1017-sg, or Gemini (all models, incl. image) for gemini-3.8-flash. A key without the model's group returns 404 model_not_found.

Configure OpenCode

Export the key

export HOPBASE_API_KEY=sk-your-key

{env:HOPBASE_API_KEY} in the config below reads the key from this variable, so the key never lands in a file you might commit.

Add the provider to opencode.json

Create or edit opencode.json in your project directory, or ~/.config/opencode/opencode.json to use it in every project:

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "hopbase": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "HopBase",
      "options": {
        "baseURL": "https://api.hop-base.com/v1",
        "apiKey": "{env:HOPBASE_API_KEY}"
      },
      "models": {
        "deepseek-v4.1-flash-1017": { "name": "DeepSeek V4.1 Flash" }
      }
    }
  },
  "model": "hopbase/deepseek-v4.1-flash-1017"
}

The keys under models must be exact HopBase model IDs. List only the models your key can reach; name is just the label OpenCode shows. model sets the default as <provider>/<model ID>.

Confirm the model list

curl https://api.hop-base.com/v1/models \
  -H "Authorization: Bearer $HOPBASE_API_KEY"

Every ID you listed under models must appear in this response. If one is missing, none of the key's groups serves it.

Send a first request

opencode run "Reply with exactly one word: pong"

opencode models hopbase lists the models OpenCode loaded from the provider. Inside the interactive UI, /models switches between them.

Adding more models

Add one entry per model ID under models. A key can include several groups, so one provider can carry models from all of them:

"models": {
  "deepseek-v4.1-flash-1017": { "name": "DeepSeek V4.1 Flash" },
  "deepseek-v4.1-flash-1017-sg": { "name": "DeepSeek V4.1 Flash (Singapore)" },
  "gemini-3.8-flash": { "name": "Gemini 3.8 Flash" }
}

Claude models use the Anthropic protocol rather than Chat Completions. For Claude, add a second provider with "npm": "@ai-sdk/anthropic" and the same baseURL (https://api.hop-base.com/v1; the package appends /messages itself), and use a key that includes a Claude group.

Prices for every model are on the pricing page.

Troubleshooting

Symptom	Cause
`401` on every request	`HOPBASE_API_KEY` is unset in the shell that launched OpenCode
`404 model_not_found`	The key does not include the model's group, or the ID under `models` is shortened. Re-read `GET /v1/models`
`route_not_found`	The key belongs to an image or video group with no chat endpoint
`opencode run` waits without output when called from a script	It also reads standard input. Redirect it, for example `opencode run "…" < /dev/null`

Next steps

Available models: find the model IDs available to a key
Vercel AI SDK: the same provider package used directly in your own code
Troubleshooting: look up an error message

On this page