OpenCode setup by hand

colabhive agents init writes this for you. Write it by hand when the configuration lives in a repository, is generated by other tooling, or you want a project-level opencode.json next to the code.

The provider block

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "colabhive": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "ColabHive",
      "options": {
        "baseURL": "https://api.colabhive.com/v1",
        "apiKey": "{env:COLABHIVE_API_KEY}",
        "timeout": 1200000
      },
      "models": {
        "<model id>": { "name": "Qwen3 Coder 30B-A3B AWQ (ColabHive)" }
      }
    }
  },
  "model": "colabhive/<model id>"
}

Field	Value
npm	@ai-sdk/openai-compatible — ColabHive speaks the OpenAI Chat Completions API
options.baseURL	https://api.colabhive.com/v1
options.apiKey	{env:COLABHIVE_API_KEY}, so the key stays in your environment and out of the file
options.timeout	1200000 (20 minutes). OpenCode aborts a request after 5 minutes by default, and the first answer of a model that is loading can take longer
models	One entry per model. The key is the model id from /v1/models; name is only the label OpenCode shows in its model picker
model	colabhive/<model id> to make it the default. Leave it out to pick the model inside OpenCode

Which identifier goes in models

Use the id of each entry in GET /v1/models: a UUID, and the one value that always routes to the right deployment.

Prefer the id over the name

/v1/models also returns a readable name (for example Qwen3 Coder 30B-A3B AWQ), and it is accepted as model too. But a label can be renamed; the id cannot. Put the id in the key and the name in the label, as above.

List the models and their ids:

curl -s https://api.colabhive.com/v1/models \
  -H "Authorization: Bearer $COLABHIVE_API_KEY" \
  | jq -r '.data[] | [.id, .name, .max_model_len, .max_model_len_source] | @tsv'

max_model_len_source is resident when a replica is serving that model now, and configured when no serving window is known — normally because none is serving, and the first request will wait for a load. colabhive agents models prints the same list as a table, warm models first.

Check that the model calls tools

Before pointing an agent at a model, send it one request with a tool and look for tool_calls in the answer:

curl -s https://api.colabhive.com/v1/chat/completions \
  -H "Authorization: Bearer $COLABHIVE_API_KEY" -H "Content-Type: application/json" \
  -d '{
    "model": "<model id>",
    "messages": [{"role": "user", "content": "How many bytes does README.md have? Use the tool."}],
    "tools": [{"type": "function", "function": {
      "name": "get_file_size",
      "description": "Return the size in bytes of a file in the repository.",
      "parameters": {"type": "object",
                     "properties": {"path": {"type": "string"}},
                     "required": ["path"]}}}],
    "max_tokens": 256
  }' | jq '.choices[0].message.tool_calls'

A list with one get_file_size call means the model can drive the agent's tools. null or [] means it answered in prose: try again once — choosing not to call a tool is a sampled decision — and pick another model if it keeps happening. colabhive agents doctor runs this same check against the configured default model.

Several models

Add more entries under models and switch between them from OpenCode. A common split is a larger model with a long window for the main agent and a smaller, faster one for short tasks such as titles and summaries; OpenCode lets you assign a model per agent in its agent section.