Skip to content

docs: document Devin as a built-in ACP provider #905

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
ScoFan-official wants to merge 1 commit into
base: main
Choose a base branch
from
+7 −4
Open

docs: document Devin as a built-in ACP provider #905

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 6 additions & 4 deletions openhands/usage/agent-canvas/acp-agents.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
---
title: ACP Agents
description: Run Claude Code, Codex, or Gemini CLI in Agent Canvas through the Agent Client Protocol.
description: Run Claude Code, Codex, Devin, or Gemini CLI in Agent Canvas through the Agent Client Protocol.
---

Use this guide when you want to bring Claude Code, Codex, or other agent CLIs into Agent Canvas. Agent Canvas can drive conversations with the built-in **OpenHands** agent or with an external **ACP agent**. For an ACP agent, the selected backend launches the provider's CLI and must have access to its subscription login or API key.
Expand Down Expand Up @@ -29,6 +29,7 @@ The Agent Server owns the subprocess and the credentials; Agent Canvas only reco
|---|---|
| **Claude Code** | `npx -y @agentclientprotocol/claude-agent-acp` |
| **Codex** | `npx -y @zed-industries/codex-acp` |
| **Devin** | `devin acp` |
| **Gemini CLI** | `npx -y @google/gemini-cli --acp` |

The provider list is sourced from the OpenHands SDK registry (`openhands.sdk.settings.acp_providers`, mirrored into `@openhands/typescript-client`) and enriched with Canvas UI metadata. Adding or changing a provider happens upstream in the SDK.
Expand All @@ -45,9 +46,10 @@ A "subscription login" is the credential the provider's own CLI stores when you
|---|---|---|
| **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` |
| **Codex** | A ChatGPT login (`codex login`) cached at `~/.codex/auth.json` | `OPENAI_API_KEY` |
| **Devin** | — (`devin acp` deliberately ignores local CLI credentials, so usage is attributed to the account owning the key) | `WINDSURF_API_KEY` (required) |
| **Gemini CLI** | Your Google login (`gemini`/`gemini --acp`) cached at `~/.gemini/oauth_creds.json` | `GEMINI_API_KEY` |

All three collect an *optional* API key (plus base URL) in onboarding. 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:
These providers collect an *optional* API key (plus base URL) in onboarding — except **Devin**, where the key is required because there is no stored-login fallback. 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:

- **Codex** — `codex login status` keeps reporting the ChatGPT login even with `OPENAI_API_KEY` set.
- **Gemini CLI** — uses the OAuth auth type chosen at `gemini` login; `GEMINI_API_KEY` is only consulted if you switch the auth type. The free Google login is the common no-key path locally — sign in once and it just works.
Expand All @@ -59,7 +61,7 @@ The one exception is the **base URL** (`*_BASE_URL`): a custom value points the

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, Devin, or Gemini CLI 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 API key (and, optionally, a custom base URL for a proxy or gateway). All three providers collect these here, and every field is optional.
4. **Say hello** — creates your first conversation and closes the modal.
Expand All @@ -77,7 +79,7 @@ Each credential you enter is saved as a **global secret** whose name is exactly
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, Devin, Gemini CLI) 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.

Expand Down
1 change: 1 addition & 0 deletions sdk/guides/agent-acp.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -155,6 +155,7 @@ When the ACP server advertises authentication methods, `ACPAgent` automatically

1. **ChatGPT subscription login** — If the server supports a `chatgpt` auth method and `~/.codex/auth.json` exists (created by `LLM.subscription_login()`), this is selected first. This enables ACP-backed workflows to use device-code login credentials without an explicit API key.
2. **API key environment variables** — Falls back to checking for `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, or `GEMINI_API_KEY` depending on which auth methods the server supports.
3. **Request-payload keys** — Some servers take the credential on the `authenticate` request itself instead of reading the environment. For Devin (`devin acp`), the `devin-browser` method is selected when `WINDSURF_API_KEY` is set and the key is sent as `_meta.api_key` on the `authenticate` call — Devin deliberately ignores local CLI credentials in ACP mode, so the key is always required.

If no supported credential source is found, the server may proceed without authentication (some servers don't require it).

Expand Down