OpenCode 2.0: how to upgrade from 1.x, and the three things that break

Anomaly published the OpenCode 2.0 announcement on October 12, calling it “a major overhaul” of the open-source coding agent. If you already run OpenCode 1.x, the practical question is: what do I have to change before upgrading, and what keeps working? Here is the answer, based on the announcement and the official Migrate from V1 guide.

The upgrade command

Per the announcement, get on the latest 1.x release first, then run:

opencode upgrade --major

The desktop app is updated by downloading the latest build from opencode.ai/download. The migration guide adds an important detail: V1 and V2 both use the opencode command and are not installed side by side by default. If you installed V1 through a package manager, remove that installation before installing V2; the V2 curl installer replaces the V1 binary.

The three breaking changes

The migration guide lists exactly three intentional breaks:

1. Plugins use a new plugin API. V1 plugin implementations do not run in V2 and must be ported.
2. The server API and clients have new contracts. Anything you wrote against the old server API needs porting.
3. Terminal client config moves from layered tui.json(c) files to one global cli.json (migrated automatically).

Everything else is meant to stay compatible. V2 reads opencode.json(c) from the same system, global and project locations as V1, and normalizes V1 fields in memory without rewriting your files. Agents, commands, skills and other files under .opencode/ “should continue to work without changes.” If they don’t, the docs say to treat it as a compatibility bug.

The recommended order: keep your config, start V2, verify models, credentials, agents, permissions and MCP servers, then port plugins, then port server-API integrations. Keep a copy of your V1 setup while you validate. Because both versions read the same config locations, don’t point V1 at files you’ve already converted to V2-only shapes.

Optional: the native V2 config shape

You can keep writing V1 config, but the native V2 format is more explicit. Some examples from the guide:

• permission maps become one ordered permissions array of {action, resource, effect} rules. bash becomes shell, task becomes subagent, and write/patch become edit.
• agent becomes agents, prompt becomes system, disable becomes disabled, and a model variant joins the model as model#variant.
• MCP servers move under mcp.servers, enabled flips to disabled, and timeout splits into catalog and execution.
• snapshot becomes snapshots, attachment becomes media, and autoshare: true becomes share: "auto".

The guide also suggests asking OpenCode itself to migrate the configuration for you.

What you get for the trouble

According to Anomaly, the 2.0 server now runs automatically as a single background process, and the TUI, web interface and desktop app all talk to it. All MCP servers are opted into a new Code Mode by default, so the agent can write small scripts that chain tool calls in one round trip instead of loading every tool into context. Subagents and shell commands can run in the background (a hotkey moves foreground work there). Nearly every 2.0 feature is implemented as one of 80+ internal plugins, and TUI plugins are now stable. A new @opencode/sdk lets you embed the same code that powers the CLI.

The new packages are live on npm: @opencode/sdk, @opencode/client and @opencode/codemode all list 2.0.29 as latest (npm). Note that the GitHub releases page and the opencode-ai npm package still showed v1.19.0 (October 11) as latest when we checked, so pin carefully in CI.

The new Code Mode matters for context cost. We covered how much tool schemas inflate agent prompts in our Claude Code vs OpenCode token overhead guide. If you drive OpenCode against a local backend, Harbor’s launch command is worth re-testing after the upgrade, since the server API changed.

Sources

• OpenCode 2.0 — Anomaly
• Migrate from V1 — OpenCode docs
• @opencode/sdk on npm
• anomalyco/opencode releases — GitHub