Checked October 11, 2026 against the official v2 introduction and V1 migration guide. Do not mix V1 installation instructions with V2 configuration examples.
Choose the correct installation route
| Platform / interface | Official route to check |
|---|---|
| CLI on supported npm platforms | npm install -g @opencode/cli; inspect the required postinstall script before running. |
| Windows CLI | Use the official standalone binary for x64 or ARM64. The current v2 guide says Windows package managers are not supported. |
| Desktop | Choose the official build matching your OS and CPU architecture. |
| Web | Run opencode pair and use its local URL and generated credentials; do not publish those credentials. |
Three intentional breaking changes
Plugins
V1 plugin implementations do not run unchanged in V2; port them to the new plugin API.
Server integrations
The server API and clients have new contracts. Test scripts and integrations against the V2 documentation.
Terminal settings
Layered tui.json(c) settings move to a global cli.json file with automatic migration.
Migrate without losing your fallback
- Capture the old setupRecord the installed version and package manager; back up global config, project .opencode files, plugins and relevant data.
- Avoid command collisionsThe official guide says V1 and V2 are no longer side by side by default. Remove a package-managed V1 installation before installing V2; the curl installer replaces the V1 binary.
- Keep supported configuration firstV2 reads supported V1 fields from the same locations. You do not need to rewrite everything before trying it.
- Verify permissions and providersTest model selection, credentials, agents and MCP servers in a disposable project. Review denied and allowed actions, not just one successful chat.
- Port integrations separatelyMigrate plugins and server clients, then test compiler/lint workflows. The migration guide says V2 accepts lsp config but does not run language servers or produce LSP diagnostics.
- Convert only after validationNative V2 config is optional. Do not point V1 at files converted to V2-only shapes; restore your backup when rolling back.
For the browser interface, keep the local server private. A working local URL does not imply it is safe to bind to a public address. Check current authentication and network documentation before remote access.
FAQ
Must I rewrite all V1 configuration?
No. The official migration guide says supported V1 configuration remains readable. Plugins, server contracts and terminal-client settings have specific breaking changes.
Can I safely run V1 and V2 on the same config?
Do not assume so. They share configuration locations; V1 should not read V2-only converted files. Keep a backup and test separately.
Does v2 include a GUI?
Yes. The official guide lists desktop builds and a web interface through opencode pair, in addition to the terminal client.