V1 to V2 Migration Reference

Breaking Changes

V2 has three intentional breaking changes:

Plugins use a new API (V1 plugins will not work)
Server API and clients have new contracts
TUI configuration moves from tui.json(c) to one global cli.json

Side-by-Side Installation

V1 runs as opencode, V2 runs as opencode2. Both can coexist:

# V1 (existing)
npm install -g opencode-ai

# V2 (beta)
npm install -g @opencode-ai/cli@next

Config Migration Quick Reference

Area	V1	V2
Permissions	`permission` map by tool	`permissions` ordered array
Agents	`agent` map	`agents` map (renamed fields)
Provider	`provider` map, `npm` field	`providers` map, `package` field
MCP	`mcp` flat map, `enabled`	`mcp.servers` map, `disabled`
Plugins	`plugin` array	`plugins` array (object form)
Commands	`command` map	`commands` map
References	`reference` map	`references` map
Snapshots	`snapshot` boolean	`snapshots` boolean
Media	`attachment` object	`media` object
Skills	`skills.paths` + `skills.urls`	`skills` single array
Compaction	`preserve_recent_tokens`	`keep.tokens`
Compaction reserve	`reserved`	`buffer`

Agent Field Renames

V1	V2
`prompt`	`system`
`disable`	`disabled`
`permission`	`permissions`
`maxSteps`	`steps`
`model` + `variant`	`model` with `#variant` suffix

Permission Action Renames

V1	V2
`bash`	`shell`
`task`	`subagent`
`write` / `patch`	`edit`

Provider Migration

V1	V2
`npm: "@ai-sdk/..."`	`package: "aisdk:@ai-sdk/..."`
`api: "https://..."`	`settings.baseURL: "https://..."`
`options: { apiKey }`	`settings: { apiKey }`

Consolidated provider IDs:

V1 provider ID	V2 provider ID
`azure-cognitive-services`	`azure`
`google-vertex-anthropic`	`google-vertex`

TUI Config Migration

V1 loaded tui.json(c) from global and project directories. V2 uses one global file:

~/.config/opencode/cli.json

V2 migrates automatically on first startup when cli.json doesn’t exist. It reads tui.json and legacy kv.json state, converts settings, and writes cli.json. The V1 files are left unchanged.

Gotcha: Migration runs only while cli.json is absent. Once it exists, V2 treats it as the source of truth. If you created cli.json before starting V2, merge V1 settings manually.

Accepted but Unsupported Fields

V2 ignores these V1 fields with a warning (not compatibility bugs):

logLevel (use OPENCODE_LOG_LEVEL env var)
server (use V2 service options)
layout (already deprecated in V1)
compaction.tail_turns and compaction.prune
Agent name inside JSON config
V1 experimental fields: disable_paste_summary, batch_tool, openTelemetry, primary_tools, continue_loop_on_deny

Recommended Migration Path

Ask OpenCode to migrate for you:

Migrate my OpenCode configuration, including file-based definitions, from the V1 format to the native V2 format.
Preserve its behavior and all unrelated settings.

V1 and V2 fields can coexist at the top level. You don’t need to convert everything at once.