Migrate OpenCode 1 to 2 Step by Step

To migrate OpenCode 1 to 2, update your installation to the latest version 1 release, remove any package-managed version 1 binaries, install version 2, and verify that your existing models, credentials, agent definitions, permissions, and Model Context Protocol (MCP) servers load properly before rewriting custom plugins.

At Layer3Labs, we build custom agents, enterprise integrations, and advisory engagements for small and mid-sized businesses, and we do not sell software licences. For a broader look at the platform changes, see our guide on OpenCode 2 Explained.

Steps to Migrate OpenCode 1 to 2

Upgrading from version 1 to version 2 requires replacing the executable binary rather than running both releases alongside each other.

Both major releases rely on the opencode command line interface (CLI) binary name in your system path, which prevents side-by-side installation by default. The official migration documentation outlines keeping existing configuration when starting V2. Anomaly says to be on the latest 1.x first.

V1 and V2 read the same config locations, so keep a copy of your V1 setup while validating. Follow these sequential steps to complete the core upgrade process:

• 1. Update to the latest 1.x release: Ensure your installation is on the latest 1.x release before upgrading.
• 2. Remove package-managed version 1 binaries: If you installed version 1 through an external package manager, uninstall that package before installing version 2.
• 3. Install version 2 (two routes): On the latest 1.x, run opencode upgrade --major. For a fresh or package-managed install, remove the package first, then run curl -fsSL https://opencode.ai/v2/install | bash.
• 4. Verify base credentials and models: Launch version 2 against your existing configuration files to confirm that your model providers, credentials, custom agent definitions, permissions, and Model Context Protocol (MCP) servers initialize correctly.
• 5. Port custom plugins and server integrations: Rewrite any custom plugins against the new plugin application programming interface (API), and update external scripts or services that communicate with the server API.
• 6. Convert configuration to native version 2 structure: After confirming that your core agents and models run as expected, prompt OpenCode or update your files manually to adopt native version 2 key names.

Breaking Changes in OpenCode 2

OpenCode version 2 introduces three breaking changes across the plugin architecture, the server interface, and terminal client settings.

Outside of these three specific domains, supported version 1 functionality is designed to remain compatible.

The release notes published by Anomaly and reporting from the AI-Augmented Engineer newsletter highlight these three intentional architectural changes:

• Plugin API redesign: Version 1 plugin implementations do not execute in version 2. Renaming a plugin directory or adjusting configuration keys is not sufficient to restore functionality, so every plugin must be rewritten to match the new plugin API.
• Server API and client contracts: OpenCode 2 introduces new contracts for its background server and programmatic clients. Any application or custom automation pipeline that interacts with the previous software development kit (SDK) or Hypertext Transfer Protocol (HTTP) endpoints must be updated.
• Terminal client configuration consolidation: Terminal user interface (TUI) settings no longer reside across layered tui.json and tui.jsonc files. Version 2 consolidates all terminal client settings into a single global cli.json file, which is auto migrated.

Supported Features in OpenCode 2

Existing server configuration files, custom agent definitions, skills, commands, and project definitions in the .opencode directory are intended to keep working; if one does not, file a compatibility issue.

Configuration files are read from the identical file locations used in version 1. These locations include system-level configuration paths, the global user file at ~/.config/opencode/opencode.json (or opencode.jsonc), project-level configuration files, and definitions stored within .opencode/ directories.

System configuration files and macOS managed preferences retain the highest precedence across environments. When defining mandatory rules or administrative restrictions for engineering teams, administrators should establish them as system policies rather than standard user settings.

If supported version 1 behavior outside of plugins, the server API, or terminal configuration stops working after upgrading to version 2, treat that failure as a compatibility bug and submit an issue to the project repository.

Configuration Conversion to Native V2 Format

You can convert your configuration to the native version 2 structure by prompting OpenCode directly or by manually updating key names.

The recommended conversion approach described in the migration documentation is to instruct OpenCode itself: 'Migrate my OpenCode configuration, including file-based definitions, from the V1 format to the native V2 format. Preserve its behavior and all unrelated settings.'

Supported version 1 fields and native version 2 fields can coexist at the top level of your configuration file. However, nested mixing inside individual agent, provider, command, or model objects is not permitted. Each individual nested block must adhere strictly to either the version 1 format or the version 2 format.

• Consolidated provider identifiers: The provider identifiers azure-cognitive-services and google-vertex-anthropic are consolidated into azure and google-vertex.
• Do not point V1 at converted files: Because version 1 and version 2 read from the identical file locations on your machine, do not point an older version 1 binary at configuration files converted to version 2 syntax.

Language Server Protocol Changes and Diagnostic Workarounds

OpenCode version 2 accepts and preserves Language Server Protocol (LSP) configuration settings but does not run language servers, expose LSP tools, or produce LSP diagnostics.

If your development workflows depended on OpenCode running background language servers to surface code errors, you must adapt those checks. Replace internal language server diagnostic checks with direct terminal executions of your project linters, typecheckers, or compiler commands.

opencode.ai's home page still lists LSP enabled while the migration doc says V2 does not run language servers. The home page at OpenCode describes the project as 'an open source agent that helps you write code in your terminal, IDE, or desktop' and continues to list 'LSP enabled' in its feature list. However, version 2 release documentation confirms that active language server execution is disabled. Development teams should verify language diagnostic handling inside their own repositories.

Team Rollout Strategy

A safe organizational rollout relies on backing up version 1 configurations, testing the upgrade on an isolated repository, and keeping administrator restrictions in system policies.

To budget model access before deploying broadly, review our analysis of OpenCode Pricing.

• Maintain isolated configuration archives: Archive your existing ~/.config/opencode directory and project-level .opencode folders before running the installation script.
• Pilot on a secondary repository: Deploy version 2 across a non-critical codebase to verify credentials, model connections, and custom commands before broad adoption.
• Audit plugin reliance: Inventory active team workflows for custom version 1 plugins, as those extensions will stop executing immediately after the binary updates.
• Enforce central guardrails: Express admin restrictions as policies in system config or managed preferences, Ordinary settings rank lower in precedence.

Teams Unready to Migrate OpenCode 1 to 2

Engineering teams that depend on custom version 1 plugins or internal Language Server Protocol diagnostics should postpone their upgrade until those components are ported.

Because version 1 plugins cannot run inside version 2, upgrading prematurely will break custom team tooling and automated developer extensions. Teams should note that OpenCode 1 and 2 both use the opencode command and are no longer installed side by side by default, as the V2 installer replaces the V1 binary.