Skip to main content

Coding agent quickstart

From nothing to OpenCode running against ColabHive.

Where your code runs, and what it costs

The agent and its tools run on your machine; the model runs on ColabHive, and every prompt the agent sends — including the code it read — goes to the model.

  • On the Starter plan the model is served from capacity ColabHive operates. To keep it on hardware you control, enroll your own nodes (Pro: up to 2, Team: up to 5, Enterprise: from 3, by contract) and set the account's node-eligibility policy to own_hardware_only — see the Data Protection API. With that policy, a model with no replica on your nodes is refused instead of being placed elsewhere.
  • Hosted capacity is billed per accelerator-hour: see Pricing.
  • Each API key has a request limit per minute set by the plan: 60 on Starter, 300 on Pro, 1,000 on Team. Past it the API answers 429 with Retry-After.

1. Get an API key​

Sign in to the Console with your Google account and create a key under Settings → API Keys. Keys start with hive_.

2. Install OpenCode and the ColabHive CLI​

curl -fsSL https://opencode.ai/install | bash      # or: npm install -g opencode-ai
pip install colabhive==0.11.0

The pinned version also upgrades an older colabhive you may already have; the colabhive command first shipped in 0.9.1.

3. Configure the agent​

export COLABHIVE_API_KEY='hive_...'
colabhive agents init

Without the export, init asks for the key and reads it without showing it. It then does four things:

  1. Reads your catalog from GET /v1/models: your own models plus the approved public catalog.
  2. Ranks the chat models: the ones with a replica serving right now first, then by the context window that replica actually runs. Models with a window under 32,768 tokens go last — a coding agent fills that quickly.
  3. Checks up to three candidates for real. Each gets a request with a tools definition and must return a well-formed tool_call; a model that answers in prose is asked once more. Among those that pass, it keeps the one that called the tool fastest — a model that acts rather than deliberates; see Choosing a model team. It does not pay a cold load just to compare once a warm model has passed.
  4. Writes the colabhive provider into ~/.config/opencode/opencode.json (or $XDG_CONFIG_HOME/opencode/opencode.json), with the chosen model first, a few more to switch to, and a request timeout of 20 minutes so OpenCode does not abort the first answer of a model that is still loading (its default is 5).

Real output of colabhive agents init 0.9.2, abbreviated: the rows for endpoints private to the account that ran it are left out. Your list depends on your catalog and on what is warm at that moment.

-> using COLABHIVE_API_KEY from the environment
-> reading the model catalog from https://api.colabhive.com
OK 67 models available, 13 with a replica serving now

  MODEL                                    STATE          WINDOW
  Qwen3 Coder 30B-A3B AWQ                  warm          222,272
  Qwen3.8-27B-FP8                          warm          127,552

-> checking Qwen3 Coder 30B-A3B AWQ
OK Qwen3 Coder 30B-A3B AWQ: returned a valid tool_call in 2.6s
-> checking Qwen3.8-27B-FP8
OK Qwen3.8-27B-FP8: returned a valid tool_call in 8.3s
OK chose Qwen3 Coder 30B-A3B AWQ: the fastest to call a tool, so it acts instead of deliberating
OK configuration written to /home/you/.config/opencode/opencode.json

Check it end to end:
  colabhive agents doctor
Then, in your project directory:
  opencode

4. Check it, then run it​

colabhive agents doctor      # re-checks the configured model with a real tool call
cd your-project
opencode

Keep the key available in new shells: add export COLABHIVE_API_KEY='hive_...' to ~/.bashrc or ~/.zshrc. The configuration references the key; it does not contain it.

Already used OpenCode with another provider? init keeps your existing default model. Pick a ColabHive model inside OpenCode with /models, or run colabhive agents init --set-default.

What init writes, and what it leaves alone​

  • The API key is never written to the file. It is referenced as {env:COLABHIVE_API_KEY}. A key in a JSON file ends up in backups, dotfile repositories and pasted terminal output.
  • Everything else in the file is kept. Other providers, agents, MCP servers and settings are left as they were; only the colabhive provider is replaced.
  • An existing default model is kept unless you pass --set-default.
  • A file with comments or trailing commas is refused, not rewritten — they would be lost. Pass --config to write a separate file, or remove them.
  • Writes are atomic, with a timestamped backup of the previous file next to it.

Other commands​

CommandWhat it does
colabhive agents modelsLists the chat models with their state (warm or cold) and window. --json prints the raw entries, --limit how many
colabhive agents doctorRe-checks the configured default model (or the first one declared) with a real tool call
colabhive agents init --model <id or name>Uses that model instead of choosing one; it is still checked
colabhive agents init --no-probeWrites the configuration without the tool-calling check (not recommended)
colabhive agents init --set-defaultMakes ColabHive the default model even if another one was set
colabhive agents init --dry-runPrints the resulting configuration without writing it
colabhive agents init --config <path>Writes to another file, for example a project-level opencode.json

Every command accepts --api-key, --base-url and --timeout (300 seconds per request by default, because the first request to a cold model waits for it to load).

If something fails​

MessageWhat to do
no API key: pass --api-key or set COLABHIVE_API_KEYExport the key, or run init in a terminal so it can ask for it
the API key was rejected (401)The key is wrong, revoked or expired. Create a new one under Settings → API Keys
none of the … candidates passed the tool-calling checkNone of the top three returned a usable tool call. Run colabhive agents models and pass one with --model
opencode is not installedInstall it with one of the commands above, then run opencode
… is not plain JSONThe file has comments or trailing commas; use --config to write another file
The first request takes minutesThe model was cold and is loading; the next requests are fast. See Known limits

Next​