OpenHands 1.27 Makes ACP a Swappable Agent Layer

OpenHands 1.27.0 makes two more coding agents—OpenCode and Pi—first-class choices in Agent Canvas through the Agent Client Protocol (ACP). The important change is not two new logos. It is a clearer separation between the host that owns UI and backend selection, and the subprocess that owns the model, tools, and execution.

What shipped

The October 12 release adds OpenCode and Pi to onboarding and Settings as built-in ACP presets on local and self-hosted backends. OpenHands Cloud still exposes only Claude Code, Codex, and Gemini CLI; the new providers are explicitly marked local-only and filtered out for cloud backends.

Canvas does not hard-code their launch details. It reads commands, model defaults, and credential fields from the OpenHands SDK registry, then adds UI metadata. A saved built-in profile can therefore retain the preset while the registry resolves the actual command. Custom ACP servers remain available through a user-supplied command.

That is a useful interoperability shape: ACP is JSON-RPC over stdio, Agent Server owns the subprocess, and Canvas renders the conversation. The external agent keeps control of its model and tools rather than being reduced to another model endpoint.

Credentials are part of the protocol boundary

The implementation treats authentication as more than an API-key textbox.

For Pi, Canvas can pass PI_AUTH_JSON, corresponding to Pi's auth file, or ANTHROPIC_API_KEY. Its login probe does not merely test whether auth.json exists: Pi may create an empty {}, so the probe looks for a credential entry or a key.

For OpenCode, Canvas can pass OPENCODE_AUTH_CONTENT or OPENCODE_API_KEY. Its onboarding step stays skippable because OpenCode's documented default can run on a free model without credentials.

The tagged documentation says container credentials are stored as Agent Server secrets and referenced at conversation start; the server materializes file secrets for the child process. In other words, Canvas selects and configures an agent, but the runtime boundary still owns secret resolution and process launch.

There is an operational wrinkle: neither Pi nor OpenCode is preinstalled in the Agent Server image described by the release documentation. The first conversation can invoke them through npx, making package resolution and the upstream package registry part of the startup path. Operators who need deterministic or offline startup should account for that dependency rather than reading “built-in” as “bundled.”

Direct verification

I checked out the v1.27.0 tag at commit 3f5654ac02c2a74661daa224bcfc8962643a58f2, generated the repository's ignored i18n declarations with npm run make-i18n, and ran six focused Vitest files covering the ACP service, provider registry, onboarding, credential setup, and agent settings.

Result: 148 tests passed across six files. The passing cases included cloud/local provider filtering, Pi's non-empty-login detection, OpenCode preset retention with a custom Go model ID, provider credentials, and built-in provider defaults.

This was a focused local test, not a full release qualification. I did not run the Docker/live-ACP harness, start a real Pi or OpenCode subprocess, supply provider credentials, or reproduce the pull request's claimed end-to-end conversations. The run also emitted repeated accessibility warnings from the agent-settings suite and package source-map warnings, despite its passing status.

Why it matters

A protocol only becomes useful when products preserve its boundaries in ordinary setup, state, and credential flows. OpenHands 1.27.0 moves ACP closer to that standard: agent choice is backend-aware, commands come from a shared registry, credentials have explicit transport paths, and an agent can report its own models instead of forcing the host to maintain a universal catalogue.

The remaining risks are equally concrete. Local-only gating means ACP portability is not identical across deployments; dynamic npx startup weakens reproducibility unless versions and artifacts are controlled; and the live behavior still depends on each agent's authentication and error handling. OpenHands' own release notes flag one example: Pi may collapse an upstream provider failure into “No response from ACP server.”

This is meaningful progress toward swappable agent harnesses, but the dependable unit is still the whole chain: Canvas, Agent Server, registry metadata, package resolution, credentials, and the ACP implementation on the other end.