Wallaby.Dispatch

OpenCode 2 is out: what actually changes if you bring your own key

2026-10-16 by the Wallaby Dispatch editorial team · updated 2026-10-15 Industry opencode kimi-k3 byok cli coding-agents
Reviewed against primary sources; Wallaby numbers come from our own production gateway logs.

Model: Kimi K3 · ✓ Verified on opencode v2.0.29 · 2026-10-15

OpenCode 2 is generally available: four releases in one week, v2.0.26 through v2.0.29, shipped October 8–14, 2026. If you run OpenCode with your own API key, the short answer is: your setup migrates in zero steps. Same environment variable, same model id, same catalog entry. We installed v2.0.29 today and verified it end to end. The longer answer is that three v1 habits now break, and the upgrade path itself has two traps worth knowing about before you type upgrade. Disclosure: Wallaby Token sells API access to Kimi K3, the model we ran the verification on.

The distribution change that trips people up

OpenCode's GitHub Releases page stops at v1.19.0. That release is a bridge build whose notes tell you to run opencode upgrade --major. Version 2 binaries are served from OpenCode's own CDN (opencode.ai/files/bin/2.0.29/...) and from WinGet as Anomaly.OpenCode.

Two consequences we hit first-hand:

  • The install script can't pin v2. install.sh --version 2.0.29 404s, because the script only looks at GitHub Releases, and v2 isn't there. Run the installer without a version pin, which now fetches the latest v2, or download the CDN zip directly.
  • upgrade --major can stall behind a proxy. From our network, the in-app upgrade ran five minutes without finishing, and upgrade -m curl hit a GitHub API 403 (rate-limited exit IP). Your mileage will vary (this was our egress, not a universal behavior), but if the upgrade hangs, the manual CDN zip is a two-minute fallback that works.

What v2 actually changes for BYOK users

The feature list is long: a Provider Account Management dialog (add, edit, and remove provider accounts from the connect UI), automatic continuation when output hits the cap, a built-in worktree tool, per-project auto-accept, remote pairing. The full changelog is on the release notes.

For bring-your-own-key setups, the important part is what did not change: the provider catalog still syncs from models.dev, the entry still tells OpenCode which environment variable to read, and the model id is the same. Our entire migration, unedited:

$ curl -fSLO https://opencode.ai/files/bin/2.0.29/opencode-darwin-arm64.zip
$ unzip -q opencode-darwin-arm64.zip && ./opencode --version
opencode v2.0.29
$ export WALLABY_API_KEY=sk-your-wallaby-key
$ opencode run -m wallaby/moonshotai/kimi-k3 "Reply with exactly three words: Wallaby funnel works"
Wallaby funnel works

Same key, same model name, no config edits. Zero migration cost is not a figure of speech here. There was literally nothing to migrate.

Three v1 habits that break in v2

1. opencode models --refresh is gone. The flag was removed (Unrecognized flag). In v1 this was the standard fix for a stale provider catalog; in v2 the refresh equivalent is restarting the background server.

2. The background server caches the catalog, and the cache can be stale about your key. v2 runs a persistent server by default. If that server first started before you set your API key, it cached a catalog that doesn't include key-gated providers. Afterwards, even with WALLABY_API_KEY set, you get:

Model unavailable: wallaby/moonshotai/kimi-k3

The key is fine; the cache is not. Fix: restart the OpenCode server, or run once with --standalone to bypass it. This gotcha does not exist in v1, which fetched the catalog in-process on every start. It's new in v2, and it's the one most likely to produce "I set the key and it still doesn't work" reports.

3. opencode models only lists providers you have credentials for. This is true in both versions, but it surprises people during setup: with no key set, the list shows only the free in-house entries. Set the key first, then look.

The free tier is a separate story

If you came here because OpenCode's free models stopped working in your scripts, that wall is unrelated to the v2 release. The free tier went app-only back in September 2026, and it behaves the same on v1 and v2. We mapped that change and three ways out in a separate post.

If you're setting up fresh

Skip the archaeology and go straight to the four-step guide: Kimi K3 in OpenCode: zero-config, in the catalog — updated today for v2, including the server-cache fix above. New Wallaby accounts get $0.50 in free credit, no card required, which covers the smoke test in this post many times over (ours cost under two cents). Kimi K3 is $2.70 in / $13.50 out per 1M tokens through Wallaby, a standing 10% below the official list.

Sources: OpenCode v1.19.0 release notes (the bridge build and upgrade --major path); the v2 binary CDN at opencode.ai/files/bin/2.0.29/; the WinGet package Anomaly.OpenCode.

Did this help?