OpenCode 2: How to Upgrade From v1 Without Breaking Your Setup

OpenCode 1.19.0, released on October 11, 2026, adds one line that matters: "Run opencode upgrade --major to upgrade to OpenCode 2." It also changes /update so that updates are no longer installed automatically. If you search "opencode v2" this week, this is the moment the open-source coding agent stopped being something you had to go find and started being something that prompts you.

I did not run the upgrade for this piece. Everything below comes from the v1.19.0 release notes and the official Migrate from V1 guide, plus community threads linked at the end.

What the release and the docs actually say#

The v1.19.0 notes are short. Under Core improvements: opencode upgrade --major upgrades you to OpenCode 2. Under TUI improvements: use /update to install updates or upgrade to OpenCode 2, and updates "are no longer installed automatically". It also allows the OpenAI ultrafast service tier and validates PTY connection origins and tickets before checking whether a PTY exists.

The migration guide is where the substance lives. Three things are called intentional breaking changes:

1. Plugins use a new plugin API. V1 plugin implementations do not run in V2.
2. The server API and clients have new contracts. Anything calling the V1 server must move to the @opencode/client package and the V2 API reference.
3. Terminal client config moves from layered tui.json(c) files to one global ~/.config/opencode/cli.json. The first V2 terminal startup migrates your global tui.json settings automatically, and project-local client config is not migrated.

Everything else supported in V1 is described as intended to stay compatible. The guide says existing server config fields, agent definitions, command definitions, skills and other files in .opencode/ "should continue to work without changes", and that a supported behavior breaking is a compatibility bug, not an expected migration cost.

The install gotcha: V1 and V2 share a command#

Per the guide, OpenCode 1 and 2 both use the opencode command and are no longer installed side by side by default. Remove a package-managed V1 install before installing V2, because the V2 curl installer replaces the V1 binary. V1 and V2 also read the same config locations (~/.config/opencode/opencode.json(c), <project>/opencode.json(c), <project>/.opencode/opencode.json(c)), and the guide warns you not to point V1 at files you have converted to the native V2 shape.

That last point is the one to respect. V2 normalizes V1 fields in memory without rewriting the file, so trying V2 is non-destructive until you start converting.

What the native V2 config changes#

Conversion is optional, but the shape is different enough that you should know it before a teammate hands you a V2-style file. From the guide:

• Permissions become one ordered permissions array of { action, resource, effect } entries. bash is now shell, task is now subagent, and write and patch are now edit.
• agent becomes agents, prompt becomes system, and a model variant joins the model string after #, as in anthropic/claude-sonnet-4-5#high.
• MCP servers group under mcp.servers, enabled becomes the inverse disabled, and timeouts split into catalog and execution.
• provider becomes providers, with npm becoming package (AI SDK packages get an aisdk: prefix) and api becoming settings.baseURL.
• Skills paths and URLs merge into one ordered skills array. Your .opencode/skills/ directory is discovered as before.

The guide's recommended path is to ask OpenCode itself to convert the config, with a prompt that tells it to preserve behavior and unrelated settings. Supported V1 and V2 fields can coexist at the top level, but the guide says to keep each nested agent, provider, command and model entry entirely in one format.

Three things that will bite you#

LSP. V2 accepts and preserves lsp configuration but "does not run language servers, expose LSP tools, or produce LSP diagnostics". If your workflow leaned on LSP feedback, the guide's answer is to use your lint, typecheck or compiler commands instead.

CLAUDE.md fallback. V2 currently only discovers AGENTS.md. If a V1 setup relied on a CLAUDE.md fallback, move that guidance into AGENTS.md. This matters if you share one repo between OpenCode and Claude Code; keep AGENTS.md as the source and let the other tool point at it.

A shared background server. By default V2 discovers or starts one shared background server per user account that owns sessions, config, permissions and tool execution. opencode --standalone runs a private server, and opencode service set disabled true makes private servers the default. If you run OpenCode headless in CI or as an API, as in OpenCode Server on Railway, decide on purpose which mode you want, and expect the V1 server API to be gone.

What people are actually saying#

The reaction is split, and the split is about plugins.

On Hacker News, one commenter in a "why are coding agents so dumb" thread said they run OpenCode v2 and that newer models tend to spawn subtasks on their own, handling more than five async subtasks out of the box. Another replied that they were confused by the v1/v2 split, since the docs say V2 is here while the GitHub releases page only showed v1.x, and that the migration list had kept them from switching. A third commenter pointed out that the tags tab, not the releases tab, tracks v2, and said v2 is better at spawning background shells and subagents asynchronously. That confusion is exactly what 1.19.0's upgrade --major is meant to remove. Thread: HN comment.

On Reddit, the search snippets lean the other way. One r/opencode post titled "Opencode 2 vs v1.19.0" says v2 broke their whole workflow and advises fixing plugins and custom scripts before updating. A "one weekend with OpenCode V2" post says most custom additions broke, several bugs turned up, and that some modifications cannot be done as plugins at all, so they would have to be re-applied after every update. Another commenter in a local-model thread put it as "expect your plugins to break". I only read search excerpts of these threads, not the full posts, so treat them as signal, not a survey.

The fair reading: the docs and the people who use stock config describe a smooth path, and the people with heavy plugin stacks describe a rewrite. Both can be true, because the guide itself says plugins are the intentional break.

What to do Monday#

1. Do not upgrade your only working install. Copy ~/.config/opencode/ and each project's .opencode/ somewhere safe first.
2. If you have zero plugins and a standard config, run opencode upgrade --major, then verify models, provider credentials, agents, permissions and MCP servers in one throwaway project. That verification list is straight from the guide.
3. If you have plugins, read the plugin migration guide before touching anything and port one at a time. Keep V1 until each one works.
4. Keep config in V1 shape until you are ready. V2 reads it and warns only on malformed, unsupported or conflicting values.
5. If you script against the server, budget time for the @opencode/client migration rather than hoping the old endpoints survive.
6. If an instruction file is CLAUDE.md, move it to AGENTS.md.

If you are choosing between agents rather than upgrading one, the OpenCode developer guide and OpenCode cron automation guide cover the stable parts, and pi vs Claude Code vs OpenCode covers the alternatives people mention when a migration goes badly.

Continue Reading#

• Claude Code vs Codex vs Cursor vs OpenCode - which agent ships more code
• OpenCode Developer Guide - setup, providers and config basics
• Put an AI Agent on a Cron Job - unattended OpenCode runs
• OpenCode Server on Railway - running the agent as an API
• pi vs Claude Code vs OpenCode - picking an agentic CLI

Sources#

• OpenCode v1.19.0 release notes - upgrade --major, /update, ultrafast tier
• OpenCode v2.0.26 tag - V2 line, tagged October 8
• Migrate from V1 - breaking changes, config mapping, install notes
• OpenCode 2 CLI intro - background service, standalone mode
• Hacker News comment thread - v2 subagent experience and release-page confusion
• r/opencode: Opencode 2 vs v1.19.0 - plugin breakage report
• r/opencodeCLI: My one weekend with OpenCode V2 - custom additions broke