OpenCode

OpenCode connects to Actualyze as a custom provider in opencode.json. The opencode-actualyze plugin, which Actualyze publishes, fills that provider with models. Each time OpenCode starts, the plugin asks Actualyze which models your API key can call and adds every one with its real context window, output limit and capabilities. You don't list models yourself.

#Before you start

• OpenCode 1. The plugin uses OpenCode 1's plugin API, and OpenCode 2 doesn't load OpenCode 1 plugins. Run opencode --version and check that it prints a 1.x version. The default install on opencode.ai's home page is now OpenCode 2; to install OpenCode 1, use the install options in OpenCode 1's docs, for example curl -fsSL https://opencode.ai/install | bash.
• An Actualyze API key with the inference scope and read-write permission. Workspace Admins, Members and FinOps Managers who belong to a team can create one: in the Actualyze app, select API Keys under ADMIN in the sidebar (every role that can hold keys sees this page, not only admins), then select Create API Key. Keep the default Read & Write permission. The key's budget is the one your OpenCode usage draws down.

#Install

Install the plugin into your global OpenCode config:

opencode plugin opencode-actualyze --global

The command adds the plugin to two files in ~/.config/opencode/: opencode.json, where it runs model discovery, and tui.json, where it adds the /actualyze command. Without --global, it writes both entries to the current project's .opencode/ directory instead. To pin a version, install the versioned name, for example opencode plugin opencode-actualyze@1.7.0 --global; add --force if the plugin is already installed, or the command leaves the existing entry unchanged.

#Connect to Actualyze

The plugin fills in a provider you declare; it doesn't create one. Add the Actualyze provider to opencode.json, next to the plugin entry the install wrote. You can also put the provider in an opencode.json at a project's root; for keys both files set, the project file wins in that project.

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": ["opencode-actualyze"],
  "provider": {
    "actualyze": {
      "npm": "@ai-sdk/openai",
      "name": "Actualyze",
      "options": {
        "baseURL": "https://app.actualyze.ai/openai/v1",
        "apiKey": "{env:ACTUALYZE_API_KEY}",
        "probe": "actualyze"
      }
    }
  }
}

• There is no models map. The plugin supplies the models.
• probe goes inside options and tells the plugin to read each model's limits and capabilities from Actualyze. Without it, models still appear but carry no context or output limit, so OpenCode asks for 32,000 output tokens, which OpenAI-backed models reject with a 400.
• OpenCode replaces {env:ACTUALYZE_API_KEY} with the environment variable's value when it loads the file, so the key never sits in the file.

Set the key in your shell profile:

export ACTUALYZE_API_KEY="<your-actualyze-api-key>"

Then restart OpenCode from a new shell.

#Choose a model

After the restart, run /models. The picker shows an Actualyze group with every model Actualyze lists for your key. Each one arrives with the context window and output limit Actualyze reports, and with reasoning and image input turned on where Actualyze reports the model supports them.

Run /actualyze to open a dialog that lists the discovered models with their limits and capabilities. It never sends a message to the model. Press esc to close it.

• Discovery runs on every start, so models your key gains or loses show up, or drop out, the next time you open OpenCode.
• Discovery never holds up startup for more than five seconds. If Actualyze is unreachable, OpenCode starts normally without the Actualyze models.
• An administrator can hide a catalog model from discovery while leaving it callable by name; that model never appears in the picker. To use it, add it to a models map under the actualyze provider with a limit block giving its context and output caps. The plugin leaves entries you declare untouched; see the plugin README's manually configured models section.

#Troubleshooting

• No Actualyze models at all: OpenCode couldn't list them at startup. Check that ACTUALYZE_API_KEY is set in the shell that started OpenCode (an unset variable becomes an empty key) and that Actualyze is reachable, then restart.
• No Actualyze models on a slow connection: discovery, including the per-model detail requests, gets five seconds in total. To allow longer, set OPENCODE_MODEL_SCOUT_TIMEOUT_MS (milliseconds, up to 60000), for example to 15000, before starting OpenCode. The model list request itself still gives up after three seconds.
• /actualyze shows models without context or output limits: "probe": "actualyze" is missing from options. Add it and restart.
• The /actualyze command doesn't exist: the plugin entry is missing from tui.json. Run the install command again.
• The plugin does nothing and opencode --version prints 2.x: you're on OpenCode 2, which doesn't load this plugin. See the note under Before you start.
• Some models are missing: your key can't call them, or an administrator hid them from discovery.
• 402: a spend limit stopped the request before any model ran, so nothing was charged. The message says which limit: usually the key's budget, or the key's own monthly limit.
• 401: the key was rejected. It may be mistyped, revoked or expired, lack the inference scope, or belong to someone who is no longer on the key's team.
• 403: the request was refused. If the message says read-write permission is required, the key is read-only; create a read-write key. Otherwise your team can't use the model you asked for; check its access in the Model Catalog or pick another.
• 402 saying Budget required: the key's budget was deleted, archived or retired, or you no longer have access to it. Create a new key bound to a budget you can use.
• Model not found: the model is no longer available to your key. Restart OpenCode to refresh the list.

#Reference

• Plugin source and README: actualyze-ai/opencode-actualyze
• OpenCode 1's providers, config variables, plugins and CLI documentation
• OpenCode 2's plugin migration guide, which explains why OpenCode 1 plugins don't run there

Actualyze labels this traffic as OpenCode in the Client column of the Observability Activity tab, which Workspace Admins, FinOps Managers and Auditors can see. Requests you cancel mid-stream still draw down the usage they consumed.