Skip to content

🙌 OpenHands: AI-Driven Development

feat(acp): add OpenCode and Pi as built-in ACP agents on local backends (#17758)

Placidoee54f35e6a17d
diff --git a/README.md b/README.md
index d03e0e12a6..a69cedcc73 100644
--- a/README.md
+++ b/README.md
@@ -7,7 +7,7 @@
<strong>The self-hosted developer control center for coding agents and automations.</strong>
</p>
<p align="center">
- Run OpenHands, Claude Code, Codex, Gemini, or any ACP-compatible agent across local, remote, and cloud backends.
+ Run OpenHands, Claude Code, Codex, Gemini, Pi, OpenCode, or any ACP-compatible agent across local, remote, and cloud backends.
</p>
</div>
<div align="center">
@@ -34,7 +34,7 @@ OpenHands Agent Canvas turns your coding agents into a self-hosted, always-on en
It runs locally on your machine by default, but can connect to multiple “agent backends”, e.g. running agents in Docker containers, on VMs, or within your company infrastructure. You can optionally choose to run agents on OpenHands Cloud or OpenHands Enterprise infrastructure.
-Agent Canvas runs the open source OpenHands agent out-of-the-box, but can use any third-party agent like Claude Code and Codex.
+Agent Canvas runs the open source OpenHands agent out-of-the-box, but can use third-party agents such as Claude Code, Codex, Gemini CLI, Pi, and OpenCode.
| | |
| -------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
@@ -43,7 +43,7 @@ Agent Canvas runs the open source OpenHands agent out-of-the-box, but can use an
| [**Create automations**](https://docs.openhands.dev/openhands/usage/agent-canvas/prebuilt-automations) | Create automations and workflows that integrate with Slack, GitHub, Linear, and more. Run on a schedule or in response to webhook events |
| [**Integrate with the tools you use**](https://docs.openhands.dev/openhands/usage/agent-canvas/prebuilt-automations) | Connect your automations with third-party services like Slack, GitHub, Notion, and more to automate workflows |
| [**Bring your own model**](https://docs.openhands.dev/openhands/usage/settings/llm-settings#llm-profiles) | Use with any LLM |
-| [**Use with any agent**](https://docs.openhands.dev/openhands/usage/agent-canvas/acp-agents) | Use with OpenHands, Claude Code, Codex, Gemini, or any agent with Agent-Client Protocol (ACP). |
+| [**Use with any agent**](https://docs.openhands.dev/openhands/usage/agent-canvas/acp-agents) | Use with OpenHands, Claude Code, Codex, Gemini, Pi, OpenCode, or any agent with Agent-Client Protocol (ACP). |
If you have questions or feedback, please open a GitHub issue or join the [#proj-agent-canvas channel in Slack](https://openhands.dev/joinslack).
diff --git a/__tests__/api/acp-service/acp-service.api.test.ts b/__tests__/api/acp-service/acp-service.api.test.ts
index d35a2b6cfc..8bc8005a71 100644
--- a/__tests__/api/acp-service/acp-service.api.test.ts
+++ b/__tests__/api/acp-service/acp-service.api.test.ts
@@ -1,3 +1,7 @@
+import { execFileSync } from "node:child_process";
+import { mkdtempSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
import { beforeEach, describe, expect, it, vi } from "vitest";
import type { BashOutput } from "@openhands/typescript-client";
import AcpService from "#/api/acp-service/acp-service.api";
@@ -121,6 +125,49 @@ describe("AcpService.getAuthStatus", () => {
});
});
+ describe("pi (auth.json entry or registry api key)", () => {
+ it("→ authenticated when a credential is present", async () => {
+ executeCommand.mockResolvedValue(bashOutput({ stdout: "present\n" }));
+ await expect(AcpService.getAuthStatus("pi")).resolves.toBe(
+ "authenticated",
+ );
+ });
+
+ it("reports pi's seeded empty auth.json as absent", async () => {
+ executeCommand.mockResolvedValue(bashOutput({ stdout: "absent\n" }));
+ await AcpService.getAuthStatus("pi");
+ const command = executeCommand.mock.calls[0][0] as string;
+ const agentDir = mkdtempSync(join(tmpdir(), "pi-probe-"));
+ const probe = (env: Record<string, string> = {}) =>
+ execFileSync("sh", ["-c", command], {
+ env: {
+ PATH: process.env.PATH,
+ PI_CODING_AGENT_DIR: agentDir,
+ ...env,
+ },
+ })
+ .toString()
+ .trim();
+
+ expect(probe()).toBe("absent");
+ writeFileSync(join(agentDir, "auth.json"), "{}");
+ expect(probe()).toBe("absent");
+ expect(probe({ ANTHROPIC_API_KEY: "sk-ant-test" })).toBe("present");
+ writeFileSync(
+ join(agentDir, "auth.json"),
+ JSON.stringify({ anthropic: { type: "api_key", key: "k" } }),
+ );
+ expect(probe()).toBe("present");
+ });
+
+ it("→ unauthenticated when no credential is present", async () => {
+ executeCommand.mockResolvedValue(bashOutput({ stdout: "absent\n" }));
+ await expect(AcpService.getAuthStatus("pi")).resolves.toBe(
+ "unauthenticated",
+ );
+ });
+ });
+
it("→ unknown for an unprobeable provider, without running any command", async () => {
await expect(AcpService.getAuthStatus("openhands")).resolves.toBe(
"unknown",
diff --git a/__tests__/components/onboarding/choose-agent-step.test.tsx b/__tests__/components/onboarding/choose-agent-step.test.tsx
index 3da8b4e2be..32e81c5035 100644
--- a/__tests__/components/onboarding/choose-agent-step.test.tsx
+++ b/__tests__/components/onboarding/choose-agent-step.test.tsx
@@ -2,13 +2,19 @@ import React from "react";
import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
import { render, screen, waitFor, within } from "@testing-library/react";
import userEvent from "@testing-library/user-event";
-import { beforeEach, describe, expect, it, vi } from "vitest";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
import {
AgentOptionIcon,
ChooseAgentStep,
type OnboardingAgentId,
} from "#/components/features/onboarding/steps/choose-agent-step";
import SettingsService from "#/api/settings-service/settings-service.api";
+import {
+ __resetActiveStoreForTests,
+ setActiveSelection,
+ setRegisteredBackends,
+} from "#/api/backend-registry/active-store";
+import { ActiveBackendProvider } from "#/contexts/active-backend-context";
import {
ACP_PROVIDERS,
getAcpPreferredDefaultModel,
@@ -40,23 +46,27 @@ describe("ChooseAgentStep", () => {
vi.spyOn(SettingsService, "saveSettings").mockResolvedValue(true);
});
- it("renders all four agent options with OpenHands marked selected by default", () => {
+ it("renders OpenHands and every ACP preset with OpenHands selected by default", () => {
renderStep();
const openhands = screen.getByTestId("onboarding-agent-option-openhands");
const claude = screen.getByTestId("onboarding-agent-option-claude-code");
const codex = screen.getByTestId("onboarding-agent-option-codex");
const gemini = screen.getByTestId("onboarding-agent-option-gemini-cli");
+ const pi = screen.getByTestId("onboarding-agent-option-pi");
+ const opencode = screen.getByTestId("onboarding-agent-option-opencode");
expect(openhands).toHaveAttribute("aria-checked", "true");
- // All four options are clickable — ACP is no longer "coming soon".
+ // All ACP options are clickable — ACP is no longer "coming soon".
expect(openhands).not.toBeDisabled();
expect(claude).not.toBeDisabled();
expect(codex).not.toBeDisabled();
expect(gemini).not.toBeDisabled();
+ expect(pi).not.toBeDisabled();
+ expect(opencode).not.toBeDisabled();
// Neither the legacy "coming soon" banner nor the per-option badges
- // should render now that all four agent kinds work end-to-end.
+ // should render now that all surfaced agent kinds work end-to-end.
expect(
screen.queryByTestId("onboarding-agent-coming-soon"),
).not.toBeInTheDocument();
@@ -81,6 +91,26 @@ describe("ChooseAgentStep", () => {
).not.toBeInTheDocument();
});
+ it.each([
+ ["pi", "pi"],
+ ["opencode", "opencode"],
+ ])(
+ "offers the %s tile with its brand mark on a local backend",
+ async (id, icon) => {
+ const { onSelect } = renderStep();
+ const tile = screen.getByTestId(`onboarding-agent-option-${id}`);
+
+ expect(
+ within(tile).getByTestId(`onboarding-agent-icon-${icon}`),
+ ).toBeInTheDocument();
+ expect(
+ within(tile).queryByTestId("onboarding-agent-icon-cli-generic"),
+ ).not.toBeInTheDocument();
+ await userEvent.setup().click(tile);
+ expect(onSelect).toHaveBeenLastCalledWith(id);
+ },
+ );
+
it("falls back to the generic CLI icon for a registry provider without an icon", () => {
ACP_PROVIDERS.push({
key: "future-cli",
@@ -126,6 +156,9 @@ describe("ChooseAgentStep", () => {
await user.click(screen.getByTestId("onboarding-agent-option-gemini-cli"));
expect(onSelect).toHaveBeenLastCalledWith("gemini-cli");
+ await user.click(screen.getByTestId("onboarding-agent-option-opencode"));
+ expect(onSelect).toHaveBeenLastCalledWith("opencode");
+
await user.click(screen.getByTestId("onboarding-agent-option-openhands"));
expect(onSelect).toHaveBeenLastCalledWith("openhands");
});
@@ -178,6 +211,8 @@ describe("ChooseAgentStep", () => {
it.each([
["codex", "codex"],
["gemini-cli", "gemini-cli"],
+ ["pi", "pi"],
+ ["opencode", "opencode"],
])("persists acp_server=%s for the matching tile", async (id, expected) => {
const save = vi.spyOn(SettingsService, "saveSettings");
renderStep(id as OnboardingAgentId);
@@ -201,6 +236,10 @@ describe("ChooseAgentStep", () => {
expect(
(call.agent_settings_diff as Record<string, unknown>).acp_model,
).toBe(getAcpPreferredDefaultModel(expected));
+ expect(call.agent_settings_diff).toMatchObject({
+ acp_command: [],
+ acp_args: [],
+ });
});
it("rebuilds the diff cleanly when the user flips between ACP providers", async () => {
@@ -283,3 +322,54 @@ describe("ChooseAgentStep", () => {
expect(onNext).not.toHaveBeenCalled();
});
});
+
+describe("ChooseAgentStep on a cloud backend", () => {
+ beforeEach(() => {
+ vi.restoreAllMocks();
+ __resetActiveStoreForTests();
+ setRegisteredBackends([
+ {
+ id: "cloud-1",
+ name: "Cloud",
+ host: "https://app.example.com",
+ apiKey: "key",
+ kind: "cloud",
+ },
+ ]);
+ setActiveSelection({ backendId: "cloud-1", orgId: null });
+ });
+ afterEach(() => {
+ window.localStorage.clear();
+ __resetActiveStoreForTests();
+ });
+
+ it("hides local-only agents and drops a selection Cloud can't run", () => {
+ const onSelect = vi.fn();
+ render(
+ <QueryClientProvider
+ client={
+ new QueryClient({ defaultOptions: { queries: { retry: false } } })
+ }
+ >
+ <ActiveBackendProvider>
+ <ChooseAgentStep
+ selectedAgentId="pi"
+ onSelect={onSelect}
+ onNext={vi.fn()}
+ />
+ </ActiveBackendProvider>
+ </QueryClientProvider>,
+ );
+
+ expect(
+ screen.getByTestId("onboarding-agent-option-claude-code"),
+ ).toBeInTheDocument();
+ expect(
+ screen.queryByTestId("onboarding-agent-option-pi"),
+ ).not.toBeInTheDocument();
+ expect(
+ screen.queryByTestId("onboarding-agent-option-opencode"),
+ ).not.toBeInTheDocument();
+ expect(onSelect).toHaveBeenCalledWith("openhands");
+ });
+});
diff --git a/__tests__/components/onboarding/setup-acp-secrets-step.test.tsx b/__tests__/components/onboarding/setup-acp-secrets-step.test.tsx
index 29eea47676..359930a1e9 100644
--- a/__tests__/components/onboarding/setup-acp-secrets-step.test.tsx
+++ b/__tests__/components/onboarding/setup-acp-secrets-step.test.tsx
@@ -261,6 +261,20 @@ describe("SetupAcpSecretsStep", () => {
).toBeInTheDocument();
});
+ it("renders OpenCode's auth store and API key, with no base URL", () => {
+ renderStep("opencode");
+
+ expect(
+ screen.getByTestId("onboarding-acp-secret-OPENCODE_AUTH_CONTENT"),
+ ).toBeInTheDocument();
+ expect(
+ screen.getByTestId("onboarding-acp-secret-OPENCODE_API_KEY"),
+ ).toHaveAttribute("type", "password");
+ expect(
+ screen.queryByTestId("onboarding-acp-secret-OPENCODE_BASE_URL"),
+ ).not.toBeInTheDocument();
+ });
+
it("shows no banner when the provider is not authenticated", () => {
acpAuthStatusMock.mockReturnValue({
status: "unauthenticated",
diff --git a/__tests__/constants/acp-providers.test.ts b/__tests__/constants/acp-providers.test.ts
index ca65e08aa4..eb47a29456 100644
--- a/__tests__/constants/acp-providers.test.ts
+++ b/__tests__/constants/acp-providers.test.ts
@@ -13,10 +13,12 @@ import {
} from "#/constants/acp-providers";
describe("getAcpProviderDisplayName", () => {
- it("resolves the three built-in registry keys to their human names", () => {
+ it("resolves the built-in registry keys to their human names", () => {
expect(getAcpProviderDisplayName("claude-code")).toBe("Claude Code");
expect(getAcpProviderDisplayName("codex")).toBe("Codex");
expect(getAcpProviderDisplayName("gemini-cli")).toBe("Gemini CLI");
+ expect(getAcpProviderDisplayName("pi")).toBe("Pi");
+ expect(getAcpProviderDisplayName("opencode")).toBe("OpenCode");
});
it("returns null for the Custom-command preset so callers can fall back to the generic 'ACP' label", () => {
@@ -62,7 +64,8 @@ describe("ACP provider registry", () => {
});
it("keeps every built-in default model in the UX suggestions", () => {
- for (const provider of ACP_PROVIDERS) {
+ // Pi has no default: it picks a model from whichever credential is set.
+ for (const provider of ACP_PROVIDERS.filter(({ key }) => key !== "pi")) {
expect(provider.default_model, provider.key).toBeTruthy();
expect(provider.available_models, provider.key).toBeTruthy();
expect(
@@ -152,6 +155,16 @@ describe("getAcpProviderSecrets — containerized credentials", () => {
]);
});
+ it("collects the auth.json blob, then the registry api key, for Pi", () => {
+ const names = getAcpProviderSecrets("pi").map((f) => f.name);
+ expect(names).toEqual(["PI_AUTH_JSON", "ANTHROPIC_API_KEY"]);
+ });
+
+ it("collects the auth store, then the Zen api key, for OpenCode", () => {
+ const names = getAcpProviderSecrets("opencode").map((f) => f.name);
+ expect(names).toEqual(["OPENCODE_AUTH_CONTENT", "OPENCODE_API_KEY"]);
+ });
+
it("renders file-content blobs as multiline secret fields", () => {
// ``multiline`` also drives the orphaned-credential warning on backends
// that can't materialise file secrets (cloud, agent-canvas#1016).
diff --git a/__tests__/routes/agent-settings.test.tsx b/__tests__/routes/agent-settings.test.tsx
index 7ad0964203..0abe572602 100644
--- a/__tests__/routes/agent-settings.test.tsx
+++ b/__tests__/routes/agent-settings.test.tsx
@@ -13,9 +13,16 @@ import { SecretsService } from "#/api/secrets-service";
import { MOCK_DEFAULT_USER_SETTINGS } from "#/mocks/handlers";
import { Settings } from "#/types/settings";
import { ACP_PROVIDERS } from "#/constants/acp-providers";
+import {
+ __resetActiveStoreForTests,
+ setActiveSelection,
+ setRegisteredBackends,
+} from "#/api/backend-registry/active-store";
+import { ActiveBackendProvider } from "#/contexts/active-backend-context";
import { parseCommand } from "#/utils/acp-command";
const CLAUDE_COMMAND = getClientAcpProvider("claude-code")!.default_command;
const CODEX_COMMAND = getClientAcpProvider("codex")!.default_command;
+const OPENCODE_PROVIDER = getClientAcpProvider("opencode")!;
// Stub the login-detection probe so the ACP credentials section doesn't spin a
// subprocess; default to no detected session so existing tests are unaffected.
@@ -189,6 +196,104 @@ describe("AgentSettingsScreen", () => {
});
});
+ it("offers OpenCode and leaves its default command to the profile resolver", async () => {
+ const user = userEvent.setup();
+ const { control } = renderAgentSettingsScreen({
+ agentSettingsOverride: CLAUDE_PROFILE,
+ });
+ await screen.findByTestId("agent-command-input");
+ await user.click(screen.getByTestId("agent-preset-selector"));
+ await user.click(await screen.findByRole("option", { name: "OpenCode" }));
+
+ expect(screen.getByTestId("agent-command-input")).toHaveValue(
+ OPENCODE_PROVIDER.default_command.join(" "),
+ );
+ expect(screen.getByLabelText("SETTINGS$AGENT_MODEL")).toHaveValue(
+ OPENCODE_PROVIDER.available_models.find(
+ ({ id }) => id === OPENCODE_PROVIDER.default_model,
+ )?.label,
+ );
+
+ expect(control().buildAgentProfileFields()).toMatchObject({
+ agent_kind: "acp",
+ acp_server: "opencode",
+ acp_command: null,
+ acp_args: null,
+ acp_model: OPENCODE_PROVIDER.default_model,
+ });
+ });
+
+ it.each([null, [...OPENCODE_PROVIDER.default_command]])(
+ "reloads OpenCode with command %j without losing its preset or model",
+ async (command) => {
+ const { control } = renderAgentSettingsScreen({
+ agentSettingsOverride: {
+ agent_kind: "acp",
+ acp_server: "opencode",
+ acp_command: command,
+ acp_model: OPENCODE_PROVIDER.default_model,
+ },
+ });
+
+ expect(await screen.findByTestId("agent-preset-selector")).toHaveValue(
+ "OpenCode",
+ );
+ expect(screen.getByTestId("agent-command-input")).toHaveValue(
+ OPENCODE_PROVIDER.default_command.join(" "),
+ );
+ expect(screen.getByLabelText("SETTINGS$AGENT_MODEL")).toHaveValue(
+ OPENCODE_PROVIDER.available_models.find(
+ ({ id }) => id === OPENCODE_PROVIDER.default_model,
+ )?.label,
+ );
+ // Old explicit defaults are cleared on the next save; new profiles
+ // resolve the current registry command rather than pinning a CLI version.
+ expect(control().buildAgentProfileFields()).toMatchObject({
+ acp_server: "opencode",
+ acp_command: null,
+ acp_model: OPENCODE_PROVIDER.default_model,
+ });
+ },
+ );
+
+ it.each(["opencode-go/kimi-k3"])(
+ "preserves the OpenCode preset when reopening and changing Go model %s",
+ async (model) => {
+ const user = userEvent.setup();
+ const { control } = renderAgentSettingsScreen({
+ agentSettingsOverride: {
+ agent_kind: "acp",
+ acp_server: "opencode",
+ acp_command: null,
+ acp_model: model,
+ },
+ });
+
+ expect(await screen.findByTestId("agent-preset-selector")).toHaveValue(
+ "OpenCode",
+ );
+ expect(screen.getByTestId("agent-model-input")).toHaveValue(model);
+ expect(control().buildAgentProfileFields()).toMatchObject({
+ acp_server: "opencode",
+ acp_command: null,
+ acp_model: model,
+ });
+
+ // Go IDs need not be in the SDK's static model suggestions. Changing
+ // the model must not turn the provider into a Custom ACP command.
+ await user.clear(screen.getByTestId("agent-model-input"));
+ await user.type(
+ screen.getByTestId("agent-model-input"),
+ "opencode-go/deepseek-v4-flash",
+ );
+ expect(control().buildAgentProfileFields()).toMatchObject({
+ acp_server: "opencode",
+ acp_command: null,
+ acp_model: "opencode-go/deepseek-v4-flash",
+ });
+ },
+ );
+
it("clears the model when switching from a built-in provider to Custom", async () => {
// Picking Custom must not leak the built-in default model onto an
// unrelated wrapper.
@@ -218,6 +323,77 @@ describe("AgentSettingsScreen", () => {
});
});
+ it("offers the Pi preset and leaves its model to Pi", async () => {
+ const pi = getClientAcpProvider("pi")!;
+ const user = userEvent.setup();
+ const { control } = renderAgentSettingsScreen({
+ agentSettingsOverride: CLAUDE_PROFILE,
+ });
+ await screen.findByTestId("agent-command-input");
+
+ await user.click(screen.getByTestId("agent-preset-selector"));
+ await user.click(await screen.findByRole("option", { name: "Pi" }));
+
+ expect(screen.getByTestId("agent-command-input")).toHaveValue(
+ pi.default_command.join(" "),
+ );
+ expect(control().buildAgentProfileFields()).toMatchObject({
+ acp_server: "pi",
+ acp_command: null,
+ acp_model: null,
+ });
+ });
+
+ it("hides the local-only presets on a cloud backend", async () => {
+ __resetActiveStoreForTests();
+ setRegisteredBackends([
+ {
+ id: "cloud-1",
+ name: "Cloud",
+ host: "https://app.example.com",
+ apiKey: "key",
+ kind: "cloud",
+ },
+ ]);
+ setActiveSelection({ backendId: "cloud-1", orgId: null });
+ try {
+ render(
+ <AgentSettingsScreen
+ agentSettingsOverride={CLAUDE_PROFILE}
+ onSaveControlChange={() => {}}
+ />,
+ {
+ wrapper: ({ children }) => (
+ <MemoryRouter>
+ <QueryClientProvider
+ client={
+ new QueryClient({
+ defaultOptions: { queries: { retry: false } },
+ })
+ }
+ >
+ <ActiveBackendProvider>{children}</ActiveBackendProvider>
+ </QueryClientProvider>
+ </MemoryRouter>
+ ),
+ },
+ );
+ await screen.findByTestId("agent-command-input");
+ await userEvent
+ .setup()
+ .click(screen.getByTestId("agent-preset-selector"));
+
+ expect(
+ await screen.findByRole("option", { name: "Codex" }),
+ ).toBeInTheDocument();
+ expect(screen.queryByRole("option", { name: "Pi" })).toBeNull();
+ expect(screen.queryByRole("option", { name: "OpenCode" })).toBeNull();
+ } finally {
+ window.localStorage.clear();
+ __resetActiveStoreForTests();
+ }
+ });
+
it("reconciles the model when the command is retyped to a different provider", async () => {
// The textarea is the other way to change provider, so it must drop the
// previous provider's model just like the preset dropdown does.
diff --git a/docs/ACP_AGENTS.md b/docs/ACP_AGENTS.md
index 4d5856ee96..fa5169ae03 100644
--- a/docs/ACP_AGENTS.md
+++ b/docs/ACP_AGENTS.md
@@ -1,7 +1,7 @@
# Using ACP agents
Agent Canvas can drive your conversations with the built-in **OpenHands** agent or
-with an external **ACP agent** — Claude Code, Codex, or Gemini CLI. This guide
+with an external **ACP agent** — Claude Code, Codex, Gemini CLI, Pi, or OpenCode. This guide
explains what ACP agents are, how to onboard one, and how to switch agents or
models later.
@@ -38,11 +38,19 @@ The provider list is sourced from the SDK registry
[`src/constants/acp-providers.ts`](../src/constants/acp-providers.ts). Adding or
changing a provider happens upstream in the SDK, not here.
-| Provider | Default command |
-| --------------- | ---------------------------------------------- |
-| **Claude Code** | `npx -y @agentclientprotocol/claude-agent-acp` |
-| **Codex** | `npx -y @agentclientprotocol/codex-acp` |
-| **Gemini CLI** | `npx -y @google/gemini-cli --acp` |
+| Provider | Default command |
+| --------------- | -------------------------------------------------------------------------- |
+| **Claude Code** | `npx -y @agentclientprotocol/claude-agent-acp` |
+| **Codex** | `npx -y @agentclientprotocol/codex-acp` |
+| **Gemini CLI** | `npx -y @google/gemini-cli --acp` |
+| **Pi** | `npx -y --package=pi-acp --package=@earendil-works/pi-coding-agent pi-acp` |
+| **OpenCode** | `npx -y opencode-ai acp` |
+
+Pi and OpenCode are offered on **local** backends only (your machine or a
+self-hosted Agent Server, including Docker); OpenHands Cloud runs only Claude
+Code, Codex, and Gemini CLI, so Canvas hides the other two there. Neither is
+pre-installed in the Agent Server image, so the first conversation downloads the
+CLI through `npx`.
See [Authentication](#authentication) for how each one authenticates.
@@ -69,8 +77,11 @@ needed instead.
| **Claude Code** | A Claude Code login (Pro/Max), from Claude Code's own credential store: the **macOS Keychain**, or `~/.claude/.credentials.json` on Linux | `ANTHROPIC_API_KEY` _(onboarding)_ |
| **Codex** | A ChatGPT login (`codex login`) cached at `~/.codex/auth.json` | `OPENAI_API_KEY` _(onboarding)_ |
| **Gemini CLI** | Your Google login (`gemini`/`gemini --acp`) cached at `~/.gemini/oauth_creds.json` | `GEMINI_API_KEY` _(onboarding)_ |
+| **Pi** | Any login or key saved by `pi` (`/login`) in `~/.pi/agent/auth.json` (or `$PI_CODING_AGENT_DIR`) | `ANTHROPIC_API_KEY` _(onboarding)_ |
+| **OpenCode** | Provider logins saved by `opencode auth login` in `~/.local/share/opencode/auth.json` | `OPENCODE_API_KEY` _(onboarding)_ |
-All three collect an _optional_ API key (+ base URL) in onboarding. As noted
+Each collects an _optional_ API key in onboarding (plus a base URL where the
+provider honours one — Pi and OpenCode do not). As noted
above, **a subscription / OAuth login takes priority over an API key** — when the
provider's CLI is signed in, a key set in the environment is not used. Verified
per provider:
@@ -88,6 +99,18 @@ per provider:
containers or multiple accounts) and signals the SDK to strip a conflicting
`ANTHROPIC_API_KEY` / `ANTHROPIC_BASE_URL`.
+Two providers behave differently:
+
+- **Pi** needs _some_ credential: with none, the session fails with
+ `Authentication required`. Pi picks its model from whichever provider that
+ credential unlocks, so Canvas doesn't preselect one. To route Pi through a
+ proxy, declare the provider in Pi's own `models.json`; `ANTHROPIC_BASE_URL`
+ is ignored. Pi's key is the same `ANTHROPIC_API_KEY` secret Claude Code
+ reads, and Claude Code then uses it instead of your Claude login.
+- **OpenCode** runs without any credential on OpenCode Zen's free models
+ (including its default, `opencode/big-pickle`), so its credential step never
+ blocks onboarding. A key or login unlocks the paid models.
+
The one exception is the **base URL** (`*_BASE_URL`): a custom value points the
CLI at a different endpoint (a proxy or gateway) and _does_ take effect even
under a login — for Gemini it rides the ACP `gateway` param. It's an advanced
@@ -97,8 +120,8 @@ override, not needed for normal use.
First-time users get a four-step onboarding modal. To onboard an ACP agent:
-1. **Choose agent** — pick Claude Code, Codex, or Gemini CLI instead of
- OpenHands. The choice is saved immediately to your backend's settings.
+1. **Choose agent** — pick Claude Code, Codex, Gemini CLI, Pi, or OpenCode
+ instead of OpenHands. The choice is saved immediately to your backend's settings.
2. **Check backend** — confirms Agent Canvas can reach the Agent Server.
3. **Set up credentials** — enter the provider's credentials. Beyond the API
key (+ optional base URL), this step also collects the credentials a
@@ -108,12 +131,16 @@ First-time users get a four-step onboarding modal. To onboard an ACP agent:
- **Gemini CLI** — `GOOGLE_APPLICATION_CREDENTIALS_JSON` (Vertex SA / ADC JSON)
plus `GOOGLE_CLOUD_PROJECT`, `GOOGLE_CLOUD_LOCATION`, and
`GOOGLE_GENAI_USE_VERTEXAI`.
+ - **Pi** — `PI_AUTH_JSON` (the contents of `~/.pi/agent/auth.json`).
+ - **OpenCode** — `OPENCODE_AUTH_CONTENT` (the contents of
+ `~/.local/share/opencode/auth.json`).
On a **local** backend the step is optional (a host login is reused
automatically); on a **Docker / cloud** backend it's **required**, because
there's no host login to fall back on. When the login probe detects an
existing session, the step shows a "you're already signed in" banner and
- stays skippable.
+ stays skippable. OpenCode's step is always skippable, since it can run on
+ free models without a credential.
4. **Say hello** — creates your first conversation and closes the modal.
@@ -173,8 +200,9 @@ SDK's `acp_file_secrets` defaults then:
Codex at it;
- materialise `GOOGLE_APPLICATION_CREDENTIALS_JSON` to a file referenced by
`GOOGLE_APPLICATION_CREDENTIALS` and route Gemini through Vertex AI;
-- export the rest (`CLAUDE_CODE_OAUTH_TOKEN`, project/location, API keys) as env
- vars for the CLI.
+- materialise `PI_AUTH_JSON` to `auth.json` under `PI_CODING_AGENT_DIR`;
+- export the rest (`CLAUDE_CODE_OAUTH_TOKEN`, `OPENCODE_AUTH_CONTENT`,
+ project/location, API keys) as env vars for the CLI.
Canvas just sends the secrets — it does **not** hand-roll the file
materialisation. The `npx -y <pkg>` command is rewritten to the pinned
@@ -218,14 +246,15 @@ grouping isolation is separate (agent-canvas#1016).
Open **Settings → Agent** at any time:
- **Agent** — switch between **OpenHands** and **ACP**.
-- **Preset** — pick a built-in provider (Claude Code, Codex, Gemini CLI) or
- **Custom** to point at any other ACP server.
+- **Preset** — pick a built-in provider (Claude Code, Codex, Gemini CLI, and,
+ on a local backend, Pi or OpenCode) or **Custom** to point at any other ACP
+ server.
- **Command** — the command line used to spawn the subprocess. Selecting a preset
fills this in; editing it to match another preset re-detects that provider.
API keys are _not_ entered here — they live in the Secrets panel.
- **Model** — choose a suggested model for the provider or enter a custom model
override. Built-in providers save a concrete model rather than leaving it
- blank.
+ blank — except Pi, which picks its own from the configured credential.
Saving writes an `agent_settings_diff` (`agent_kind`, `acp_server`,
`acp_command`, `acp_model`) to `PATCH /api/settings`. A running conversation
diff --git a/docs/README.md b/docs/README.md
index 9a47854e01..a282844f37 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -3,7 +3,7 @@
This directory contains the project documentation.
- [Architecture](./architecture.md): system boundaries, runtime modes, and quality gates.
-- [Using ACP agents](./ACP_AGENTS.md): onboard and configure external agents (Claude Code, Codex, Gemini CLI).
+- [Using ACP agents](./ACP_AGENTS.md): onboard and configure external agents (Claude Code, Codex, Gemini CLI, Pi, OpenCode).
- [Development guide](./DEVELOPMENT.md)
- [Canvas Extensions manual testing](./CANVAS_EXTENSIONS_TESTING.md)
- [Self-hosting guide](./SELF_HOSTING.md)
diff --git a/src/api/acp-service/acp-service.api.ts b/src/api/acp-service/acp-service.api.ts
index a73277547d..88dd9db3c7 100644
--- a/src/api/acp-service/acp-service.api.ts
+++ b/src/api/acp-service/acp-service.api.ts
@@ -52,10 +52,11 @@ function classifyCodex(out: BashOutput): AcpAuthStatus {
return "unknown";
}
-// Gemini CLI signs in via Google OAuth and has no status command, so we check
-// its credentials file. The command echoes present/absent and exits 0 either
-// way; anything else (a shell failure) ⇒ unknown.
-function classifyGemini(out: BashOutput): AcpAuthStatus {
+// Gemini CLI signs in via Google OAuth and Pi stores its logins in auth.json;
+// neither has a status command, so we check for the credential directly. The
+// command echoes present/absent and exits 0 either way; anything else (a shell
+// failure) ⇒ unknown.
+function classifyPresence(out: BashOutput): AcpAuthStatus {
// The command echoes exactly `present` / `absent` to stdout, so match trimmed
// stdout exactly. Reading only stdout (not stderr) means a stray shell
// warning can't turn a real result into `unknown`.
@@ -79,14 +80,20 @@ const ACP_AUTH_PROBES: Record<string, AcpAuthProbe> = {
"gemini-cli": {
command:
'test -f "$HOME/.gemini/oauth_creds.json" && echo present || echo absent',
- classify: classifyGemini,
+ classify: classifyPresence,
+ },
+ // Pi seeds an empty ``{}`` auth.json on first run, so require an entry.
+ pi: {
+ command:
+ '{ [ -n "$ANTHROPIC_API_KEY" ] || grep -qs \'"type"\' "${PI_CODING_AGENT_DIR:-$HOME/.pi/agent}/auth.json"; } && echo present || echo absent',
+ classify: classifyPresence,
},
};
/**
* Detects whether the selected ACP provider is already logged in — entirely
* client-side, with **no dedicated agent-server endpoint**. It runs the
- * provider's own status command (or, for Gemini, a credentials-file check)
+ * provider's own status command (or, for Gemini and Pi, a credentials check)
* through the existing agent-server bash endpoint and classifies the output.
*
* Gated by the caller to **local backends**: the command runs wherever the
diff --git a/src/components/features/onboarding/steps/choose-agent-step.tsx b/src/components/features/onboarding/steps/choose-agent-step.tsx
index 040de71521..623fbcb0f0 100644
--- a/src/components/features/onboarding/steps/choose-agent-step.tsx
+++ b/src/components/features/onboarding/steps/choose-agent-step.tsx
@@ -10,7 +10,10 @@ import {
ACP_PROVIDER_FALLBACK_ICON,
ACP_PROVIDERS,
buildAcpAgentSettingsDiff,
+ getAcpProvidersForBackend,
} from "#/constants/acp-providers";
+import type { BackendKind } from "#/api/backend-registry/types";
+import { useActiveBackend } from "#/contexts/active-backend-context";
import {
AgentBrandIcon,
type AgentBrandIconKind,
@@ -25,7 +28,9 @@ export type OnboardingAgentId =
| "openhands"
| "claude-code"
| "codex"
- | "gemini-cli";
+ | "gemini-cli"
+ | "pi"
+ | "opencode";
function getAgentOptionIcon(id: string): AgentBrandIconKind {
if (id === "openhands") return "openhands";
@@ -73,14 +78,14 @@ interface AgentOption {
// new provider (or changing a display name) only needs one edit in
// ``acp-providers.ts``. The OpenHands tile is the only synthetic
// entry — it isn't an ACP provider, just the canonical default.
-function getAgentOptions(): AgentOption[] {
+function getAgentOptions(backendKind: BackendKind): AgentOption[] {
return [
{
id: "openhands",
label: "OpenHands",
descriptionKey: I18nKey.ONBOARDING$AGENT_OPENHANDS_DESCRIPTION,
},
- ...ACP_PROVIDERS.map<AgentOption>((provider) => ({
+ ...getAcpProvidersForBackend(backendKind).map<AgentOption>((provider) => ({
id: provider.key as OnboardingAgentId,
label: provider.display_name,
descriptionKey: provider.description_key,
@@ -103,6 +108,15 @@ export function ChooseAgentStep({
}: ChooseAgentStepProps) {
const { t } = useTranslation("openhands");
const { mutate: saveSettings, isPending: isSaving } = useSaveSettings();
+ const backendKind = useActiveBackend().backend.kind;
+ const options = getAgentOptions(backendKind);
+ const isSelectionOffered = options.some(({ id }) => id === selectedAgentId);
+
+ // Switching to a backend that can't run the chosen agent (e.g. back to the
+ // backend step, then to Cloud) must not leave a hidden tile selected.
+ React.useEffect(() => {
+ if (!isSelectionOffered) onSelect("openhands");
+ }, [isSelectionOffered, onSelect]);
const handleNext = () => {
// The diff builder seeds the preferred default model (Vertex-safe for
@@ -150,7 +164,7 @@ export function ChooseAgentStep({
aria-label={t(I18nKey.ONBOARDING$AGENT_TITLE)}
className="flex flex-col gap-3"
>
- {getAgentOptions().map((option) => {
+ {options.map((option) => {
const isSelected = option.id === selectedAgentId;
return (
<button
diff --git a/src/components/shared/agent-brand-icon.tsx b/src/components/shared/agent-brand-icon.tsx
index eec2738954..62b98d48ba 100644
--- a/src/components/shared/agent-brand-icon.tsx
+++ b/src/components/shared/agent-brand-icon.tsx
@@ -7,6 +7,11 @@ import {
CODEX_VIEWBOX,
GEMINI_MARK_PATH,
GEMINI_VIEWBOX,
+ OPENCODE_MARK_INNER_PATH,
+ OPENCODE_MARK_OUTER_PATH,
+ OPENCODE_VIEWBOX,
+ PI_MARK_PATH,
+ PI_VIEWBOX,
} from "#/constants/acp-brand-marks";
import type { ACPProviderIcon } from "#/constants/acp-providers";
import { cn } from "#/utils/utils";
@@ -14,7 +19,7 @@ import { cn } from "#/utils/utils";
/**
* Icons the conversation chip + onboarding tiles can render. Strictly broader
* than {@link ACPProviderIcon} — that type covers ACP CLI subprocesses only
- * (Claude Code, Codex, Gemini, generic terminal fallback), whereas this type
+ * (plus the generic terminal fallback), whereas this type
* additionally includes the native OpenHands harness.
*/
export type AgentBrandIconKind = "openhands" | ACPProviderIcon;
@@ -106,6 +111,42 @@ export function AgentBrandIcon({
</svg>
);
}
+ if (kind === "pi") {
+ return (
+ <svg
+ xmlns="http://www.w3.org/2000/svg"
+ viewBox={PI_VIEWBOX}
+ width={size}
+ height={size}
+ className={cn("shrink-0", className)}
+ data-testid={testId ?? "agent-brand-icon-pi"}
+ aria-hidden
+ >
+ <path fill="currentColor" d={PI_MARK_PATH} />
+ </svg>
+ );
+ }
+ if (kind === "opencode") {
+ return (
+ <svg
+ xmlns="http://www.w3.org/2000/svg"
+ viewBox={OPENCODE_VIEWBOX}
+ width={size}
+ height={size}
+ className={cn("shrink-0", className)}
+ data-testid={testId ?? "agent-brand-icon-opencode"}
+ aria-hidden
+ >
+ <path
+ fillRule="evenodd"
+ clipRule="evenodd"
+ d={OPENCODE_MARK_OUTER_PATH}
+ fill="currentColor"
+ />
+ <path d={OPENCODE_MARK_INNER_PATH} fill="currentColor" opacity="0.35" />
+ </svg>
+ );
+ }
return (
<TerminalIcon
width={size}
diff --git a/src/constants/acp-brand-marks.ts b/src/constants/acp-brand-marks.ts
index ea510d7d4a..7066af47f9 100644
--- a/src/constants/acp-brand-marks.ts
+++ b/src/constants/acp-brand-marks.ts
@@ -16,3 +16,13 @@ export const CODEX_VIEWBOX = "0 0 12 12";
export const GEMINI_MARK_PATH =
"M12 0C12.904 6.056 17.944 11.096 24 12C17.944 12.904 12.904 17.944 12 24C11.096 17.944 6.056 12.904 0 12C6.056 11.096 11.096 6.056 12 0Z";
export const GEMINI_VIEWBOX = "0 0 24 24";
+
+export const PI_MARK_PATH =
+ "M420 280H280V140H0V0H420V280ZM560 560H420V280H560V560ZM140 560H0V140H140V280H280V420H140V560Z";
+export const PI_VIEWBOX = "0 0 560 560";
+
+// OpenCode's square logo; the inner path renders dimmed, as in the original.
+export const OPENCODE_MARK_OUTER_PATH =
+ "M210 60H90V240H210V60ZM270 300H30V0H270V300Z";
+export const OPENCODE_MARK_INNER_PATH = "M210 240H90V120H210V240Z";
+export const OPENCODE_VIEWBOX = "0 0 300 300";
diff --git a/src/constants/acp-providers.test.ts b/src/constants/acp-providers.test.ts
index 79251b0037..8f5e81227a 100644
--- a/src/constants/acp-providers.test.ts
+++ b/src/constants/acp-providers.test.ts
@@ -3,6 +3,7 @@ import { describe, expect, it } from "vitest";
import {
ACP_MANAGED_SENTINEL,
ACP_PROVIDERS,
+ getAcpProvidersForBackend,
getAcpProviderSecrets,
SURFACED_ACP_PROVIDERS,
resolveEffectiveAcpModel,
@@ -90,14 +91,24 @@ describe("surfaced ACP providers", () => {
(key) => !SURFACED_ACP_PROVIDERS.includes(key),
);
- it("surfaces only Claude Code, Codex and Gemini CLI", () => {
+ it("surfaces Claude Code, Codex, Gemini CLI, Pi and OpenCode", () => {
expect([...SURFACED_ACP_PROVIDERS]).toEqual([
"claude-code",
"codex",
"gemini-cli",
+ "pi",
+ "opencode",
]);
});
+ it("offers Pi and OpenCode on local backends only", () => {
+ const keys = (kind: "local" | "cloud") =>
+ getAcpProvidersForBackend(kind).map(({ key }) => key);
+
+ expect(keys("local")).toEqual([...SURFACED_ACP_PROVIDERS]);
+ expect(keys("cloud")).toEqual(["claude-code", "codex", "gemini-cli"]);
+ });
+
it("surfaces nothing the pinned client registry has dropped", () => {
// A rename or removal upstream must break loudly rather than leave a tile
// whose command and models resolve to nothing. An addition stays a no-op.
diff --git a/src/constants/acp-providers.ts b/src/constants/acp-providers.ts
index 9f9abc92b5..f22d601e6c 100644
--- a/src/constants/acp-providers.ts
+++ b/src/constants/acp-providers.ts
@@ -1,10 +1,13 @@
import { getAcpProvider as getClientAcpProvider } from "@openhands/typescript-client";
+import type { BackendKind } from "#/api/backend-registry/types";
import { I18nKey } from "#/i18n/declaration";
export type ACPProviderIcon =
| "claude-code"
| "codex"
| "gemini"
+ | "pi"
+ | "opencode"
| "cli-generic";
export const ACP_PROVIDER_FALLBACK_ICON: ACPProviderIcon = "cli-generic";
@@ -96,7 +99,7 @@ export interface ACPProviderConfig {
* still enter a custom override in Settings -> Agent.
*/
available_models?: ACPModelOption[];
- /** Model ID preselected for built-in providers so Canvas never saves blank. */
+ /** Model ID preselected for the provider; absent when it picks its own. */
default_model?: string;
/**
* i18n key for the one-line provider description rendered under the
@@ -111,6 +114,8 @@ export interface ACPProviderConfig {
* parse this registry without importing React components.
*/
icon?: ACPProviderIcon;
+ /** Offered only on local backends; Cloud runs a fixed set of providers. */
+ local_only?: boolean;
}
export interface ACPModelOption {
@@ -128,7 +133,7 @@ export interface ACPModelOption {
// offers — see {@link SURFACED_ACP_PROVIDERS}.
const ACP_PROVIDER_UI: Record<
string,
- { icon: ACPProviderIcon; description_key: I18nKey }
+ { icon: ACPProviderIcon; description_key: I18nKey; local_only?: boolean }
> = {
"claude-code": {
icon: "claude-code",
@@ -142,6 +147,16 @@ const ACP_PROVIDER_UI: Record<
icon: "gemini",
description_key: I18nKey.ONBOARDING$AGENT_GEMINI_CLI_DESCRIPTION,
},
+ pi: {
+ icon: "pi",
+ description_key: I18nKey.ONBOARDING$AGENT_PI_DESCRIPTION,
+ local_only: true,
+ },
+ opencode: {
+ icon: "opencode",
+ description_key: I18nKey.ONBOARDING$AGENT_OPENCODE_DESCRIPTION,
+ local_only: true,
+ },
};
function getAvailableModels(key: string): ACPModelOption[] | undefined {
@@ -175,9 +190,19 @@ export const ACP_PROVIDERS: ACPProviderConfig[] = Object.entries(
default_model: info?.default_model ?? undefined,
description_key: ui.description_key,
icon: ui.icon,
+ local_only: ui.local_only,
};
});
+/** The built-in ACP providers a backend of ``kind`` can launch. */
+export function getAcpProvidersForBackend(
+ kind: BackendKind,
+): ACPProviderConfig[] {
+ return kind === "cloud"
+ ? ACP_PROVIDERS.filter((provider) => !provider.local_only)
+ : ACP_PROVIDERS;
+}
+
export const ACP_CUSTOM_PRESET_KEY = "custom";
/**
@@ -267,6 +292,24 @@ const ACP_RESERVED_CREDENTIALS: Record<string, ACPProviderSecretField[]> = {
hint_key: I18nKey.ONBOARDING$ACP_SECRET_VERTEXAI_FLAG_HINT,
},
],
+ pi: [
+ {
+ name: "PI_AUTH_JSON",
+ secret: true,
+ multiline: true,
+ hint_key: I18nKey.ONBOARDING$ACP_SECRET_FILE_BLOB_HINT,
+ hint_values: { file: "~/.pi/agent/auth.json" },
+ },
+ ],
+ opencode: [
+ {
+ name: "OPENCODE_AUTH_CONTENT",
+ secret: true,
+ multiline: true,
+ hint_key: I18nKey.ONBOARDING$ACP_SECRET_AUTH_CONTENT_HINT,
+ hint_values: { file: "~/.local/share/opencode/auth.json" },
+ },
+ ],
};
/**
diff --git a/src/i18n/translation.json b/src/i18n/translation.json
index e77e1dded4..02094fd673 100644
--- a/src/i18n/translation.json
+++ b/src/i18n/translation.json
@@ -32928,6 +32928,40 @@
"tr": "Google'ın Gemini CLI aracısı.",
"uk": "Агент Gemini CLI від Google."
},
+ "ONBOARDING$AGENT_PI_DESCRIPTION": {
+ "en": "The open source Pi coding agent.",
+ "ja": "オープンソースのコーディングエージェント Pi。",
+ "zh-CN": "开源的 Pi 编程智能体。",
+ "zh-TW": "開源的 Pi 程式設計代理。",
+ "ko-KR": "오픈 소스 Pi 코딩 에이전트입니다.",
+ "no": "Pi, en åpen kildekode-agent for programmering.",
+ "ar": "وكيل البرمجة مفتوح المصدر Pi.",
+ "de": "Der quelloffene Coding-Agent Pi.",
+ "fr": "L'agent de programmation open source Pi.",
+ "it": "L'agente di programmazione open source Pi.",
+ "pt": "O agente de programação de código aberto Pi.",
+ "es": "El agente de programación de código abierto Pi.",
+ "ca": "L'agent de programació de codi obert Pi.",
+ "tr": "Açık kaynaklı Pi kodlama aracı.",
+ "uk": "Агент програмування з відкритим кодом Pi."
+ },
+ "ONBOARDING$AGENT_OPENCODE_DESCRIPTION": {
+ "en": "The open source OpenCode coding agent.",
+ "ja": "オープンソースのコーディングエージェント OpenCode。",
+ "zh-CN": "开源的 OpenCode 编程智能体。",
+ "zh-TW": "開源的 OpenCode 程式設計代理。",
+ "ko-KR": "오픈 소스 OpenCode 코딩 에이전트입니다.",
+ "no": "OpenCode, en åpen kildekode-agent for programmering.",
+ "ar": "وكيل البرمجة مفتوح المصدر OpenCode.",
+ "de": "Der quelloffene Coding-Agent OpenCode.",
+ "fr": "L'agent de programmation open source OpenCode.",
+ "it": "L'agente di programmazione open source OpenCode.",
+ "pt": "O agente de programação de código aberto OpenCode.",
+ "es": "El agente de programación de código abierto OpenCode.",
+ "ca": "L'agent de programació de codi obert OpenCode.",
+ "tr": "Açık kaynaklı OpenCode kodlama aracısı.",
+ "uk": "Агент програмування з відкритим кодом OpenCode."
+ },
"ONBOARDING$BACKEND_TITLE": {
"en": "Check your backend",
"ja": "バックエンドを確認",
@@ -36821,6 +36855,23 @@
"tr": "{{file}} dosyasının tüm içeriğini yapıştırın. Almak için `cat {{file}}` çalıştırın. Bir secret olarak kaydedilir ve çalışma zamanında aracı için diske yazılır.",
"uk": "Вставте повний вміст {{file}}. Виконайте `cat {{file}}`, щоб отримати його. Зберігається як секрет і записується на диск для агента під час виконання."
},
+ "ONBOARDING$ACP_SECRET_AUTH_CONTENT_HINT": {
+ "en": "Paste the full contents of {{file}}. Run `cat {{file}}` to get it. Saved as a secret and passed to the agent at runtime.",
+ "ja": "{{file}} の内容全体を貼り付けてください。`cat {{file}}` を実行して取得できます。シークレットとして保存され、実行時にエージェントへ渡されます。",
+ "zh-CN": "粘贴 {{file}} 的完整内容。运行 `cat {{file}}` 获取。它会作为密钥保存,并在运行时传递给智能体。",
+ "zh-TW": "貼上 {{file}} 的完整內容。執行 `cat {{file}}` 取得。將以密鑰形式儲存,並在執行時傳遞給代理。",
+ "ko-KR": "{{file}}의 전체 내용을 붙여넣으세요. `cat {{file}}`을 실행해 가져올 수 있습니다. 비밀로 저장되며 실행 시 에이전트에 전달됩니다.",
+ "no": "Lim inn hele innholdet i {{file}}. Kjør `cat {{file}}` for å hente det. Lagres som en hemmelighet og sendes til agenten ved kjøretid.",
+ "ar": "الصق المحتوى الكامل لـ {{file}}. شغّل `cat {{file}}` للحصول عليه. يُحفظ كسرّ ويُمرَّر إلى الوكيل عند التشغيل.",
+ "de": "Füge den vollständigen Inhalt von {{file}} ein. Führe `cat {{file}}` aus, um ihn zu erhalten. Wird als Secret gespeichert und zur Laufzeit an den Agenten übergeben.",
+ "fr": "Collez le contenu complet de {{file}}. Exécutez `cat {{file}}` pour l'obtenir. Enregistré comme secret et transmis à l'agent à l'exécution.",
+ "it": "Incolla l'intero contenuto di {{file}}. Esegui `cat {{file}}` per ottenerlo. Salvato come secret e passato all'agente in fase di esecuzione.",
+ "pt": "Cole o conteúdo completo de {{file}}. Execute `cat {{file}}` para obtê-lo. Salvo como secret e repassado ao agente em tempo de execução.",
+ "es": "Pega el contenido completo de {{file}}. Ejecuta `cat {{file}}` para obtenerlo. Se guarda como secreto y se pasa al agente en tiempo de ejecución.",
+ "ca": "Enganxa el contingut complet de {{file}}. Executa `cat {{file}}` per obtenir-lo. Es desa com a secret i es passa a l'agent en temps d'execució.",
+ "tr": "{{file}} dosyasının tüm içeriğini yapıştırın. Almak için `cat {{file}}` çalıştırın. Bir secret olarak kaydedilir ve çalışma zamanında araca iletilir.",
+ "uk": "Вставте повний вміст {{file}}. Виконайте `cat {{file}}`, щоб отримати його. Зберігається як секрет і передається агенту під час виконання."
+ },
"ONBOARDING$ACP_SECRET_OAUTH_TOKEN_HINT": {
"en": "Subscription OAuth token for Claude Pro/Max. Run `claude setup-token` in your terminal to get it.",
"ja": "Claude Pro/Max のサブスクリプション OAuth トークン。ターミナルで `claude setup-token` を実行して取得してください。",
diff --git a/src/routes/agent-settings.tsx b/src/routes/agent-settings.tsx
index 62a419e74c..6462e9fe1f 100644
--- a/src/routes/agent-settings.tsx
+++ b/src/routes/agent-settings.tsx
@@ -25,13 +25,14 @@ import {
normalizeFieldValue,
} from "#/utils/sdk-settings-schema";
import {
- ACP_PROVIDERS,
ACP_CUSTOM_PRESET_KEY,
getAcpPreferredDefaultModel,
getAcpProvider,
+ getAcpProvidersForBackend,
getAcpProviderSecrets,
type ACPProviderConfig,
} from "#/constants/acp-providers";
+import { useActiveBackend } from "#/contexts/active-backend-context";
import { parseCommand, formatCommand } from "#/utils/acp-command";
import {
readProfileScope,
@@ -313,6 +314,9 @@ export function AgentSettingsScreen({
const { data: schema } = useAgentSettingsSchema(
settings?.agent_settings_schema,
);
+ const acpProviders = getAcpProvidersForBackend(
+ useActiveBackend().backend.kind,
+ );
const fields = React.useMemo(
() => schema?.sections.flatMap((section) => section.fields),
@@ -503,7 +507,7 @@ export function AgentSettingsScreen({
// stable across the ``isLoading`` early-return below; ``detectPreset`` is a
// cheap pure lookup.
const acpPresetForCreds =
- agentType === "acp" ? detectPreset(commandText, ACP_PROVIDERS) : null;
+ agentType === "acp" ? detectPreset(commandText, acpProviders) : null;
const acpCredentialForm = useAcpCredentialForm(
acpPresetForCreds && acpPresetForCreds !== ACP_CUSTOM_PRESET_KEY
? acpPresetForCreds
@@ -723,7 +727,7 @@ export function AgentSettingsScreen({
const isAcp = agentType === "acp";
const commandTokens = parseCommand(commandText);
- const selectedPreset = detectPreset(commandText, ACP_PROVIDERS);
+ const selectedPreset = detectPreset(commandText, acpProviders);
const selectedProvider = getAcpProvider(selectedPreset);
const modelSuggestions = selectedProvider?.available_models ?? [];
const hasModelSuggestions = modelSuggestions.length > 0;
@@ -736,7 +740,7 @@ export function AgentSettingsScreen({
!!selectedProvider &&
commandTokens.join(" ") === selectedProvider.default_command.join(" ");
const commandPlaceholder =
- formatCommand(ACP_PROVIDERS[0]?.default_command ?? []) ||
+ formatCommand(acpProviders[0]?.default_command ?? []) ||
COMMAND_PLACEHOLDER_FALLBACK;
// Assign the control's field builder from the live render state.
@@ -790,7 +794,7 @@ export function AgentSettingsScreen({
const newType = key as AgentType;
setAgentType(newType);
if (newType === "acp" && !commandText) {
- const preferred = ACP_PROVIDERS[0];
+ const preferred = acpProviders[0];
if (preferred) {
setCommandText(formatCommand(preferred.default_command));
setAcpModel(getAcpPreferredDefaultModel(preferred.key) ?? "");
@@ -1145,7 +1149,7 @@ export function AgentSettingsScreen({
name="agent-preset"
label={t(I18nKey.SETTINGS$AGENT_PRESET)}
items={[
- ...ACP_PROVIDERS.map((provider) => ({
+ ...acpProviders.map((provider) => ({
key: provider.key,
label: provider.display_name,
})),
@@ -1201,8 +1205,8 @@ export function AgentSettingsScreen({
// reconciliation. Gated on the *detected preset* actually
// changing, so it never clobbers a model the user is editing
// within the same provider.
- const prevPreset = detectPreset(commandText, ACP_PROVIDERS);
- const nextPreset = detectPreset(nextCommandText, ACP_PROVIDERS);
+ const prevPreset = detectPreset(commandText, acpProviders);
+ const nextPreset = detectPreset(nextCommandText, acpProviders);
if (nextPreset !== prevPreset) {
setAcpModel(getAcpPreferredDefaultModel(nextPreset) ?? "");
setIsCustomAcpModel(false);
diff --git a/tests/e2e/live-acp/README.md b/tests/e2e/live-acp/README.md
index f4b6e02b0a..e959a99749 100644
--- a/tests/e2e/live-acp/README.md
+++ b/tests/e2e/live-acp/README.md
@@ -10,7 +10,8 @@ this asserts a real agent reply.
> **Requires `agent-server:1.25.0-python` or newer** (software-agent-sdk#3510):
> the ACP credentials ride as loopback LookupSecrets, and only #3510 resolves
-> them off the event loop. An older image deadlocks the first turn.
+> them off the event loop. An older image deadlocks the first turn. OpenCode
+> needs 1.45.0 or newer.
It is **not** part of `npm test` (it lives under `tests/`, which Vitest excludes,
and needs a running container + real host credentials).
@@ -18,25 +19,27 @@ and needs a running container + real host credentials).
## Run it
```bash
-# 1. Agent-server container. v1.28.0 adds the client_tools API used by Canvas.
+# 1. Agent-server container, at the version Canvas pins.
# The Python mount keeps pre-migration conversation state loadable.
docker run -d --name oh-acp -p 8010:8000 \
-v oh-acp-data:/workspace \
-v "$(pwd)/tools:/canvas-tools:ro" -e OH_EXTRA_PYTHON_PATH=/canvas-tools \
- ghcr.io/openhands/agent-server:1.28.0-python
+ ghcr.io/openhands/agent-server:1.53.0-python
# 2. Run the e2e (all providers, or a subset).
npx vite-node -c tests/e2e/live-acp/vite-node.config.mts \
- tests/e2e/live-acp/acp-docker-e2e.mts -- codex claude gemini
+ tests/e2e/live-acp/acp-docker-e2e.mts -- codex claude gemini opencode
# 3. Tear down (holds real creds).
docker rm -f oh-acp
```
Credentials are read from the host and **never printed**: Codex `~/.codex/auth.json`,
-the Claude Code OAuth token from the macOS keychain, and the gcloud ADC for Gemini
-Vertex (`gcloud auth application-default login` first). A provider whose creds
-aren't present is skipped.
+the Claude Code OAuth token from the macOS keychain, the gcloud ADC for Gemini
+Vertex (`gcloud auth application-default login` first), and the optional
+`OPENCODE_API_KEY`. OpenCode's default `opencode/big-pickle` model can complete
+the smoke test without a key; other providers are skipped when their required
+host credentials are absent.
The provider plans (models, credential collectors) and the HTTP/poll helpers are
shared between both scripts via `harness.mts` — change a model default or
@@ -58,6 +61,7 @@ deadlock, no "Failed to start ACP server: timed out"**, which is exactly what
| **Codex** | ✅ real reply `ACPOK-CODEX` (both scripts) | `Materialised ACP file-secret 'CODEX_AUTH_JSON' -> …/acp/codex/auth.json`; codex-acp 0.15.0; `Authenticating with ACP method: chatgpt` |
| **Claude Code** | ✅ real reply `ACPOK-CLAUDE` (both scripts) | claude-agent-acp 0.30.0; `CLAUDE_CODE_OAUTH_TOKEN` env path (no `ANTHROPIC_BASE_URL`) |
| **Gemini CLI** | ✅ real reply `ACPOK-GEMINI`¹ | `Materialised ACP file-secret 'GOOGLE_APPLICATION_CREDENTIALS_JSON' -> …/acp/gemini-cli/gcloud-credentials.json`; gemini-cli 0.45.1; `Authenticating with ACP method: vertex-ai` → real Vertex inference on `gemini-2.5-pro` |
+| **OpenCode** | ✅ real reply `ACPOK-OPENCODE` (app-path script, agent-server 1.49.6, 2026-09-28) | opencode-ai 1.18.23; default `opencode/big-pickle`, no API key |
¹ **Gemini prerequisites.** The full turn passes with: a **fresh** host ADC
(`gcloud auth application-default login` — a stale one fails as `invalid_rapt`,
@@ -71,6 +75,9 @@ software-agent-sdk#3532; this is why Canvas preselects `gemini-2.5-pro`), and
## Knobs
- `ACP_E2E_BASE_URL` (default `http://localhost:8010`)
-- `ACP_E2E_CODEX_MODEL` / `ACP_E2E_CLAUDE_MODEL` / `ACP_E2E_GEMINI_MODEL`
+- `ACP_E2E_SESSION_API_KEY` (optional `X-Session-API-Key` for an authenticated
+ Agent Server; never printed)
+- `ACP_E2E_CODEX_MODEL` / `ACP_E2E_CLAUDE_MODEL` / `ACP_E2E_GEMINI_MODEL` /
+ `ACP_E2E_OPENCODE_MODEL`
- `ACP_E2E_GEMINI_SESSION_MODE` (set `default` to bypass the SDK `yolo` blocker)
- `GOOGLE_CLOUD_PROJECT` / `GOOGLE_CLOUD_LOCATION` (else read from gcloud / `us-central1`)
diff --git a/tests/e2e/live-acp/acp-docker-app-e2e.mts b/tests/e2e/live-acp/acp-docker-app-e2e.mts
index 3e419558b6..fb793be380 100644
--- a/tests/e2e/live-acp/acp-docker-app-e2e.mts
+++ b/tests/e2e/live-acp/acp-docker-app-e2e.mts
@@ -63,8 +63,9 @@ async function run(plan: ProviderPlan): Promise<boolean> {
}
// 2) choose-agent step — persist ACP agent settings via the app's diff builder.
- const diff = buildAcpAgentSettingsDiff(plan.acpServer, { model: plan.model });
+ const diff = buildAcpAgentSettingsDiff(plan.acpServer);
if (!diff) throw new Error(`no settings diff for ${plan.acpServer}`);
+ diff.acp_model = plan.model;
if (plan.sessionMode) diff.acp_session_mode = plan.sessionMode;
await settingsClient.updateSettings({ agent_settings_diff: diff });
console.log(
@@ -119,7 +120,9 @@ async function main() {
const args = process.argv.slice(2).filter((a) => a !== "--");
const plan = args[0] ? getProviderPlan(args[0]) : undefined;
if (!plan) {
- console.error(`usage: ... acp-docker-app-e2e.mts -- <codex|claude|gemini>`);
+ console.error(
+ `usage: ... acp-docker-app-e2e.mts -- <codex|claude|gemini|opencode>`,
+ );
process.exit(2);
}
console.log(`App-path e2e against ${BASE} — provider: ${plan.id}`);
diff --git a/tests/e2e/live-acp/acp-docker-e2e.mts b/tests/e2e/live-acp/acp-docker-e2e.mts
index 0ed722313d..dd094b37a1 100644
--- a/tests/e2e/live-acp/acp-docker-e2e.mts
+++ b/tests/e2e/live-acp/acp-docker-e2e.mts
@@ -22,7 +22,7 @@
* -v "$(pwd)/tools:/canvas-tools:ro" -e OH_EXTRA_PYTHON_PATH=/canvas-tools \
* ghcr.io/openhands/agent-server:1.28.0-python
* npx vite-node -c tests/e2e/live-acp/vite-node.config.mts \
- * tests/e2e/live-acp/acp-docker-e2e.mts -- codex claude gemini
+ * tests/e2e/live-acp/acp-docker-e2e.mts -- codex claude gemini opencode
*
* The provider plans, host credential collectors, and HTTP/poll helpers are
* shared with the app-path script — see ./harness.mts. A provider whose
diff --git a/tests/e2e/live-acp/harness.mts b/tests/e2e/live-acp/harness.mts
index 2020bfc8c7..6b73d2a341 100644
--- a/tests/e2e/live-acp/harness.mts
+++ b/tests/e2e/live-acp/harness.mts
@@ -7,8 +7,8 @@
* between the two scripts.
*
* Credentials are read from the host and never printed: Codex
- * ~/.codex/auth.json, the Claude Code OAuth token from the macOS keychain, and
- * the gcloud ADC for Gemini Vertex.
+ * ~/.codex/auth.json, the Claude Code OAuth token from the macOS keychain,
+ * the gcloud ADC for Gemini Vertex, and the optional OpenCode API key.
*/
import { execFileSync } from "node:child_process";
import { readFileSync } from "node:fs";
@@ -21,6 +21,7 @@ import {
} from "#/api/backend-registry/active-store";
export const BASE = process.env.ACP_E2E_BASE_URL ?? "http://localhost:8010";
+const SESSION_API_KEY = process.env.ACP_E2E_SESSION_API_KEY ?? "";
export const POLL_TIMEOUT_MS = Number(
process.env.ACP_E2E_TIMEOUT_MS ?? 180_000,
);
@@ -37,14 +38,14 @@ export function registerDockerBackend(): void {
id: "acp-docker",
name: "ACP Docker",
host: BASE,
- apiKey: "",
+ apiKey: SESSION_API_KEY,
kind: "local",
},
]);
setActiveSelection({ backendId: "acp-docker", orgId: null });
}
-export type ProviderId = "codex" | "claude" | "gemini";
+export type ProviderId = "codex" | "claude" | "gemini" | "opencode";
export interface ProviderPlan {
id: ProviderId;
@@ -153,6 +154,17 @@ export const PROVIDER_PLANS: ProviderPlan[] = [
},
sessionMode: process.env.ACP_E2E_GEMINI_SESSION_MODE,
},
+ {
+ id: "opencode",
+ acpServer: "opencode",
+ model: process.env.ACP_E2E_OPENCODE_MODEL ?? "opencode/big-pickle",
+ expectedToken: "ACPOK-OPENCODE",
+ // The default model runs keyless; a host key still goes through LookupSecret.
+ collectSecrets: () =>
+ process.env.OPENCODE_API_KEY
+ ? { OPENCODE_API_KEY: process.env.OPENCODE_API_KEY }
+ : {},
+ },
];
export function getProviderPlan(id: string): ProviderPlan | undefined {
@@ -162,7 +174,10 @@ export function getProviderPlan(id: string): ProviderPlan | undefined {
export async function postJson(url: string, body: unknown): Promise<any> {
const res = await fetch(url, {
method: "POST",
- headers: { "Content-Type": "application/json" },
+ headers: {
+ "Content-Type": "application/json",
+ ...(SESSION_API_KEY ? { "X-Session-API-Key": SESSION_API_KEY } : {}),
+ },
body: JSON.stringify(body),
});
const text = await res.text();
@@ -173,7 +188,11 @@ export async function postJson(url: string, body: unknown): Promise<any> {
}
export async function getJson(url: string): Promise<any> {
- const res = await fetch(url);
+ const res = await fetch(url, {
+ headers: SESSION_API_KEY
+ ? { "X-Session-API-Key": SESSION_API_KEY }
+ : undefined,
+ });
const text = await res.text();
if (!res.ok) {
throw new Error(`GET ${url} -> ${res.status}: ${text.slice(0, 400)}`);
diff --git a/tests/e2e/live-acp/vite-node.config.mts b/tests/e2e/live-acp/vite-node.config.mts
index 1e0ea24608..ac98f95f7e 100644
--- a/tests/e2e/live-acp/vite-node.config.mts
+++ b/tests/e2e/live-acp/vite-node.config.mts
@@ -9,6 +9,10 @@ import { defineConfig } from "vite";
const srcDir = fileURLToPath(new URL("../../../src", import.meta.url));
export default defineConfig({
+ define: {
+ // Injected by the production Vite config; these scripts load no extension skills.
+ __EXTENSIONS_SKILLS_DIR__: JSON.stringify(""),
+ },
resolve: {
alias: [{ find: /^#\//, replacement: `${srcDir}/` }],
},