OpenCode 2 Upgrade Guide: Migrating Smoothly from v1 Without Pitfalls

The open-source AI coding terminal OpenCode has reached a major version milestone. The newly added opencode upgrade --major command in OpenCode 1.19.0 provides an official path for migrating from v1 to OpenCode 2. But a major version upgrade is never just about running one command — the official migration guide clearly lays out what will break, what can be carried over, and a step-by-step "Monday safety checklist" you can follow.

The Upgrade Entry Point: The Trade-offs Behind a Single Command

The purpose of opencode upgrade --major is clear: to let v1 users cross the major version boundary without manually reinstalling or digging through documentation to compare configurations item by item. This command lowers the psychological barrier of "should I upgrade?" — but it solves the installation-level problem, not the compatibility-level one.

What really determines your upgrade experience is how much of your configuration relies on old interfaces. The official migration guide focuses on three areas: plugins, the server API, and TUI configuration. These three happen to be the parts that changed the most as OpenCode evolved from a "personal terminal tool" into an "extensible platform."

If your usage is simple — open the terminal, chat, edit code — the upgrade will likely be seamless. But if you've touched plugin development, written automation scripts calling the server API, or heavily customized the TUI interface, you'll need to check each item against the checklist.

What is TUI configuration? TUI (Text-based User Interface) refers to an interactive interface that runs entirely within the terminal — OpenCode's chat window, keyboard shortcuts, and status bar layout all fall under the TUI umbrella. TUI configuration is typically a separate config file (such as tui.toml or keybindings.json) used to define key mappings, theme colors, panel layouts, and more. The reason it's prone to issues during major version upgrades is that TUI config items are tightly coupled with the internal component structure: once v2 rewrites the rendering layer or introduces a new state management approach, v1's config fields may be renamed, merged, or outright deprecated. In practice, the most typical symptoms after upgrading are broken shortcuts, the interface reverting to the default theme, or startup warnings about unknown config items. The fix isn't to guess field by field, but to regenerate a minimal config based on v2's config schema, then add back customizations one at a time.

What Breaks and What Carries Over: The Core Conclusions of the Migration Guide

The official guide's categorization is blunt — no ambiguous "may be affected."

Definitely breaking:

• Plugins: The plugin interface underwent incompatible changes in v2. Extensions relying on the v1 plugin API need to be rewritten to the new specification.
• Server API: Adjustments to the server API will directly affect all automation flows that call OpenCode via HTTP or local ports.
• TUI configuration: The structure of the terminal interface config file has changed. Old config items may be ignored or throw errors.

Smoothly carried over:

• Core project context and working directory configuration
• Basic model and provider settings
• Daily conversation history and regular usage habits

This division signals something: OpenCode 2 has restructured at the "platform capability" level, but tried to preserve continuity at the "daily usage" level. For the vast majority of ordinary users, the migration cost is mainly about adapting config files, not relearning how to use the tool.

What is the server API, and why is it easier to overlook than plugins? OpenCode's server API is a set of local HTTP endpoints that allow external programs to invoke OpenCode's capabilities via a port — for example, letting editor plugins, CI scripts, or custom dashboards trigger code completion or query session status. The difference from the plugin interface is that plugins run inside the OpenCode process, whereas the server API is cross-process communication, and the caller could be a script written in any language. Because of this, breaking changes to the server API often don't surface when you're "just opening the terminal and using it" — they're discovered when some automation pipeline suddenly returns a 404 or parameter error. During migration, it's recommended to first search your codebase for all requests pointing to OpenCode's port, verify whether the path prefix, authentication method, and request body fields match the v2 docs, and pay special attention to old scripts that build URLs via string concatenation.

The Monday Safety Checklist: Making the Upgrade a Controllable Operation

The safe process recommended by the migration guide is essentially a set of practices that lower rollback costs. Executing them in order can push the probability of a "botched upgrade" very low.

Step 1: Back up your config directory. Before running opencode upgrade --major, make a copy of the entire config folder. This is the prerequisite for every subsequent step — with a backup, any misstep can be reverted to square one.

Step 2: Test on a non-critical project. Don't use your primary project as a guinea pig. Find a peripheral repo, or temporarily clone a copy of the code, and first verify whether basic functionality works after the upgrade.

Step 3: Check the three categories of breaking points one by one. Open your plugin directory, automation scripts, and TUI config file, and confirm each item against the migration guide. For plugins, check whether interface signatures have changed; for scripts, check whether API paths and parameters have been adjusted; for TUI config, check whether any fields have been deprecated.

Step 4: Upgrade your main environment only after confirming everything is fine. Once the first two steps pass, execute the upgrade on your daily work environment. By this point you have a backup and validation results, so the likelihood of problems is already very low.

Step 5: Keep the old version path around for a while. Even after a successful upgrade, it's advisable to leave the v1 executable in your PATH for a few more days as an emergency fallback.

This process has no technical sophistication, but that's exactly the part many people skip. Major version upgrade accidents often aren't because the changes themselves are complex, but because users operate directly on their main environment with no way back.

Why is "keep the old version path" the most underestimated step on the checklist? On Unix-like systems, the PATH environment variable determines which executable the terminal prioritizes. After upgrading to v2, if the v1 binary remains at its original path — just not first in PATH — you can temporarily use an absolute path or reorder PATH to roll back when problems arise, without re-downloading and reinstalling. A more robust approach is to rename and back up the v1 executable (e.g., opencode-v1) and add a temporary alias in your shell config. After a few days, once plugins and workflows are confirmed stable, clean up the old files. The value of this step isn't that "you'll definitely need it" — it's that it turns the upgrade from an irreversible operation into a reversible one, thereby lowering the psychological cost of trial and error.

Is This Upgrade Worth It?

The wording of the migration guide reveals the official judgment: v2's restructuring is meant to support the plugin ecosystem and external integrations, not change for change's sake. If you're using OpenCode for plugin development or integrating it into your own toolchain, the improved interface stability in v2 is a tangible benefit.

Conversely, if you just use it as a daily coding assistant, the motivation to upgrade is less urgent. You can observe for a while and follow up once the community has smoothed out the plugin adaptation issues.

In either case, opencode upgrade --major simplifies the "action" of upgrading, but the "decision" remains in the user's hands — back up first, test first, check first, then act. These three principles apply to OpenCode 2 and to all major version migrations.

One-line Summary

OpenCode 1.19.0 offers a cross-v2 upgrade command, but plugins, server API, and TUI config are all incompatible; the official safe migration checklist covers backup, trial run, and item-by-item checks.

Paragraph Summary

OpenCode 1.19.0 adds the opencode upgrade --major command, providing an official path from v1 to OpenCode 2. But the migration guide notes that simplified installation doesn't mean compatibility is guaranteed: v2 has incompatible changes in the plugin interface, server API, and TUI configuration, and users relying on these extensibility features must adapt each one; meanwhile, project context, model and provider settings, and daily conversation history can be carried over smoothly. The official recommended "Monday safety checklist" — back up the entire config directory, test on a non-critical project, check the three categories of breaking points against the guide, then upgrade your main environment once confirmed, and keep the old version executable as a fallback. For plugin developers and toolchain integrators, v2's improved interface stability offers clear benefits; ordinary users can wait and see how community adaptation progresses before deciding.