Skip to content

🙌 OpenHands: AI-Driven Development

feat(onboarding): collect ACP provider API keys and store as secrets (#967)

simonrosenberga46156b23141
diff --git a/.pr/mcp-evidence/mcp-catalog-all-43-entries.png b/.pr/mcp-evidence/mcp-catalog-all-43-entries.png
deleted file mode 100644
index 614890df91..0000000000
Binary files a/.pr/mcp-evidence/mcp-catalog-all-43-entries.png and /dev/null differ
diff --git a/.pr/mcp-evidence/mcp-marketplace-all-entries.png b/.pr/mcp-evidence/mcp-marketplace-all-entries.png
deleted file mode 100644
index faa8eae6b5..0000000000
Binary files a/.pr/mcp-evidence/mcp-marketplace-all-entries.png and /dev/null differ
diff --git a/.pr/mcp-evidence/pr-757-everything-installed-e1c24fb.png b/.pr/mcp-evidence/pr-757-everything-installed-e1c24fb.png
deleted file mode 100644
index 6efa5c4dbd..0000000000
Binary files a/.pr/mcp-evidence/pr-757-everything-installed-e1c24fb.png and /dev/null differ
diff --git a/__tests__/components/onboarding/onboarding-modal.test.tsx b/__tests__/components/onboarding/onboarding-modal.test.tsx
index e6c4736788..883dab5c24 100644
--- a/__tests__/components/onboarding/onboarding-modal.test.tsx
+++ b/__tests__/components/onboarding/onboarding-modal.test.tsx
@@ -9,6 +9,7 @@ import { ActiveBackendProvider } from "#/contexts/active-backend-context";
import { OnboardingModal } from "#/components/features/onboarding/onboarding-modal";
import { NavigationProvider } from "#/context/navigation-context";
import SettingsService from "#/api/settings-service/settings-service.api";
+import { SecretsService } from "#/api/secrets-service";
const llmSettingsScreenMock = vi.hoisted(() => vi.fn());
@@ -109,11 +110,20 @@ function renderModal(onClose = vi.fn()) {
beforeEach(() => {
window.localStorage.clear();
__resetActiveStoreForTests();
- llmSettingsScreenMock.mockClear();
+ // Clear accumulated spy/mock call history so per-test assertions (the
+ // ACP secret-write checks and the LLM-defaults mock) don't see calls
+ // leaked from a prior test. Covers `llmSettingsScreenMock` too.
+ vi.clearAllMocks();
// ChooseAgentStep's Next button now persists the selection via
// saveSettings before advancing. Stub it so the rest of the flow
// (which these tests focus on) isn't gated on a real HTTP call.
vi.spyOn(SettingsService, "saveSettings").mockResolvedValue(true);
+ // The ACP secrets step lists existing secrets to flag "already saved"
+ // fields. Stub the fetch so it doesn't reach a real client (none is
+ // wired up in this test) and the field placeholders stay in the
+ // not-yet-saved state.
+ vi.spyOn(SecretsService, "getSecrets").mockResolvedValue([]);
+ vi.spyOn(SecretsService, "createSecret").mockResolvedValue();
});
afterEach(() => {
window.localStorage.clear();
@@ -273,12 +283,14 @@ describe("OnboardingModal", () => {
expect(settings.contains(next)).toBe(false);
});
- it("skips the LLM-setup step when the user picks an ACP agent", async () => {
+ it("skips the step-2 slide for an ACP agent with no credentials to collect", async () => {
renderModal();
const user = userEvent.setup();
- // Pick Claude Code, then advance from Choose Agent → Check Backend.
- await user.click(screen.getByTestId("onboarding-agent-option-claude-code"));
+ // Pick Gemini CLI: it authenticates via an interactive OAuth login
+ // (no env-var API key), so it has no credentials step and slide 2 is
+ // skipped — unlike Claude Code / Codex, which now render one there.
+ await user.click(screen.getByTestId("onboarding-agent-option-gemini-cli"));
await user.click(screen.getByTestId("onboarding-agent-next"));
await waitFor(
() =>
@@ -290,8 +302,7 @@ describe("OnboardingModal", () => {
);
// Advancing again should jump straight to Say Hello (index 3) and
- // bypass the LLM form — ACP agents own their own LLM via the
- // subprocess.
+ // bypass slide 2 — Gemini owns its own auth via the OAuth login.
await waitFor(
() =>
expect(
@@ -340,6 +351,111 @@ describe("OnboardingModal", () => {
);
});
+ it("shows the ACP credentials step on slide 2 for Claude Code and saves entered keys as secrets", async () => {
+ renderModal();
+ const user = userEvent.setup();
+
+ // Pick Claude Code → Check Backend.
+ await user.click(screen.getByTestId("onboarding-agent-option-claude-code"));
+ await user.click(screen.getByTestId("onboarding-agent-next"));
+ await waitFor(
+ () =>
+ expect(
+ screen.getByTestId("onboarding-backend-next"),
+ ).not.toBeDisabled(),
+ { timeout: 3000 },
+ );
+ await user.click(screen.getByTestId("onboarding-backend-next"));
+
+ // Slide 2 is the ACP credentials step (not skipped), so the flow keeps
+ // all 4 progress segments and slide 2 — not Say Hello — is now active.
+ await waitFor(
+ () =>
+ expect(screen.getByTestId("onboarding-modal")).toHaveAttribute(
+ "data-current-step",
+ "2",
+ ),
+ { timeout: 3000 },
+ );
+ expect(screen.getByTestId("onboarding-slide-2")).toHaveAttribute(
+ "data-active",
+ "true",
+ );
+ expect(
+ screen.getByTestId("onboarding-step-setup-acp-secrets"),
+ ).toBeInTheDocument();
+ expect(
+ screen.getByTestId("onboarding-progress-step-3"),
+ ).toBeInTheDocument();
+
+ // Both Anthropic credentials are offered; the optional base URL too.
+ const apiKeyField = screen.getByTestId(
+ "onboarding-acp-secret-ANTHROPIC_API_KEY",
+ );
+ expect(apiKeyField).toBeInTheDocument();
+ expect(
+ screen.getByTestId("onboarding-acp-secret-ANTHROPIC_BASE_URL"),
+ ).toBeInTheDocument();
+
+ // Fill the API key and advance: the value is upserted as a global
+ // secret of the same name, then the flow moves on to Say Hello.
+ await user.type(apiKeyField, "sk-ant-test");
+ await user.click(screen.getByTestId("onboarding-acp-secrets-next"));
+
+ await waitFor(() => {
+ expect(SecretsService.createSecret).toHaveBeenCalledWith(
+ "ANTHROPIC_API_KEY",
+ "sk-ant-test",
+ undefined,
+ );
+ });
+ await waitFor(
+ () =>
+ expect(screen.getByTestId("onboarding-modal")).toHaveAttribute(
+ "data-current-step",
+ "3",
+ ),
+ { timeout: 3000 },
+ );
+ });
+
+ it("skips the secret write when the ACP credentials step is left blank", async () => {
+ renderModal();
+ const user = userEvent.setup();
+
+ await user.click(screen.getByTestId("onboarding-agent-option-codex"));
+ await user.click(screen.getByTestId("onboarding-agent-next"));
+ await waitFor(
+ () =>
+ expect(
+ screen.getByTestId("onboarding-backend-next"),
+ ).not.toBeDisabled(),
+ { timeout: 3000 },
+ );
+ await user.click(screen.getByTestId("onboarding-backend-next"));
+ await waitFor(
+ () =>
+ expect(screen.getByTestId("onboarding-modal")).toHaveAttribute(
+ "data-current-step",
+ "2",
+ ),
+ { timeout: 3000 },
+ );
+
+ // Leaving every field empty is a deliberate skip — no secret is
+ // written, and the user still advances to Say Hello.
+ await user.click(screen.getByTestId("onboarding-acp-secrets-next"));
+ await waitFor(
+ () =>
+ expect(screen.getByTestId("onboarding-modal")).toHaveAttribute(
+ "data-current-step",
+ "3",
+ ),
+ { timeout: 3000 },
+ );
+ expect(SecretsService.createSecret).not.toHaveBeenCalled();
+ });
+
it("pre-fills the say-hello input with the default greeting on step 3", async () => {
renderModal();
const user = userEvent.setup();
diff --git a/__tests__/components/onboarding/setup-acp-secrets-step.test.tsx b/__tests__/components/onboarding/setup-acp-secrets-step.test.tsx
new file mode 100644
index 0000000000..8fb4491a0f
--- /dev/null
+++ b/__tests__/components/onboarding/setup-acp-secrets-step.test.tsx
@@ -0,0 +1,178 @@
+import React from "react";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import { render, screen, waitFor } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+import { __resetActiveStoreForTests } from "#/api/backend-registry/active-store";
+import { ActiveBackendProvider } from "#/contexts/active-backend-context";
+import { SetupAcpSecretsStep } from "#/components/features/onboarding/steps/setup-acp-secrets-step";
+import { type OnboardingAgentId } from "#/components/features/onboarding/steps/choose-agent-step";
+import { SecretsService } from "#/api/secrets-service";
+
+function renderStep(providerKey: OnboardingAgentId = "claude-code") {
+ const onBack = vi.fn();
+ const onNext = vi.fn();
+ render(
+ <QueryClientProvider
+ client={
+ new QueryClient({ defaultOptions: { queries: { retry: false } } })
+ }
+ >
+ <ActiveBackendProvider>
+ <SetupAcpSecretsStep
+ providerKey={providerKey}
+ onBack={onBack}
+ onNext={onNext}
+ />
+ </ActiveBackendProvider>
+ </QueryClientProvider>,
+ );
+ return { onBack, onNext };
+}
+
+beforeEach(() => {
+ vi.restoreAllMocks();
+ __resetActiveStoreForTests();
+ vi.spyOn(SecretsService, "getSecrets").mockResolvedValue([]);
+ vi.spyOn(SecretsService, "createSecret").mockResolvedValue();
+});
+afterEach(() => {
+ __resetActiveStoreForTests();
+});
+
+describe("SetupAcpSecretsStep", () => {
+ it("renders the provider's API key and optional base URL fields", () => {
+ renderStep("codex");
+
+ expect(
+ screen.getByTestId("onboarding-acp-secret-OPENAI_API_KEY"),
+ ).toBeInTheDocument();
+ expect(
+ screen.getByTestId("onboarding-acp-secret-OPENAI_BASE_URL"),
+ ).toBeInTheDocument();
+ // The API key is a password field; the base URL is a plain text input.
+ expect(
+ screen.getByTestId("onboarding-acp-secret-OPENAI_API_KEY"),
+ ).toHaveAttribute("type", "password");
+ expect(
+ screen.getByTestId("onboarding-acp-secret-OPENAI_BASE_URL"),
+ ).toHaveAttribute("type", "text");
+ });
+
+ it("flags a credential that already exists as a saved secret", async () => {
+ vi.spyOn(SecretsService, "getSecrets").mockResolvedValue([
+ { name: "ANTHROPIC_API_KEY" },
+ ]);
+ renderStep("claude-code");
+
+ // The already-saved field carries a non-empty placeholder hint; a
+ // not-yet-saved field (base URL) does not.
+ const apiKey = screen.getByTestId(
+ "onboarding-acp-secret-ANTHROPIC_API_KEY",
+ ) as HTMLInputElement;
+ const baseUrl = screen.getByTestId(
+ "onboarding-acp-secret-ANTHROPIC_BASE_URL",
+ ) as HTMLInputElement;
+ await waitFor(() => expect(apiKey.placeholder.length).toBeGreaterThan(0));
+ expect(baseUrl.placeholder).toBe("");
+ });
+
+ it("does not write an existing secret when its field is left blank", async () => {
+ vi.spyOn(SecretsService, "getSecrets").mockResolvedValue([
+ { name: "ANTHROPIC_API_KEY" },
+ ]);
+ const { onNext } = renderStep("claude-code");
+ const user = userEvent.setup();
+
+ // Wait for the existing secret to register (its "already saved" placeholder
+ // appears) so we know the step has loaded before we advance.
+ const apiKey = screen.getByTestId(
+ "onboarding-acp-secret-ANTHROPIC_API_KEY",
+ ) as HTMLInputElement;
+ await waitFor(() => expect(apiKey.placeholder.length).toBeGreaterThan(0));
+
+ // Advance without typing: a blank field is a deliberate skip, so the
+ // already-saved secret must be left untouched (no overwrite).
+ await user.click(screen.getByTestId("onboarding-acp-secrets-next"));
+
+ await waitFor(() => expect(onNext).toHaveBeenCalledTimes(1));
+ expect(SecretsService.createSecret).not.toHaveBeenCalled();
+ });
+
+ it("overwrites an existing secret when the user types a replacement", async () => {
+ // Key rotation: a credential is already saved, the user types a new value
+ // over it. The blank-skip guard must not suppress this — the new value has
+ // to be written even though the secret already exists.
+ vi.spyOn(SecretsService, "getSecrets").mockResolvedValue([
+ { name: "ANTHROPIC_API_KEY" },
+ ]);
+ const { onNext } = renderStep("claude-code");
+ const user = userEvent.setup();
+
+ const apiKey = screen.getByTestId(
+ "onboarding-acp-secret-ANTHROPIC_API_KEY",
+ ) as HTMLInputElement;
+ await waitFor(() => expect(apiKey.placeholder.length).toBeGreaterThan(0));
+
+ await user.type(apiKey, "sk-ant-new-key");
+ await user.click(screen.getByTestId("onboarding-acp-secrets-next"));
+
+ await waitFor(() => {
+ expect(SecretsService.createSecret).toHaveBeenCalledWith(
+ "ANTHROPIC_API_KEY",
+ "sk-ant-new-key",
+ undefined,
+ );
+ expect(onNext).toHaveBeenCalledTimes(1);
+ });
+ });
+
+ it("upserts every filled field as a secret and then advances", async () => {
+ const { onNext } = renderStep("claude-code");
+ const user = userEvent.setup();
+
+ await user.type(
+ screen.getByTestId("onboarding-acp-secret-ANTHROPIC_API_KEY"),
+ "sk-ant-123",
+ );
+ await user.type(
+ screen.getByTestId("onboarding-acp-secret-ANTHROPIC_BASE_URL"),
+ "https://proxy.example.com",
+ );
+ await user.click(screen.getByTestId("onboarding-acp-secrets-next"));
+
+ await waitFor(() => {
+ expect(SecretsService.createSecret).toHaveBeenCalledWith(
+ "ANTHROPIC_API_KEY",
+ "sk-ant-123",
+ undefined,
+ );
+ expect(SecretsService.createSecret).toHaveBeenCalledWith(
+ "ANTHROPIC_BASE_URL",
+ "https://proxy.example.com",
+ undefined,
+ );
+ expect(onNext).toHaveBeenCalledTimes(1);
+ });
+ });
+
+ it("does not advance when a secret write fails", async () => {
+ vi.spyOn(SecretsService, "createSecret").mockRejectedValue(
+ new Error("boom"),
+ );
+ const { onNext } = renderStep("claude-code");
+ const user = userEvent.setup();
+
+ await user.type(
+ screen.getByTestId("onboarding-acp-secret-ANTHROPIC_API_KEY"),
+ "sk-ant-123",
+ );
+ await user.click(screen.getByTestId("onboarding-acp-secrets-next"));
+
+ await waitFor(() =>
+ expect(SecretsService.createSecret).toHaveBeenCalledTimes(1),
+ );
+ expect(onNext).not.toHaveBeenCalled();
+ });
+});
diff --git a/src/components/features/onboarding/onboarding-modal.tsx b/src/components/features/onboarding/onboarding-modal.tsx
index 7550933e33..f93d9aaefe 100644
--- a/src/components/features/onboarding/onboarding-modal.tsx
+++ b/src/components/features/onboarding/onboarding-modal.tsx
@@ -14,7 +14,9 @@ import {
} from "./steps/choose-agent-step";
import { CheckBackendStep } from "./steps/check-backend-step";
import { SetupLlmStep } from "./steps/setup-llm-step";
+import { SetupAcpSecretsStep } from "./steps/setup-acp-secrets-step";
import { SayHelloStep } from "./steps/say-hello-step";
+import { getAcpProviderSecrets } from "#/constants/acp-providers";
const TOTAL_STEPS = 4;
@@ -86,39 +88,49 @@ export function OnboardingModal({ onClose }: OnboardingModalProps) {
const [selectedAgentId, setSelectedAgentId] =
React.useState<OnboardingAgentId>("openhands");
- // The LLM-setup step (index 2) is OpenHands-specific: ACP agents drive
- // their own LLM via the subprocess and authenticate through the Secrets
- // panel, so there's nothing to configure in that form for them. Skip
- // over it in both directions when the user has picked an ACP agent,
- // keeping the rest of the flow intact (back from SayHello on the ACP
- // path returns to ChooseAgent, not to a dead-end LLM page).
- const skipLlmStep = selectedAgentId !== "openhands";
+ // Slide index 2 is the "provider credentials" slot. Its content depends on
+ // the chosen agent:
+ // * OpenHands → the LLM-setup form (its own LLM config).
+ // * Claude Code / Codex → the ACP secrets form (API key + base URL), since
+ // these providers authenticate via env-var keys.
+ // * Gemini CLI → nothing: it authenticates through an interactive
+ // OAuth login, so there's no key to enter and we
+ // skip the slide entirely.
+ // ``getAcpProviderSecrets`` returns the field list (empty for Gemini), which
+ // is what distinguishes the ACP-with-secrets case from the skip case.
+ const isOpenHands = selectedAgentId === "openhands";
+ const acpSecretFields = getAcpProviderSecrets(selectedAgentId);
+ const showAcpSecretsStep = !isOpenHands && acpSecretFields.length > 0;
+ // Skip slide 2 only when there's nothing to show there (an ACP provider
+ // with no credentials to collect). Skipping keeps the rest of the flow
+ // intact in both directions (back from SayHello returns to CheckBackend,
+ // not a dead-end blank page).
+ const skipStep2 = !isOpenHands && !showAcpSecretsStep;
const goNext = React.useCallback(
() =>
setCurrentStep((step) => {
- const delta = skipLlmStep && step === 1 ? 2 : 1;
+ const delta = skipStep2 && step === 1 ? 2 : 1;
return Math.min(step + delta, TOTAL_STEPS - 1);
}),
- [skipLlmStep],
+ [skipStep2],
);
const goBack = React.useCallback(
() =>
setCurrentStep((step) => {
- const delta = skipLlmStep && step === 3 ? 2 : 1;
+ const delta = skipStep2 && step === 3 ? 2 : 1;
return Math.max(step - delta, 0);
}),
- [skipLlmStep],
+ [skipStep2],
);
// The progress bar should show the user's actual visited-step count,
- // not the underlying index. On the ACP path the LLM-setup slide is
- // skipped, so:
+ // not the underlying index. When slide 2 is skipped:
// * the bar renders 3 segments instead of 4, and
// * the SayHello slide (modal index 3) maps to logical step 2 so
// segment 2 doesn't pop "completed" on a slide the user never saw.
- const progressTotal = skipLlmStep ? TOTAL_STEPS - 1 : TOTAL_STEPS;
+ const progressTotal = skipStep2 ? TOTAL_STEPS - 1 : TOTAL_STEPS;
const progressStep =
- skipLlmStep && currentStep > 1 ? currentStep - 1 : currentStep;
+ skipStep2 && currentStep > 1 ? currentStep - 1 : currentStep;
return (
<ModalBackdrop
@@ -164,7 +176,15 @@ export function OnboardingModal({ onClose }: OnboardingModalProps) {
<CheckBackendStep onBack={goBack} onNext={goNext} />
</Slide>
<Slide index={2} currentStep={currentStep}>
- <SetupLlmStep onBack={goBack} onNext={goNext} />
+ {isOpenHands ? (
+ <SetupLlmStep onBack={goBack} onNext={goNext} />
+ ) : showAcpSecretsStep ? (
+ <SetupAcpSecretsStep
+ providerKey={selectedAgentId}
+ onBack={goBack}
+ onNext={goNext}
+ />
+ ) : null}
</Slide>
<Slide index={3} currentStep={currentStep}>
<SayHelloStep onBack={goBack} onLaunched={onClose} />
diff --git a/src/components/features/onboarding/steps/setup-acp-secrets-step.tsx b/src/components/features/onboarding/steps/setup-acp-secrets-step.tsx
new file mode 100644
index 0000000000..2b9aabc58a
--- /dev/null
+++ b/src/components/features/onboarding/steps/setup-acp-secrets-step.tsx
@@ -0,0 +1,173 @@
+import React from "react";
+import { useTranslation } from "react-i18next";
+import { useQueryClient } from "@tanstack/react-query";
+import { AxiosError } from "axios";
+import { BrandButton } from "#/components/features/settings/brand-button";
+import { SettingsInput } from "#/components/features/settings/settings-input";
+import { I18nKey } from "#/i18n/declaration";
+import { useCreateSecret } from "#/hooks/mutation/use-create-secret";
+import { useSearchSecrets } from "#/hooks/query/use-get-secrets";
+import {
+ getAcpProviderDisplayName,
+ getAcpProviderSecrets,
+} from "#/constants/acp-providers";
+import { type OnboardingAgentId } from "./choose-agent-step";
+import {
+ displayErrorToast,
+ displaySuccessToast,
+} from "#/utils/custom-toast-handlers";
+import { retrieveAxiosErrorMessage } from "#/utils/retrieve-axios-error-message";
+
+interface SetupAcpSecretsStepProps {
+ /** ACP provider whose credentials we're collecting (e.g. ``"claude-code"``).
+ * Typed as {@link OnboardingAgentId} — the same type the onboarding modal
+ * tracks — so a mistyped key is a compile error rather than a silently empty
+ * form. Providers without a credentials entry (``"openhands"``,
+ * ``"gemini-cli"``) simply yield no fields. */
+ providerKey: OnboardingAgentId;
+ onBack: () => void;
+ onNext: () => void;
+}
+
+/**
+ * Onboarding credentials step for ACP providers that authenticate via an
+ * env-var API key (Claude Code, Codex). The fields are derived from
+ * {@link getAcpProviderSecrets}; each one maps 1:1 to a **global secret**
+ * whose name equals the env var the agent-server exports into the provider
+ * subprocess. Saving here is therefore the same as adding the secret under
+ * Settings → Secrets — it shows up there afterwards.
+ *
+ * The step is intentionally skippable: a user may authenticate Claude Code via
+ * a subscription login, or already have the env var set on the backend, so we
+ * never block "Next" on a value. Empty fields are simply not written; a field
+ * whose secret already exists shows an "already saved" placeholder and is left
+ * untouched unless the user types a replacement.
+ */
+export function SetupAcpSecretsStep({
+ providerKey,
+ onBack,
+ onNext,
+}: SetupAcpSecretsStepProps) {
+ const { t } = useTranslation("openhands");
+ const queryClient = useQueryClient();
+ const { mutateAsync: createSecret } = useCreateSecret();
+ const { data: existingSecrets } = useSearchSecrets();
+
+ const fields = React.useMemo(
+ () => getAcpProviderSecrets(providerKey),
+ [providerKey],
+ );
+ const [values, setValues] = React.useState<Record<string, string>>({});
+ const [isSaving, setIsSaving] = React.useState(false);
+
+ const providerName = getAcpProviderDisplayName(providerKey) ?? providerKey;
+
+ const secretExists = React.useCallback(
+ (name: string) =>
+ (existingSecrets ?? []).some((secret) => secret.name === name),
+ [existingSecrets],
+ );
+
+ const handleNext = async () => {
+ // Only persist fields the user actually filled in — empty inputs are a
+ // deliberate skip, not a request to clear an existing secret.
+ const toSave = fields
+ .map((field) => ({ name: field.name, value: values[field.name]?.trim() }))
+ .filter((entry): entry is { name: string; value: string } =>
+ Boolean(entry.value),
+ );
+
+ if (toSave.length === 0) {
+ onNext();
+ return;
+ }
+
+ setIsSaving(true);
+ try {
+ // Sequential so a mid-list failure leaves the earlier secrets saved and
+ // surfaces a single, specific error rather than a race of toasts.
+ for (const { name, value } of toSave) {
+ await createSecret({ name, value });
+ }
+ await queryClient.invalidateQueries({ queryKey: ["secrets-search"] });
+ await queryClient.invalidateQueries({ queryKey: ["secrets"] });
+ displaySuccessToast(t(I18nKey.SETTINGS$SAVED));
+ onNext();
+ } catch (error) {
+ const message = retrieveAxiosErrorMessage(error as AxiosError);
+ displayErrorToast(message || t(I18nKey.ERROR$GENERIC));
+ } finally {
+ setIsSaving(false);
+ }
+ };
+
+ return (
+ <div
+ data-testid="onboarding-step-setup-acp-secrets"
+ className="flex flex-col gap-6"
+ >
+ <header className="flex flex-col gap-2">
+ <h2 className="text-2xl font-medium text-white">
+ {t(I18nKey.ONBOARDING$ACP_SECRETS_TITLE)}
+ </h2>
+ <p className="text-sm text-[var(--oh-muted)]">
+ {t(I18nKey.ONBOARDING$ACP_SECRETS_SUBTITLE, {
+ provider: providerName,
+ })}
+ </p>
+ </header>
+
+ <div className="flex flex-col gap-5">
+ {fields.map((field) => {
+ const alreadySet = secretExists(field.name);
+ return (
+ <div key={field.name} className="flex flex-col gap-1.5">
+ <SettingsInput
+ testId={`onboarding-acp-secret-${field.name}`}
+ name={field.name}
+ // The env-var name is the canonical label here; rendering it
+ // monospace makes clear it's a literal key, not prose.
+ label={field.name}
+ labelClassName="font-mono"
+ type={field.secret ? "password" : "text"}
+ value={values[field.name] ?? ""}
+ onChange={(value) =>
+ setValues((prev) => ({ ...prev, [field.name]: value }))
+ }
+ // Every field is optional — the whole step is skippable.
+ showOptionalTag
+ placeholder={
+ alreadySet ? t(I18nKey.ONBOARDING$ACP_SECRET_ALREADY_SET) : ""
+ }
+ />
+ <span className="text-xs text-[var(--oh-muted)]">
+ {t(field.hint_key)}
+ </span>
+ </div>
+ );
+ })}
+ </div>
+
+ <div className="sticky bottom-0 flex items-center justify-between gap-2 bg-base-secondary pt-4 pb-7">
+ <BrandButton
+ testId="onboarding-acp-secrets-back"
+ type="button"
+ variant="secondary"
+ onClick={onBack}
+ isDisabled={isSaving}
+ >
+ {t(I18nKey.ONBOARDING$BACK)}
+ </BrandButton>
+ <BrandButton
+ testId="onboarding-acp-secrets-next"
+ type="button"
+ variant="primary"
+ isDisabled={isSaving}
+ onClick={handleNext}
+ >
+ {isSaving ? t(I18nKey.SETTINGS$SAVING) : t(I18nKey.ONBOARDING$NEXT)}
+ </BrandButton>
+ </div>
+ </div>
+ );
+}
diff --git a/src/constants/acp-providers.ts b/src/constants/acp-providers.ts
index 03f9267d6c..cc21df5837 100644
--- a/src/constants/acp-providers.ts
+++ b/src/constants/acp-providers.ts
@@ -171,6 +171,71 @@ export const ACP_PROVIDERS: ACPProviderConfig[] = Object.entries(
export const ACP_CUSTOM_PRESET_KEY = "custom";
+/**
+ * A credential an ACP provider authenticates with, surfaced during onboarding
+ * so the user can populate it without leaving the flow. The {@link name} is
+ * both the global-secret name and the environment variable the agent-server
+ * exports into the ACP subprocess — keeping them identical is what makes a
+ * saved secret actually reach the provider CLI.
+ */
+export interface ACPProviderSecretField {
+ /** Secret name and env var (e.g. ``"ANTHROPIC_API_KEY"``). Must satisfy the
+ * secret-name pattern ``^[a-zA-Z][a-zA-Z0-9_]{0,63}$``. */
+ name: string;
+ /** Render as a masked password input (API keys) rather than a plain-text
+ * input (base URLs). Every field is optional regardless — the whole step is
+ * skippable — so this only controls masking, not whether the field gates. */
+ secret?: boolean;
+ /** i18n key for the one-line helper text under the field. */
+ hint_key: I18nKey;
+}
+
+// Credentials Canvas prompts for during onboarding, keyed by ACP registry key.
+// Only providers that authenticate through an env-var API key appear here:
+// Claude Code (Anthropic) and Codex (OpenAI). Gemini CLI authenticates via an
+// interactive OAuth login rather than a static key, so it has no entry and its
+// onboarding credentials step is skipped. Every field is optional (the step is
+// skippable): the API keys render masked, the base-URL entries are plain-text
+// overrides for proxies/gateways. A provider with no entry simply shows no
+// credentials step.
+const ACP_PROVIDER_SECRETS: Record<string, ACPProviderSecretField[]> = {
+ "claude-code": [
+ {
+ name: "ANTHROPIC_API_KEY",
+ secret: true,
+ hint_key: I18nKey.ONBOARDING$ACP_SECRET_API_KEY_HINT,
+ },
+ {
+ name: "ANTHROPIC_BASE_URL",
+ hint_key: I18nKey.ONBOARDING$ACP_SECRET_BASE_URL_HINT,
+ },
+ ],
+ codex: [
+ {
+ name: "OPENAI_API_KEY",
+ secret: true,
+ hint_key: I18nKey.ONBOARDING$ACP_SECRET_API_KEY_HINT,
+ },
+ {
+ name: "OPENAI_BASE_URL",
+ hint_key: I18nKey.ONBOARDING$ACP_SECRET_BASE_URL_HINT,
+ },
+ ],
+};
+
+/**
+ * List the credentials Canvas should prompt for when onboarding the given ACP
+ * provider. Returns ``[]`` for OpenHands, the ``"custom"`` preset, providers
+ * that don't use a static API key (Gemini CLI), and any unknown key — callers
+ * treat an empty list as "no credentials step for this provider".
+ */
+export function getAcpProviderSecrets(
+ key: string | null | undefined,
+): ACPProviderSecretField[] {
+ if (!key) return [];
+ return ACP_PROVIDER_SECRETS[key] ?? [];
+}
+
/**
* Look up a built-in ACP provider config by its registry key.
*
diff --git a/src/i18n/translation.json b/src/i18n/translation.json
index 53ad6c2ac6..3a60b4152f 100644
--- a/src/i18n/translation.json
+++ b/src/i18n/translation.json
@@ -27539,6 +27539,91 @@
"tr": "Sohbet başlatılıyor…",
"uk": "Розпочинаємо розмову…"
},
+ "ONBOARDING$ACP_SECRETS_TITLE": {
+ "en": "Add your API keys",
+ "ja": "API キーを追加",
+ "zh-CN": "添加你的 API 密钥",
+ "zh-TW": "新增你的 API 金鑰",
+ "ko-KR": "API 키 추가",
+ "no": "Legg til API-nøklene dine",
+ "ar": "أضف مفاتيح API الخاصة بك",
+ "de": "API-Schlüssel hinzufügen",
+ "fr": "Ajoutez vos clés API",
+ "it": "Aggiungi le tue chiavi API",
+ "pt": "Adicione suas chaves de API",
+ "es": "Añade tus claves de API",
+ "ca": "Afegeix les teves claus API",
+ "tr": "API anahtarlarınızı ekleyin",
+ "uk": "Додайте свої ключі API"
+ },
+ "ONBOARDING$ACP_SECRETS_SUBTITLE": {
+ "en": "Store the credentials {{provider}} needs to run. They're saved as secrets you can manage anytime under Settings → Secrets.",
+ "ja": "{{provider}} の実行に必要な認証情報を保存します。これらはシークレットとして保存され、設定 → シークレットでいつでも管理できます。",
+ "zh-CN": "保存 {{provider}} 运行所需的凭据。它们将作为密钥保存,你可以随时在“设置 → 密钥”中管理。",
+ "zh-TW": "儲存 {{provider}} 執行所需的憑證。它們會以密鑰形式保存,你可以隨時在「設定 → 密鑰」中管理。",
+ "ko-KR": "{{provider}} 실행에 필요한 자격 증명을 저장합니다. 비밀로 저장되며 설정 → 비밀에서 언제든지 관리할 수 있습니다.",
+ "no": "Lagre legitimasjonen {{provider}} trenger for å kjøre. De lagres som hemmeligheter du kan administrere når som helst under Innstillinger → Hemmeligheter.",
+ "ar": "احفظ بيانات الاعتماد التي يحتاجها {{provider}} للعمل. تُحفظ كأسرار يمكنك إدارتها في أي وقت من الإعدادات → الأسرار.",
+ "de": "Speichere die Anmeldedaten, die {{provider}} zum Ausführen benötigt. Sie werden als Secrets gespeichert und lassen sich jederzeit unter Einstellungen → Secrets verwalten.",
+ "fr": "Enregistrez les identifiants dont {{provider}} a besoin pour fonctionner. Ils sont enregistrés comme secrets que vous pouvez gérer à tout moment dans Paramètres → Secrets.",
+ "it": "Salva le credenziali necessarie a {{provider}} per funzionare. Vengono salvate come segreti che puoi gestire in qualsiasi momento in Impostazioni → Segreti.",
+ "pt": "Guarde as credenciais que o {{provider}} precisa para funcionar. Elas são salvas como segredos que você pode gerenciar a qualquer momento em Configurações → Segredos.",
+ "es": "Guarda las credenciales que {{provider}} necesita para funcionar. Se guardan como secretos que puedes gestionar en cualquier momento en Configuración → Secretos.",
+ "ca": "Desa les credencials que {{provider}} necessita per funcionar. Es desen com a secrets que pots gestionar en qualsevol moment a Configuració → Secrets.",
+ "tr": "{{provider}} öğesinin çalışması için gereken kimlik bilgilerini saklayın. Bunlar, Ayarlar → Gizli Bilgiler altında istediğiniz zaman yönetebileceğiniz gizli bilgiler olarak kaydedilir.",
+ "uk": "Збережіть облікові дані, потрібні для роботи {{provider}}. Вони зберігаються як секрети, якими можна керувати будь-коли в розділі Налаштування → Секрети."
+ },
+ "ONBOARDING$ACP_SECRET_API_KEY_HINT": {
+ "en": "Used to authenticate the agent. Leave blank to use credentials already set on your backend.",
+ "ja": "エージェントの認証に使用します。バックエンドに既に設定されている認証情報を使う場合は空欄のままにしてください。",
+ "zh-CN": "用于对智能体进行身份验证。如果要使用后端已配置的凭据,请留空。",
+ "zh-TW": "用於驗證代理。若要使用後端已設定的憑證,請留空。",
+ "ko-KR": "에이전트 인증에 사용됩니다. 백엔드에 이미 설정된 자격 증명을 사용하려면 비워 두세요.",
+ "no": "Brukes til å autentisere agenten. La stå tom for å bruke legitimasjon som allerede er satt opp på backend-en.",
+ "ar": "يُستخدم لمصادقة الوكيل. اتركه فارغًا لاستخدام بيانات الاعتماد المُعدّة مسبقًا على الخادم الخلفي.",
+ "de": "Wird zur Authentifizierung des Agenten verwendet. Leer lassen, um bereits im Backend hinterlegte Anmeldedaten zu verwenden.",
+ "fr": "Sert à authentifier l'agent. Laissez vide pour utiliser les identifiants déjà configurés sur votre backend.",
+ "it": "Usata per autenticare l'agente. Lascia vuoto per usare le credenziali già configurate sul tuo backend.",
+ "pt": "Usada para autenticar o agente. Deixe em branco para usar as credenciais já configuradas no seu backend.",
+ "es": "Se usa para autenticar el agente. Déjalo en blanco para usar las credenciales ya configuradas en tu backend.",
+ "ca": "S'utilitza per autenticar l'agent. Deixa-ho en blanc per fer servir les credencials ja configurades al teu backend.",
+ "tr": "Aracıyı doğrulamak için kullanılır. Arka uçta zaten ayarlanmış kimlik bilgilerini kullanmak için boş bırakın.",
+ "uk": "Використовується для автентифікації агента. Залиште порожнім, щоб використати облікові дані, уже налаштовані на вашому бекенді."
+ },
+ "ONBOARDING$ACP_SECRET_BASE_URL_HINT": {
+ "en": "Optional. Point the agent at a custom API endpoint, such as a proxy or gateway.",
+ "ja": "任意。プロキシやゲートウェイなど、カスタム API エンドポイントをエージェントに指定します。",
+ "zh-CN": "可选。让智能体指向自定义 API 端点,例如代理或网关。",
+ "zh-TW": "選填。讓代理指向自訂 API 端點,例如代理伺服器或閘道。",
+ "ko-KR": "선택 사항. 프록시나 게이트웨이 등 사용자 지정 API 엔드포인트로 에이전트를 연결합니다.",
+ "no": "Valgfritt. Pek agenten mot et egendefinert API-endepunkt, for eksempel en proxy eller gateway.",
+ "ar": "اختياري. وجّه الوكيل إلى نقطة نهاية API مخصصة، مثل وكيل أو بوابة.",
+ "de": "Optional. Leite den Agenten an einen benutzerdefinierten API-Endpunkt weiter, etwa einen Proxy oder ein Gateway.",
+ "fr": "Facultatif. Dirigez l'agent vers un point de terminaison d'API personnalisé, tel qu'un proxy ou une passerelle.",
+ "it": "Facoltativo. Indirizza l'agente verso un endpoint API personalizzato, come un proxy o un gateway.",
+ "pt": "Opcional. Aponte o agente para um endpoint de API personalizado, como um proxy ou gateway.",
+ "es": "Opcional. Dirige el agente a un endpoint de API personalizado, como un proxy o una pasarela.",
+ "ca": "Opcional. Dirigeix l'agent a un punt final d'API personalitzat, com ara un proxy o una passarel·la.",
+ "tr": "İsteğe bağlı. Aracıyı proxy veya ağ geçidi gibi özel bir API uç noktasına yönlendirin.",
+ "uk": "Необов'язково. Спрямуйте агента на власну кінцеву точку API, наприклад проксі або шлюз."
+ },
+ "ONBOARDING$ACP_SECRET_ALREADY_SET": {
+ "en": "Already saved — leave blank to keep",
+ "ja": "保存済み — そのままにする場合は空欄",
+ "zh-CN": "已保存 — 留空以保留",
+ "zh-TW": "已儲存 — 留空以保留",
+ "ko-KR": "이미 저장됨 — 유지하려면 비워 두세요",
+ "no": "Allerede lagret – la stå tom for å beholde",
+ "ar": "محفوظ بالفعل — اتركه فارغًا للإبقاء عليه",
+ "de": "Bereits gespeichert – zum Beibehalten leer lassen",
+ "fr": "Déjà enregistré — laissez vide pour conserver",
+ "it": "Già salvato — lascia vuoto per mantenerlo",
+ "pt": "Já salvo — deixe em branco para manter",
+ "es": "Ya guardado: déjalo en blanco para mantenerlo",
+ "ca": "Ja desat — deixa-ho en blanc per mantenir-ho",
+ "tr": "Zaten kaydedildi — korumak için boş bırakın",
+ "uk": "Уже збережено — залиште порожнім, щоб зберегти"
+ },
"ERROR$FAILED_TO_LOAD_PROFILE_TRY_AGAIN": {
"en": "Failed to load existing profile. Please try again.",
"ja": "既存のプロファイルの読み込みに失敗しました。もう一度お試しください。",