The convenience feature is an authority change
OpenCode 2 no longer treats each interface as the center of the agent. Its official release explains that a single background process starts automatically and terminal, web, desktop, and programmatic clients all speak to it. That is a cleaner architecture. It is also a local control plane.
The distinction matters because the service does more than preserve chat. It owns sessions, exposes an API, discovers local clients, coordinates scheduled work, manages plugins, applies configuration and policy, connects MCP servers, moves work into Git worktrees, and can be exposed to other hosts through pairing. A client can close while the service continues. A second client can observe or steer work created elsewhere. The useful unit is no longer “the terminal session”; it is the service plus every client and workspace attached to it.
Developer attention is real but not proof of production reliability. The OpenCode 2 launch reached 890 points and 397 comments on Hacker News in the current research window, while the first-party repository had roughly 225,000 stars when checked on November 5. Those are adoption and interest signals. They do not tell you whether your operating system, update path, plugins, MCP servers, permission rules, remote access, and worktrees will recover correctly after a failure.
The issue tracker supplies cases, not prevalence. Current reports describe a managed service that timed out at startup, a plugin reload that silently dropped custom agents and commands until restart, an update path that left an orphaned service, and Windows watchdog or snapshot conditions that restarted the service and aborted active work. Some reports were closed, fixed, marked duplicate, or could not be reproduced. Their value is not an implied defect rate. Their value is a failure taxonomy that teams can turn into acceptance tests.
If every client trusts one service, the first production question is not “does the UI open?” It is “can the client prove which service, version, policy, state, and workspace it is trusting?”
This article proposes that proof. The core rule is simple: do not promote OpenCode 2 from individual experimentation to team or unattended use until a test harness can identify the service, compare its active contract with the intended contract, exercise recovery paths, and block work when it cannot establish parity.
One process now joins five kinds of state
ClientsTUI, desktop, web, scripts using @opencode/client, CLI API commands, and paired applications.
Shared serviceOwns session catalogs, agent execution, plugin state, MCP connections, permission requests, and client-visible events.
Configuration authorityCombines system, managed, global, and project configuration; policies outrank user settings where administrators need enforcement.
Workspace authorityMaps sessions to projects and worktrees while tools read, edit, execute, and communicate with external services.
Recovery evidenceHealth, version, active configuration, session inventory, worktree identity, interrupted effects, and operator disposition.
Centralization removes several sources of split-brain behavior. A script can discover the same local service the terminal uses. Desktop and web clients can show the same session family. A long-running task no longer has to die because its original panel closed. OpenCode can call its own API to create a worktree, rename a session, move it, inspect another session, interrupt it, or send it another prompt.
But the same mechanism couples previously separate concerns. A service restart can affect every attached client and background task. A stale registration can send a new client to the wrong process. A configuration reload can leave the service alive while required extensions disappear. A global client file and a service-side configuration tree can disagree. A remote pairing path can extend a local authority boundary onto another device. A migration that keeps familiar files but changes plugin and server APIs can look successful until a rarely used capability is needed.
The V2 migration guide makes three breaking areas explicit: plugins use a new API, server API and clients have new contracts, and terminal configuration moves to one global cli.json. It also says supported V1 configuration and file-based definitions should continue to work, while certain accepted fields have no V2 behavior and are ignored with warnings. That creates a testable requirement: “the file parsed” is weaker than “the intended restriction or capability is active.”
Administrative policy deserves special attention. The migration guide warns that overriding ordinary settings cannot prevent users from adding providers, MCP servers, agents, or plugins. Enforced restrictions belong in policies, whose system and managed-preference layers outrank global and project policy. A migration that converts a deny rule into a user-overridable setting has preserved syntax while losing authority.
Freeze an acceptance manifest before the upgrade
Start with an intended-state manifest that is independent of the running service. It should name the exact OpenCode build, installation source, service endpoint, state directory, project roots, allowed remote exposure, required agents and plugins, MCP servers, provider policies, permission defaults, update mode, and recovery targets. Keep credentials outside the file; record only secret references and custody rules.
contract: opencode-service/v1
release:
version: "2.2.0"
install_source: "pinned-package-or-image"
service:
expected_host: "127.0.0.1"
remote_pairing: false
identity_fields: [pid, version, started_at, state_dir, endpoint]
configuration:
required_policies: [provider-deny-default, remote-mcp-deny]
required_agents: [build, review]
required_plugins: [org-policy, evidence-receipt]
update_mode: "notify"
workspace:
allowed_roots: ["/work/acme"]
require_worktree_per_write_session: true
recovery:
max_start_seconds: 20
session_loss_target: 0
require_interrupted_effect_inventory: true
require_operator_receipt: true
Do not infer the manifest from the current process after migration. That would let the system under test define success. Export the V1 baseline before changing files: effective provider list, agent definitions, permission rules, plugins, MCP servers, commands, instructions, model mappings, update behavior, and project-specific exceptions. Save hashes of relevant files and record which layer supplies each rule.
Then create a parity matrix. Some fields can be compared mechanically: a required plugin is present, a provider is denied, or an MCP server uses the expected command. Others require behavioral probes: an agent cannot write outside its worktree, a remote client cannot approve a protected tool, a project cannot override a managed deny, and a plugin reload cannot expose a partially applied registry.
| Claim | Static evidence | Behavioral probe | Block when |
| Right service | Endpoint, PID, version, state directory | Restart and rediscover under version pin | Identity is absent, stale, or ambiguous |
| Policy parity | Effective policy export and layer source | Attempt a denied provider, MCP server, and plugin | Any lower layer can override the deny |
| Permission parity | Resolved permission rules per agent | Read, write, shell, network, and remote approval probes | Prompt or decision differs from contract |
| Extension parity | Plugin and agent inventory with versions | Hot reload valid and invalid changes | Registry partially disappears or stays stale |
| Session durability | Session IDs, worktree paths, active tasks | Kill service during model, shell, and subagent work | Work is duplicated, lost silently, or misattributed |
| Rollback | State backup and compatibility declaration | Restore old binary against copied state | Rollback mutates production state or cannot reconnect |
A listening port is not a healthy service
A startup check should establish identity before availability. The client must learn the version, process start time, state location, endpoint, and a boot identifier that changes across restarts. It should then verify the effective contract and a small canary capability. Only after those checks should it attach a real session or allow scheduled work.
async function admitService(expected) {
const info = await withTimeout(client.systemInfo(), expected.maxStartMs)
assert(info.version === expected.version)
assert(info.endpoint === expected.endpoint)
assert(info.stateDir === expected.stateDir)
const active = await client.exportEffectiveContract()
assert(hash(active.policies) === expected.policyHash)
assert(hasEvery(active.plugins, expected.requiredPlugins))
assert(hasEvery(active.agents, expected.requiredAgents))
const canary = await client.runReadOnlyCanary({project: expected.canaryProject})
assert(canary.workspace === expected.canaryProject)
assert(canary.deniedWrites === true)
return {bootId: info.bootId, admittedAt: new Date().toISOString()}
}
OpenCode's public API may not expose every hypothetical field in that example. The contract is the important part: obtain equivalent evidence through supported API calls, status commands, logs, process metadata, or a small organization plugin. If a critical property cannot be observed, do not substitute a green icon. Mark it unverified and limit the service accordingly.
Test false health. Hold the registration lock while no listener is available. Start an old binary on the expected port. Leave a process alive after replacing its executable. Delay an information endpoint while the event stream still emits heartbeats. Break one required MCP server while the core service responds. A healthy control plane must distinguish “process exists,” “transport responds,” “configuration loaded,” “dependencies reconciled,” and “safe to admit work.”
Recovery also needs effect accounting. If the service dies after starting a shell command, the replacement process must not blindly repeat it. Record whether the effect completed, remains running, failed, or is unknown. The correct next action may be observe, reconcile, compensate, request approval, or stop. “Retry session” is not a safe universal answer.
Centralize policy without centralizing accidental power
The service can make permission behavior consistent across clients, which is valuable. A desktop client and terminal should not reach different decisions about the same shell command because one cached an old rule. Yet central consistency can amplify a mistake. A permissive project rule, missing managed policy, or compromised plugin now affects every attached interface.
Separate five authorities: who may connect, which projects they may see, which agents and tools they may invoke, which side effects require approval, and who may change policy. HTTP Basic authentication with OPENCODE_PASSWORD, documented for V2 servers, protects a transport endpoint but does not express that complete model. Keep remote service exposure off by default, use a strong secret when enabled, restrict network reachability, and treat pairing as a new trust grant rather than a convenience link.
Permission testing should cover the effective behavior of each agent, not only the default. Probe reads outside the project, writes outside the assigned worktree, shell commands, environment access, network calls, MCP tools, secret-bearing files, destructive Git operations, and client-driven approvals. Include negative tests from every interface. If a remote web client can approve an action the TUI correctly blocks, the shared service has synchronized state without synchronizing authority.
Hot reload needs transaction semantics. The official release emphasizes that OpenCode 2 can write and load a plugin during a session. That is powerful, but issue #49982 demonstrates the failure class: a reload error can leave the running service without expected custom agents and commands until restart. A safe reload computes the candidate registry, validates it completely, and swaps it atomically. On failure, the prior registry must remain active and the service must report a blocking condition.
Updates need the same discipline. Pin the tested version for team and unattended lanes. Download and verify the new build, stop admission of new tasks, inventory active sessions and external effects, start a candidate service on isolated state or a separate development port, run parity probes, drain or interrupt work deliberately, then hand clients to the new boot identity. Never interpret “new process started” as proof that the old process released locks, stopped tools, or wrote compatible state.
Turn current issue reports into a failure-injection suite
| Failure class | Observed case | Acceptance test | Required behavior |
| Startup race | Managed server times out or a client cannot connect | Delay bind and initialization beyond the normal path | Bounded retry, real cause, no duplicate service |
| Orphaned update | Old process survives package replacement and keeps a lock | Replace binary while the service owns registration | Detect stale identity; quarantine or cleanly stop it |
| Reload degradation | Failed plugin reload drops custom registry entries | Introduce an invalid plugin during hot reload | Keep prior registry; surface blocking error |
| False watchdog failure | Idle event stream triggers restart and aborts work | Pause heartbeats while health API remains responsive | Confirm multi-signal failure before restart |
| Slow information path | Snapshot work delays health response and causes a loop | Block snapshot or status handler under load | Separate health from heavy work; shed load safely |
| Version skew | Client and service API contracts differ | Connect old client to new server and the reverse | Reject incompatibility with migration guidance |
| Workspace loss | Session points to removed or changed worktree | Delete, move, and reuse the worktree path | Stop writes; require explicit rebind |
| Unknown side effect | Service dies after dispatch but before receipt | Kill between tool request and completion record | Reconcile target state; never blind retry |
Do not wait for a reported issue to match your platform exactly. The general patterns apply across operating systems: discovery races, stale locks, version skew, partial reload, overloaded control endpoints, and ambiguous side effects. Reproduce them in a copied project and disposable state directory. Preserve logs, timestamps, process trees, configuration hashes, session IDs, worktree hashes, and target-system receipts.
A recovery receipt should state the old and new boot identities, trigger, last known healthy time, active sessions, interrupted tools, external effects checked, state restored, configuration and policy hashes, probes rerun, work abandoned, operator, approval, and residual uncertainty. If an effect remains unknown, the receipt is not complete merely because the service is green again.
Migrate in shadow mode, not on the strength of compatibility claims
- Inventory the V1 installation, configuration layers, agents, commands, instructions, skills, plugins, MCP servers, providers, permissions, update mode, and integrations that call the server API.
- Back up configuration and state without putting credentials into the test record. Hash the artifacts and keep V1 away from files converted to V2-only shapes.
- Classify every rule as user preference or enforced policy. Convert administrative restrictions to V2 policies rather than ordinary settings.
- Port plugins and server integrations explicitly. A renamed file does not make a V1 plugin compatible, and the V2 server API is an intentional breaking change.
- Start V2 in a copied project and isolated state location. Pin the build and disable automatic updates for the validation lane.
- Compare effective agents, providers, permissions, MCP servers, plugins, models, and instructions with the frozen baseline. Investigate ignored-field warnings.
- Run positive and negative permission probes from TUI, desktop, web, API client, and any paired application in scope.
- Exercise session creation, worktree creation and movement, interruption, background shell work, subagents, compaction, snapshot, reconnect, and export.
- Inject startup, reload, update, version, workspace, dependency, and target-effect failures. Require honest state and a recovery receipt.
- Promote one bounded workload only after the service passes the manifest. Keep rollback isolated from production state and revalidate after every release.
The official guide recommends verifying models, provider credentials, agents, permissions, MCP servers, and plugins before relying on V2. Treat that list as the minimum, not the whole gate. Add service identity, policy precedence, client parity, worktree binding, active-effect reconciliation, observability, and rollback because they determine whether a centralized runtime fails safely.
A 30-day production-readiness plan
Days 1-5: freeze and map. Build the manifest, baseline V1 behavior, identify every client and integration, and choose a low-consequence repository. Define which evidence blocks promotion and who owns service, policy, plugin, workspace, and security decisions.
Days 6-12: prove parity. Install one pinned V2 build in isolation. Port plugins and integrations. Run configuration, policy, permission, MCP, model, instruction, worktree, and API tests. Record mismatches instead of editing the acceptance target to match the candidate.
Days 13-20: break the service. Run the failure matrix under normal and high load. Kill processes during model output, shell execution, plugin reload, snapshot, and update. Test remote connection and denial paths. Measure detection time, recovery time, duplicated effects, lost work, false health, and manual steps.
Days 21-26: shadow real work. Run representative tasks beside the existing lane without giving V2 sole authority. Compare accepted patches, review effort, session continuity, permission prompts, tool failures, and operator interventions. Include an overnight or scheduled task only after side-effect reconciliation passes.
Days 27-30: decide with evidence. Approve a bounded production lane, extend the test period, or stop. Bind approval to a specific build, manifest, operating-system set, plugins, policies, and workload. A later OpenCode, plugin, MCP, policy, or client change reopens affected tests.
The useful outcome is not “OpenCode 2 works.” It is a narrower, durable statement: this exact service contract recovered honestly from these failures while preserving these policy and workspace invariants. That is evidence a team can operate.
Frequently asked questions
What changed in OpenCode 2's service architecture?
One background service runs automatically and multiple clients connect to it. That lets sessions and scheduled work outlive one UI, but it also makes the service the shared authority for state and execution.
Is the background service a complete security boundary?
No. It can centralize policy and permissions, but the host operating system, network, credentials, plugins, MCP servers, workspace isolation, remote access, and target systems still enforce important boundaries.
Should a team enable automatic updates?
Not in a controlled or unattended lane unless the team has a tested canary, drain, state-compatibility, rollback, and recovery process. Pin the accepted build and promote later releases through the same parity and failure suite.
Does a closed GitHub issue mean the failure no longer matters?
It may mean the specific defect was fixed, duplicated, not reproduced, or declined. The failure class still belongs in your regression suite because adjacent changes can recreate the same unsafe outcome.
How is this different from an agent-host protocol?
A protocol article explains how multiple clients can synchronize around host-owned sessions. This guide evaluates a concrete product's local service, configuration hierarchy, plugins, permissions, updates, worktrees, and recovery behavior.
Sources and further reading
Sources were accessed November 5, 2026. Official documentation defines intended behavior. GitHub issues and community discussions are bounded failure and adoption signals, not prevalence estimates.
- Anomaly: OpenCode 2.0 - first-party service, API, worktree, background-task, plugin, SDK, and upgrade architecture.
- OpenCode: Migrate from V1 - breaking changes, configuration precedence, policy authority, plugin/API migration, authentication, and verification guidance.
- OpenCode changelog - current service-registration, state-isolation, session-cleanup, recovery, permission, and update fixes.
- anomalyco/opencode - first-party repository and live project metadata.
- Hacker News: OpenCode 2.0 - launch discussion; engagement recorded during the research window.
- Issue #41696 - managed background-service startup timeout case.
- Issue #49982 - failed plugin reload and missing custom registry case.
- Issue #37521 - orphaned process and update-lock recovery case.
- Issue #52049 - event-stream watchdog restart and interrupted-session case.
- Issue #51216 - snapshot-related unresponsiveness and restart-loop case.
- The New Stack: OpenCode 2 shared service - independent architectural coverage.
- Related: persistent sessions and one state authority.
- Related: agent harness durability and recovery.
- Related: permission kernels for AI agents.
Related guides
Use the coding-agent sandbox guide for hostile-repository boundaries, the execution receipt guide for side-effect evidence, and the reversibility contract for compensation and rollback design.