OpenCode 2 Migration: Three Breaking Changes to Check
V1.19 adds a direct upgrade path, but plugins, API integrations, and terminal settings need separate attention before teams switch.
Listen
AI narration
11:01
0:00 / 11:01
AI SummaryGenerated from this article
Condensed Summary (98 words)
OpenCode 2 reads V1 configuration files without rewriting them, but introduces three breaking changes requiring separate attention. V1.19.0 released October 11, 2026, provides an opencode upgrade --major command for migration. V1 plugins do not run in V2 and must be ported using the new plugin API. Server API integrations need new contracts, and terminal settings consolidate from multiple files into one global cli.json. The official migration guide recommends a staged approach: preserve existing configuration, validate essential behavior, port incompatible extensions, and convert to native V2 syntax only when ready. Supported configuration in .opencode/ directories remains compatible without conversion.
OpenCode 2 can read supported V1 configuration without rewriting the original files, but it cannot run V1 plugins. The project’s official migration guide makes that boundary clear: adopting the new version does not require a wholesale configuration conversion, though some extensions and integrations must be ported.
The V1.19.0 release provides a direct upgrade path. Its October 11, 2026 changelog entry introduces opencode upgrade --major for upgrading to OpenCode 2. The terminal’s /update command can also install updates or upgrade to V2.
For existing users, the practical question is what survives the switch unchanged. The guide identifies three intentional breaking changes and recommends a staged migration: retain existing configuration, validate essential behavior, port incompatible extensions, and convert to native V2 syntax only when ready.
V1.19 Makes the Major Upgrade an Explicit Action
For users on V1.19, the documented command is:
opencode upgrade --major
The same release changes terminal updating behavior: /update installs updates or offers the move to OpenCode 2, while updates are no longer installed automatically, according to the changelog.
Check the installation method before taking either path. OpenCode 1 and OpenCode 2 now both use the opencode command and are no longer installed side by side by default. The current guide says to remove a package-managed V1 installation before separately installing V2; the V2 curl installer replaces the V1 binary.
For rollback planning, do not assume a second command name will preserve a working V1 environment. Before replacing the executable, record how V1 was installed and keep a copy of its configuration and file-based definitions.
The migration documentation is a living page. V1.19.0’s major-upgrade handoff is the dated event here; the current guide’s instructions did not necessarily all first appear on October 11.
The Three Breaking Changes Affect Different Layers
The documented compatibility boundaries cover executable extensions, server integrations, and terminal preferences. Each requires a different response.
V1 Plugins Must Be Ported
V2 introduces a new plugin API, and the guide explicitly says V1 plugin implementations do not run in V2.
Work with Zeniteq
Let’s work together
We’re open to thoughtful collaborations with teams building in AI. Explore the ways we can work together.
Keeping a plugin’s configuration entry is therefore not enough. Teams need a V2-compatible implementation from the plugin’s maintainer or an internal port. Custom plugins need scheduled migration work; configuration cleanup alone will not resolve their incompatibility.
An inventory should distinguish convenient plugins from those required for a workflow. If a required plugin has no V2 implementation, successful startup alone is not evidence that the environment is ready.
Server Integrations Need New Contracts
The server API and clients also have new contracts. Integrations calling the old server API must migrate, according to the guide.
Custom clients and API-based automation need separate attention from ordinary configuration files. A script that communicates with OpenCode’s server needs its own compatibility check, even if the server starts and the terminal works.
Test each integration’s real workflow against V2. A working interactive session cannot substitute for those checks, and the migration guide does not promise that existing API consumers will continue working unchanged.
Terminal Settings Move to One Global File
Terminal configuration moves from layered tui.json or tui.jsonc files to one global cli.json file. The guide describes this migration as automatic.
The configuration model changes along with the filename. Teams that previously depended on settings from multiple terminal configuration files should inspect the resulting global configuration and verify the behavior they rely on.
Automatic migration reduces manual editing without preserving the old layering mechanism. This terminal-specific change is also separate from V2’s support for existing server configuration.
Supported V1 Configuration Can Stay in Place
Outside the three intentional breaks, OpenCode says supported V1 functionality is intended to remain compatible.
V2 reads existing system, global, and project configuration from the same locations as V1. It normalizes supported legacy and native V2 fields in memory without rewriting the source file. Supported server settings, agent definitions, command definitions, skills, and other files under .opencode/ are intended to continue working.
Teams can therefore retain the old format while testing the new runtime, without simultaneously changing how their configuration is expressed.
MCP servers belong in that validation stage. The guide specifically recommends checking models, credentials, agents, permissions, and MCP servers after starting V2. Existing supported MCP configuration does not automatically become a plugin-porting task merely because it connects an external tool.
One qualification needs attention: “accepted by the V1 schema” does not mean “supported in V2.” The guide identifies legacy fields without a V2 equivalent that are intentionally ignored. For example, the compaction fields tail_turns and prune are ignored with a warning; V2 retains recent context by token budget instead.
If behavior explicitly described as supported stops working, the guide says to treat that as a compatibility bug, not an expected migration requirement.
Optional Conversion Still Has Rules
Native V2 syntax can wait until the working environment has been validated. When teams do convert, several mappings deserve review because a superficially similar edit can change meaning.
Permissions: V1’s tool-grouped settings become an ordered permissions array. Action names also change, including bash to shell and task to subagent.
Agents: The agent and deprecated mode maps become agents. Agent prompt becomes system, and disable becomes disabled.
MCP servers: Server definitions move under mcp.servers. The old enabled flag becomes the inverse disabled flag, while timeout settings distinguish catalog and execution operations.
Commands: The singular command map becomes commands, and subtask becomes subagent.
These conversion rules do not require every field to be renamed before launching V2. Check the inversion of enabled especially carefully: copying the old boolean directly into disabled would reverse the intended setting.
Partial conversion is supported, within limits. V1 and V2 fields may coexist at the top level, and a valid native V2 value takes precedence when both forms set the same canonical value, regardless of JSON key order.
Mixed members are recognized within mcp, compaction, and experimental. Individual agent, provider, command, and model entries, however, should each remain entirely in one format. V2 does not recursively infer mixed formats inside those entries.
Administrators of managed deployments should also review policy placement. The current production guide says ordinary system settings provide lowest-precedence defaults, while system policies cannot be overridden by global or project files. It recommends experimental.policies for admin-enforced restrictions instead of relying on ordinary settings such as permissions.
Upgrade in Stages, With a Clear Validation Point
The safest sequence follows the guide’s staged approach, keeping installation, compatibility testing, and syntax conversion separate.
Preserve the V1 setup. Copy configuration and file-based definitions before changing anything. Record the installation method and identify required plugins, API integrations, and terminal customizations.
Choose the installation route. V1.19 provides opencode upgrade --major and the /update path. If installing V2 separately, follow the guide’s instruction to remove a package-managed V1 installation first. Do not assume the versions will remain independently available under different commands.
Start with existing supported configuration. Verify model access, credentials, agents, permissions, and MCP servers before making optional syntax changes. This separates runtime compatibility problems from conversion mistakes.
Validate the incompatible components independently. Port required plugins and integrations using the old server API. Inspect the automatically migrated terminal configuration. Where automation matters, exercise the actual workflow; checking only that OpenCode launches is insufficient.
Convert syntax after establishing working behavior. Review native V2 edits in small groups, respecting the rules for mixed formats. The guide recommends asking OpenCode to perform the conversion while preserving behavior and unrelated settings, but generated edits still warrant review.
Keep the preserved V1 files separate from converted configuration. Both versions use the same configuration locations, and the migration guide explicitly warns against pointing V1 at files converted to native V2-only shapes.
The acceptance test is whether the team’s supported configuration behaves correctly and its required extensions and automation work under the new contracts. Deferring configuration conversion lets users isolate those checks. That separation is more valuable than completing every rename in a single upgrade.
