Coding-agent runtime | November 5, 2026

OpenCode 2 turns one background service into your local agent control plane

A shared process can keep terminal, web, desktop, scripts, sessions, permissions, plugins, and worktrees coherent. It also concentrates failure. Before relying on OpenCode 2 for unattended work, prove which service is running, which policy it loaded, what survives a restart, and how every client fails when the answer is uncertain.

Service identity Policy parity Failure injection Evidence checked Nov 5
OpenCode clients connected to one tested background service and recovery gate

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.

ClaimStatic evidenceBehavioral probeBlock when
Right serviceEndpoint, PID, version, state directoryRestart and rediscover under version pinIdentity is absent, stale, or ambiguous
Policy parityEffective policy export and layer sourceAttempt a denied provider, MCP server, and pluginAny lower layer can override the deny
Permission parityResolved permission rules per agentRead, write, shell, network, and remote approval probesPrompt or decision differs from contract
Extension parityPlugin and agent inventory with versionsHot reload valid and invalid changesRegistry partially disappears or stays stale
Session durabilitySession IDs, worktree paths, active tasksKill service during model, shell, and subagent workWork is duplicated, lost silently, or misattributed
RollbackState backup and compatibility declarationRestore old binary against copied stateRollback 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 classObserved caseAcceptance testRequired behavior
Startup raceManaged server times out or a client cannot connectDelay bind and initialization beyond the normal pathBounded retry, real cause, no duplicate service
Orphaned updateOld process survives package replacement and keeps a lockReplace binary while the service owns registrationDetect stale identity; quarantine or cleanly stop it
Reload degradationFailed plugin reload drops custom registry entriesIntroduce an invalid plugin during hot reloadKeep prior registry; surface blocking error
False watchdog failureIdle event stream triggers restart and aborts workPause heartbeats while health API remains responsiveConfirm multi-signal failure before restart
Slow information pathSnapshot work delays health response and causes a loopBlock snapshot or status handler under loadSeparate health from heavy work; shed load safely
Version skewClient and service API contracts differConnect old client to new server and the reverseReject incompatibility with migration guidance
Workspace lossSession points to removed or changed worktreeDelete, move, and reuse the worktree pathStop writes; require explicit rebind
Unknown side effectService dies after dispatch but before receiptKill between tool request and completion recordReconcile 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

  1. Inventory the V1 installation, configuration layers, agents, commands, instructions, skills, plugins, MCP servers, providers, permissions, update mode, and integrations that call the server API.
  2. 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.
  3. Classify every rule as user preference or enforced policy. Convert administrative restrictions to V2 policies rather than ordinary settings.
  4. 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.
  5. Start V2 in a copied project and isolated state location. Pin the build and disable automatic updates for the validation lane.
  6. Compare effective agents, providers, permissions, MCP servers, plugins, models, and instructions with the frozen baseline. Investigate ignored-field warnings.
  7. Run positive and negative permission probes from TUI, desktop, web, API client, and any paired application in scope.
  8. Exercise session creation, worktree creation and movement, interruption, background shell work, subagents, compaction, snapshot, reconnect, and export.
  9. Inject startup, reload, update, version, workspace, dependency, and target-effect failures. Require honest state and a recovery receipt.
  10. 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.

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.