OpenCode, the open-source terminal coding agent, is in the middle of a major rebuild. The Neuron’s October 15 digest listed “OpenCode 2.0,” noting that Hacker News commenters raised sandbox permission questions. I’m using two upgrade write-ups: Capital and Compute and explainx.ai. Neither author ran it, I haven’t either, and they conflict on dates, so I won’t give a firm release date. One says @opencode/cli 2.0.0 shipped September 11 and reached 2.0.28 on October 13. The other treats 1.19.0 (October 11) as the bridge release. Check the project’s own release notes.

What changed, per the write-ups

  • One shared background service. The terminal, desktop and web apps attach to the same local service instead of each running their own, with sessions in one database. opencode service status checks it.
  • Code Mode. An execute tool lets the agent run JavaScript that chains tool calls in one script. Capital and Compute says its sandbox has no filesystem access, imports, timers or fetch, and can only call the tools it’s given. explainx notes all MCP servers are opted in by default.
  • Background work. A subagent with background: true returns immediately and notifies the parent when done. Ctrl+B moves a running foreground task to the background. Background shell calls have no timeout unless you set one.
  • Worktree tools (worktree_create, list, remove) arrived in 2.0.27, and 2.0.28 added per-project auto-accept permissions.
  • opencode pair prints a local URL and credentials for the web app. --remote warns that it exposes your server.

Optional cache warming

After four minutes idle, it can send keep-alive pings every four minutes up to 30 minutes after your last real request. It’s off by default, and each ping is a billed request. The article’s Opus 5.5 example puts a full 30-minute warm at $0.14 in pings against a $0.50 cold re-write. It also warns that the docs’ 5-minute interval example is risky given a 5-minute cache lifetime. Compare Claude Code’s approach in my changelog post, where long idle sessions are compacted instead.

Breaking changes

  1. V1 plugins don’t run. Plugin code must be ported to the new API.
  2. The server API changed. Anything written against V1’s HTTP server needs updating.
  3. Terminal config: layered tui.json files become one global cli.json, migrated automatically (the sources differ on file names).
  4. LSP: the config remains, but V2 runs no language servers and shows no diagnostics, so use linters or type checkers instead.
  5. Renames: permission to permissions, bash/task/write/patch to shell/subagent/edit, mcp to mcp.servers. MCP’s enabled: false becomes disabled: true, and a careless find-and-replace could enable servers you meant to disable.

Upgrading safely

Per the guides: update to the latest 1.x first, back up your config and custom plugins, then run opencode upgrade --major, and review the diff of any config migration an agent offers. The V2 installer replaces V1, so rolling back means reinstalling V1. Try it on one machine first. The Capital and Compute piece also notes that a default opencode-ai install still gives V1.

My cautions

  • Both write-ups note no public benchmarks of V2 vs V1, so lower-token-use claims are unmeasured.
  • Model-written Code Mode scripts can be wrong, and an MCP server with write access could be called in a loop. Keep permission prompts on for destructive tools, which matches the default-deny advice in the Kaspersky guidelines post.
  • Separately, The Neuron reports OpenCode now offers a free DeepSeek V4.1 Flash tier with a 200K-token context window, versus 1M on the paid version. I haven’t verified that.

If you juggle several agents, compare it with AgentPlane, which takes a different approach to the same “one control plane” idea.

Sources: Capital and Compute, explainx.ai, The Neuron.