Connect OpenCode with OpenRouter

TL;DR

Add an OpenRouter API key as an OpenCode Credential; saving it runs a real check against the Runtime before it's stored, so a rejected key is never saved. Then choose the model and a low, medium, or high effort. An unavailable Runtime means the **Stack** image can't run OpenCode yet, regardless of whether the key was saved.

The OpenCode Runtime reaches models through your OpenRouter account. Its usage is metered on top of Zozo's flat hosted fee, and it doesn't accept a subscription Credential.

Connect an OpenRouter Key

1. Create or copy a key from your OpenRouter key settings.
2. In Setup, stay on Credential; Connect a Runtime. On an existing Stack, open Credentials in the Dashboard (#/auth) and use Add a Credential.
3. Enter a name for the Credential and choose OpenCode (OpenRouter) as the Provider.
4. Leave Kind set to API key. It's the only kind OpenCode accepts, so there is no subscription-consent step.
5. Paste the OpenRouter key and click Add Credential.

The key must start with sk-or-v1-. Zozo stores it outside the Event journal and, before saving it, exercises the Runtime with a minimal check: it runs a real, throwaway turn through the Runtime with the key attached and only saves the key once that turn tells Zozo whether it authenticates. A successful check gives the new Credential an authenticated health badge. A rejected key is never saved, and you'll see why so you can fix and retry it.

A Credential saved before this check existed needs a re-save

An OpenCode Credential added before Zozo started running this check has no recorded health verdict yet. Credentials shows it with a not validated badge rather than authenticated or invalid, and it's refused for Intake and Dispatch until you paste the same key in again through Add a Credential. Re-saving it runs the check and gives it a verdict.

If OpenRouter reports the key has run out of credit, Zozo still marks it authenticated: the key itself works. It also pauses that Credential until you add credit, since Zozo can't tell in advance when your balance will allow a Run to start again. Add credit in your OpenRouter account and the next Run attempt clears the pause.

If the Runtime can't be reached at all while saving a key, for example a Stack image that doesn't carry OpenCode yet, Zozo reports that it couldn't validate the key rather than guessing, and doesn't save it. Retry once the Stack carries a usable OpenCode Runtime.

Pick a Model and Effort

1. Find the new Credential on Credentials and click Tune runtime.
2. Set Model for Intake + Wayfinder, Dispatch, or both. Choose a suggestion from the deployed build or enter another OpenRouter model ID.
3. Set Effort to low, medium, or high. Any other OpenCode effort value prevents a Run from starting. Leave either field blank to use the OpenCode default.
4. Click Save tuning.

New Threads pick up the saved profile. Existing Threads keep the model and effort they already selected.

Read the Runtime-Unavailable State

Open Credentials and find OpenCode (OpenRouter) under Runtime availability. An unavailable badge and its detail mean the current Stack image doesn't carry a usable OpenCode Runtime. This state describes the Runtime, not the OpenRouter key, so replacing the key won't make the Runtime available.

Wait for a Stack image with OpenCode

OpenCode Runs can't start while its Runtime is unavailable. Keep work on an available Primary or Fallback Credential until the Stack receives an image that carries the OpenCode Runtime.

Related

• Understanding Credentials: decide where OpenCode fits and assign the Credential as a Primary or Fallback route.
• Tenant Reference: check which Credential kinds each Provider accepts.
• Reconnect After a Credential Alert: replace a key when its Credential health, rather than Runtime availability, fails.