# OpenCode V1 to V2: keep a local coding workflow

Move an existing local OpenCode workflow from V1 to V2 by checking the executable generation, provider schema, permissions, and one small task.

Author: Retrivium team
Updated: 2026-11-03
Canonical URL: https://retrivium.ai/journal/opencode-v1-v2-local-migration/
Language: en

Migrating a local OpenCode workflow from V1 to V2 requires more than reusing the same command name. Both generations use opencode by default, while provider configuration and permission fields have different documented shapes.

## The concrete application boundary

The V1 introduction explicitly warns that the two generations cannot coexist under their default executable name. Installation channels can therefore replace or conflict with a prior command. Identify the installed generation before following a provider tutorial. In V2, custom providers use providers entries with a runtime package, settings, and model definitions. Permissions use an ordered permissions array with action/resource/effect rules. Old permission, bash, and task examples do not become valid V2 policy by leaving their wording unchanged. Treat this as a configuration migration with separate generation and tool checks, not as evidence that the local model must be downloaded again ([OpenCode V1 introduction](https://opencode.ai/docs/)).

## A practical route

Preserve the working V1 configuration and a small task transcript before changing anything. Record the actual executable and version using the application’s documented version mechanism. Compare the local provider with the current V2 provider reference, keeping the endpoint and real model identity intact while translating configuration structure. Recreate the intended action policy using current V2 names and ordering. Select the model through /models and start a read-only explanation in a disposable repository before permitting a reviewed edit ([OpenCode V2 Providers](https://opencode.ai/v2/docs/providers)) ([OpenCode V2 Permissions](https://opencode.ai/v2/docs/permissions)).

## A worked example

An old setup connects to a local server and asks before shell commands. After migration, the user can obtain text but the copied policy has no intended effect because it uses V1 names. Correct the V2 policy separately from the already working provider. Retry a read-only Git inspection and one bounded edit, checking their respective decisions rather than assuming that the first successful answer proves the whole migration.

| Check | Record |
| --- | --- |
| Command ownership | The installed generation that currently owns the opencode executable. |
| Provider migration | The V2 package, endpoint settings, and explicit provider/model selection. |
| Policy migration | Current V2 action names and ordered rules reproducing the intended approval behavior. |

## Reading the failure correctly

A stale shell path can invoke another generation than expected. A familiar display name can also hide a different model reference. Do not solve a configuration parse error by broadening permissions or reinstalling the runtime. Keep the preserved starting configuration available until the new workflow is understood; this article does not promise automatic session or plugin migration.

## What completes the check

A completed migration reproduces both the intended local generation path and the intended review boundaries. The shared executable name is a packaging detail, not a guarantee of compatible settings or identical behavior across generations.

Related background: [Reproducible inference stacks: preserving a GPU pilot’s result](/journal/software-stack-reproducibility/), [Coding LLMs on 12GB VRAM: Budget Context and Headroom](/journal/coding-llm-12gb-vram/).