Skip to content

🙌 OpenHands: AI-Driven Development

Add multi-step onboarding modal (#257)

Robert Brennan8482aeda2690
diff --git a/AGENTS.md b/AGENTS.md
index 7de09980a8..e573e4ab91 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -178,3 +178,5 @@
- Backend dropdown connectivity indicator: `useBackendsHealth` (`src/hooks/query/use-backends-health.ts`) polls each registered backend every 10s. Local agent-server backends are probed via `ServerClient.getServerInfo()` (`/server_info`); cloud SaaS backends are probed via `getCurrentCloudApiKey()` (`/api/keys/current` through the bundled `/api/cloud-proxy`). Verdicts are surfaced as a colored dot rendered through `DropdownOption.prefix` (added to `src/ui/dropdown/types.ts`); the trigger reads its prefix from the live `options` array (not downshift's frozen `selectedItem`) so the indicator updates without remounting. The same dot is also rendered in each row of `ManageBackendsModal`. Tests live in `__tests__/hooks/query/use-backends-health.test.tsx`, the `connection indicator` block of `__tests__/components/backends/backend-selector.test.tsx`, and `__tests__/components/backends/manage-backends-modal.test.tsx`.
- Manage Backends modal: `src/components/features/backends/manage-backends-modal.tsx` lets users edit (host/name/api-key/kind) and remove existing backends, plus add new ones inline via a "+ Add Backend" footer button that opens a `BackendFormModal`. Both the dropdown footer's "Add backend" and the manage modal's "+ Add Backend" reuse `BackendFormModal` (see `backend-form-modal.tsx`), with `mode="add"` or `mode="edit"`; `AddBackendModal` is now a thin compatibility wrapper for `BackendFormModal mode="add"`. The modal is also auto-rendered (with a no-op `onClose`) by `src/root.tsx` when the active backend is unreachable, replacing the old full-screen `MissingAgentServerNotice` onboarding screen.
+
+- Onboarding modal: `src/components/features/onboarding/onboarding-modal.tsx` is a 4-step welcome flow rendered by `<OnboardingHost />` (mounted on the home route) and gated by the `openhands-onboarded` localStorage flag (`use-onboarding-completion.ts`). The four steps live under `steps/`: choose-agent (Step 0 – OpenHands selectable, Claude Code & Codex disabled with a "coming soon" note), check-backend (embeds the new `BackendForm` extracted from `backend-form-modal.tsx` plus a colored connection banner driven by `useBackendsHealth`), setup-llm (renders `<LlmSettingsScreen onSaveSuccess={onNext} />` so the existing settings UI keeps owning validation), and say-hello (text input pre-filled from `ONBOARDING$HELLO_DEFAULT_MESSAGE`, launches a no-workspace conversation via `useCreateConversation` and closes the modal). Animation: all four panels are mounted as siblings inside a horizontal rail; advancing/retreating just sets `currentStep`, which translates the rail by `-(step * 100)%` for the slide effect. Progress is rendered by `OnboardingProgressBar` with `data-state` per segment (`completed` | `current` | `upcoming`). When extending, refactor `BackendFormModal` carefully — the inner `BackendForm` is the public surface used both by the modal and by `CheckBackendStep`; the modal version still owns dirty/save tracking so it keeps "Save"/"Cancel" footer behavior.
diff --git a/__tests__/components/onboarding/choose-agent-step.test.tsx b/__tests__/components/onboarding/choose-agent-step.test.tsx
new file mode 100644
index 0000000000..99dff24189
--- /dev/null
+++ b/__tests__/components/onboarding/choose-agent-step.test.tsx
@@ -0,0 +1,73 @@
+import React from "react";
+import { render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { describe, expect, it, vi } from "vitest";
+import {
+ ChooseAgentStep,
+ type OnboardingAgentId,
+} from "#/components/features/onboarding/steps/choose-agent-step";
+
+function renderStep(initial: OnboardingAgentId = "openhands") {
+ const onSelect = vi.fn();
+ const onNext = vi.fn();
+ render(
+ <ChooseAgentStep
+ selectedAgentId={initial}
+ onSelect={onSelect}
+ onNext={onNext}
+ />,
+ );
+ return { onSelect, onNext };
+}
+
+describe("ChooseAgentStep", () => {
+ it("renders the three agent options with OpenHands marked selected", () => {
+ 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");
+
+ expect(openhands).toHaveAttribute("aria-checked", "true");
+ expect(openhands).not.toBeDisabled();
+
+ // Claude Code and Codex are visible but disabled / coming-soon.
+ expect(claude).toBeDisabled();
+ expect(claude).toHaveAttribute("aria-disabled", "true");
+ expect(codex).toBeDisabled();
+ expect(codex).toHaveAttribute("aria-disabled", "true");
+
+ // The "coming soon" note is rendered.
+ expect(
+ screen.getByTestId("onboarding-agent-coming-soon"),
+ ).toBeInTheDocument();
+ });
+
+ it("ignores clicks on the disabled agent options", async () => {
+ const { onSelect } = renderStep();
+ const user = userEvent.setup();
+
+ await user.click(screen.getByTestId("onboarding-agent-option-claude-code"));
+ await user.click(screen.getByTestId("onboarding-agent-option-codex"));
+
+ expect(onSelect).not.toHaveBeenCalled();
+ });
+
+ it("invokes onSelect when the OpenHands option is clicked", async () => {
+ const { onSelect } = renderStep();
+ const user = userEvent.setup();
+
+ await user.click(screen.getByTestId("onboarding-agent-option-openhands"));
+
+ expect(onSelect).toHaveBeenCalledWith("openhands");
+ });
+
+ it("invokes onNext when the Next button is clicked", async () => {
+ const { onNext } = renderStep();
+ const user = userEvent.setup();
+
+ await user.click(screen.getByTestId("onboarding-agent-next"));
+
+ expect(onNext).toHaveBeenCalledTimes(1);
+ });
+});
diff --git a/__tests__/components/onboarding/onboarding-modal.test.tsx b/__tests__/components/onboarding/onboarding-modal.test.tsx
new file mode 100644
index 0000000000..d2aac10f74
--- /dev/null
+++ b/__tests__/components/onboarding/onboarding-modal.test.tsx
@@ -0,0 +1,210 @@
+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 { OnboardingModal } from "#/components/features/onboarding/onboarding-modal";
+import { NavigationProvider } from "#/context/navigation-context";
+
+// Both the backend status badge in the embedded edit form and the
+// step-1 health probe ride on `useBackendsHealth`, which itself
+// resolves through these two clients.
+vi.mock("#/api/typescript-client", () => ({
+ createServerClient: vi.fn(() => ({
+ getServerInfo: vi.fn().mockResolvedValue({ version: "1.18.0" }),
+ })),
+}));
+
+vi.mock("#/api/cloud/organization-service.api", () => ({
+ getCurrentCloudApiKey: vi.fn().mockResolvedValue({
+ orgId: null,
+ isLegacyKey: true,
+ }),
+}));
+
+// The LLM step renders the full `LlmSettingsScreen`, which transitively
+// pulls in agent-server config + schema queries we don't need to
+// exercise here. Stub it to a marker so we can still verify the LLM
+// step is mounted.
+vi.mock("#/routes/llm-settings", () => ({
+ LlmSettingsScreen: () => (
+ <div data-testid="llm-settings-screen-stub">llm settings</div>
+ ),
+}));
+
+vi.mock("#/hooks/use-is-creating-conversation", () => ({
+ useIsCreatingConversation: () => false,
+}));
+
+vi.mock("#/hooks/mutation/use-create-conversation", () => ({
+ useCreateConversation: () => ({
+ mutate: vi.fn(),
+ isPending: false,
+ isSuccess: false,
+ }),
+}));
+
+function renderModal(onClose = vi.fn()) {
+ const queryClient = new QueryClient({
+ defaultOptions: { queries: { retry: false } },
+ });
+ const navigationValue = {
+ currentPath: "/",
+ conversationId: null,
+ isNavigating: false,
+ navigate: vi.fn(),
+ };
+ return render(
+ <QueryClientProvider client={queryClient}>
+ <ActiveBackendProvider>
+ <NavigationProvider value={navigationValue}>
+ <OnboardingModal onClose={onClose} />
+ </NavigationProvider>
+ </ActiveBackendProvider>
+ </QueryClientProvider>,
+ );
+}
+
+beforeEach(() => {
+ window.localStorage.clear();
+ __resetActiveStoreForTests();
+});
+afterEach(() => {
+ window.localStorage.clear();
+ __resetActiveStoreForTests();
+});
+
+describe("OnboardingModal", () => {
+ it("starts on the Choose Agent step with each slide offset by its index", () => {
+ renderModal();
+
+ expect(screen.getByTestId("onboarding-modal")).toHaveAttribute(
+ "data-current-step",
+ "0",
+ );
+ expect(
+ screen.getByTestId("onboarding-step-choose-agent"),
+ ).toBeInTheDocument();
+
+ // Active slide sits at offset 0; later slides are translated 100%
+ // per index away to the right and absolute-positioned so they
+ // don't bleed into the modal box.
+ expect(screen.getByTestId("onboarding-slide-0")).toHaveAttribute(
+ "data-active",
+ "true",
+ );
+ expect(
+ screen.getByTestId("onboarding-slide-0").style.transform,
+ ).toBe("translateX(0%)");
+ expect(
+ screen.getByTestId("onboarding-slide-1").style.transform,
+ ).toBe("translateX(100%)");
+ expect(
+ screen.getByTestId("onboarding-slide-2").style.transform,
+ ).toBe("translateX(200%)");
+ expect(
+ screen.getByTestId("onboarding-slide-3").style.transform,
+ ).toBe("translateX(300%)");
+
+ // Progress bar reflects step 1 of 4.
+ expect(
+ screen.getByTestId("onboarding-progress-step-0"),
+ ).toHaveAttribute("data-state", "current");
+ expect(
+ screen.getByTestId("onboarding-progress-step-1"),
+ ).toHaveAttribute("data-state", "upcoming");
+ });
+
+ it("advances each step via the per-step Next button and reframes slide offsets", async () => {
+ renderModal();
+ const user = userEvent.setup();
+
+ // Step 0 → 1
+ await user.click(screen.getByTestId("onboarding-agent-next"));
+ await waitFor(() =>
+ expect(screen.getByTestId("onboarding-modal")).toHaveAttribute(
+ "data-current-step",
+ "1",
+ ),
+ );
+ expect(screen.getByTestId("onboarding-slide-1")).toHaveAttribute(
+ "data-active",
+ "true",
+ );
+ expect(
+ screen.getByTestId("onboarding-slide-0").style.transform,
+ ).toBe("translateX(-100%)");
+ expect(
+ screen.getByTestId("onboarding-slide-1").style.transform,
+ ).toBe("translateX(0%)");
+ expect(
+ screen.getByTestId("onboarding-slide-2").style.transform,
+ ).toBe("translateX(100%)");
+
+ // Once the backend health probe resolves, step 1's Next is enabled.
+ await waitFor(() =>
+ expect(
+ screen.getByTestId("onboarding-backend-next"),
+ ).not.toBeDisabled(),
+ );
+ await user.click(screen.getByTestId("onboarding-backend-next"));
+ expect(screen.getByTestId("onboarding-modal")).toHaveAttribute(
+ "data-current-step",
+ "2",
+ );
+ expect(screen.getByTestId("onboarding-slide-2")).toHaveAttribute(
+ "data-active",
+ "true",
+ );
+
+ // Step 2 → 3
+ await user.click(screen.getByTestId("onboarding-llm-next"));
+ expect(screen.getByTestId("onboarding-modal")).toHaveAttribute(
+ "data-current-step",
+ "3",
+ );
+ expect(screen.getByTestId("onboarding-slide-3")).toHaveAttribute(
+ "data-active",
+ "true",
+ );
+ expect(
+ screen.getByTestId("onboarding-slide-3").style.transform,
+ ).toBe("translateX(0%)");
+ });
+
+ it("Skip immediately closes the modal", async () => {
+ const onClose = vi.fn();
+ renderModal(onClose);
+
+ const user = userEvent.setup();
+ await user.click(screen.getByTestId("onboarding-skip"));
+
+ expect(onClose).toHaveBeenCalledTimes(1);
+ });
+
+ it("pre-fills the say-hello input with the default greeting on step 3", async () => {
+ renderModal();
+ const user = userEvent.setup();
+
+ await user.click(screen.getByTestId("onboarding-agent-next"));
+ await waitFor(() =>
+ expect(
+ screen.getByTestId("onboarding-backend-next"),
+ ).not.toBeDisabled(),
+ );
+ await user.click(screen.getByTestId("onboarding-backend-next"));
+ await user.click(screen.getByTestId("onboarding-llm-next"));
+
+ const helloInput = screen.getByTestId(
+ "onboarding-hello-input",
+ ) as HTMLInputElement;
+ // Translation is mocked to return the key; the default-message
+ // hook still pre-fills with whatever t() returns, which here is
+ // the I18nKey itself. The contract under test is that the input
+ // is non-empty and matches the resolved default message.
+ expect(helloInput.value).toBe("ONBOARDING$HELLO_DEFAULT_MESSAGE");
+ });
+});
diff --git a/__tests__/components/onboarding/onboarding-progress-bar.test.tsx b/__tests__/components/onboarding/onboarding-progress-bar.test.tsx
new file mode 100644
index 0000000000..adf19a181f
--- /dev/null
+++ b/__tests__/components/onboarding/onboarding-progress-bar.test.tsx
@@ -0,0 +1,42 @@
+import { render, screen } from "@testing-library/react";
+import { describe, expect, it } from "vitest";
+import { OnboardingProgressBar } from "#/components/features/onboarding/onboarding-progress-bar";
+
+describe("OnboardingProgressBar", () => {
+ it("renders one segment per step and marks the current segment", () => {
+ render(<OnboardingProgressBar currentStep={1} totalSteps={4} />);
+
+ const bar = screen.getByTestId("onboarding-progress-bar");
+ expect(bar).toHaveAttribute("aria-valuenow", "2");
+ expect(bar).toHaveAttribute("aria-valuemin", "1");
+ expect(bar).toHaveAttribute("aria-valuemax", "4");
+
+ // Segment states match the current step.
+ expect(
+ screen.getByTestId("onboarding-progress-step-0"),
+ ).toHaveAttribute("data-state", "completed");
+ expect(
+ screen.getByTestId("onboarding-progress-step-1"),
+ ).toHaveAttribute("data-state", "current");
+ expect(
+ screen.getByTestId("onboarding-progress-step-2"),
+ ).toHaveAttribute("data-state", "upcoming");
+ expect(
+ screen.getByTestId("onboarding-progress-step-3"),
+ ).toHaveAttribute("data-state", "upcoming");
+ });
+
+ it("treats the first step as current with no completed segments", () => {
+ render(<OnboardingProgressBar currentStep={0} totalSteps={3} />);
+
+ expect(
+ screen.getByTestId("onboarding-progress-step-0"),
+ ).toHaveAttribute("data-state", "current");
+ expect(
+ screen.getByTestId("onboarding-progress-step-1"),
+ ).toHaveAttribute("data-state", "upcoming");
+ expect(
+ screen.getByTestId("onboarding-progress-step-2"),
+ ).toHaveAttribute("data-state", "upcoming");
+ });
+});
diff --git a/__tests__/components/onboarding/use-onboarding-completion.test.tsx b/__tests__/components/onboarding/use-onboarding-completion.test.tsx
new file mode 100644
index 0000000000..26184f80ea
--- /dev/null
+++ b/__tests__/components/onboarding/use-onboarding-completion.test.tsx
@@ -0,0 +1,58 @@
+import React from "react";
+import { act, renderHook } from "@testing-library/react";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import {
+ ONBOARDING_COMPLETED_STORAGE_KEY,
+ useOnboardingCompletion,
+} from "#/components/features/onboarding/use-onboarding-completion";
+
+beforeEach(() => {
+ window.localStorage.clear();
+});
+afterEach(() => {
+ window.localStorage.clear();
+});
+
+describe("useOnboardingCompletion", () => {
+ it("starts incomplete when the localStorage flag is missing", () => {
+ const { result } = renderHook(() => useOnboardingCompletion());
+ expect(result.current.isCompleted).toBe(false);
+ });
+
+ it("starts complete when the localStorage flag is set", () => {
+ window.localStorage.setItem(ONBOARDING_COMPLETED_STORAGE_KEY, "1");
+ const { result } = renderHook(() => useOnboardingCompletion());
+ expect(result.current.isCompleted).toBe(true);
+ });
+
+ it("persists completion to localStorage and flips the flag", () => {
+ const { result } = renderHook(() => useOnboardingCompletion());
+ expect(result.current.isCompleted).toBe(false);
+
+ act(() => {
+ result.current.markCompleted();
+ });
+
+ expect(result.current.isCompleted).toBe(true);
+ expect(
+ window.localStorage.getItem(ONBOARDING_COMPLETED_STORAGE_KEY),
+ ).not.toBeNull();
+ });
+
+ it("syncs across tabs via the storage event", () => {
+ const { result } = renderHook(() => useOnboardingCompletion());
+ expect(result.current.isCompleted).toBe(false);
+
+ act(() => {
+ window.localStorage.setItem(ONBOARDING_COMPLETED_STORAGE_KEY, "1");
+ window.dispatchEvent(
+ new StorageEvent("storage", {
+ key: ONBOARDING_COMPLETED_STORAGE_KEY,
+ newValue: "1",
+ }),
+ );
+ });
+
+ expect(result.current.isCompleted).toBe(true);
+ });
+});
diff --git a/src/components/features/backends/backend-form-modal.tsx b/src/components/features/backends/backend-form-modal.tsx
index 0fb5411930..7057d4b466 100644
--- a/src/components/features/backends/backend-form-modal.tsx
+++ b/src/components/features/backends/backend-form-modal.tsx
@@ -1,11 +1,15 @@
import React from "react";
+import { useQuery } from "@tanstack/react-query";
import { useTranslation } from "react-i18next";
import { ModalBackdrop } from "#/components/shared/modals/modal-backdrop";
import { BrandButton } from "#/components/features/settings/brand-button";
import { SettingsInput } from "#/components/features/settings/settings-input";
import { useActiveBackendContext } from "#/contexts/active-backend-context";
+import { useBackendsHealth } from "#/hooks/query/use-backends-health";
+import { createServerClient } from "#/api/typescript-client";
import { I18nKey } from "#/i18n/declaration";
import type { Backend, BackendKind } from "#/api/backend-registry/types";
+import { BackendStatusDot } from "./backend-status-dot";
export type BackendFormMode = "add" | "edit";
@@ -32,15 +36,116 @@ function normalizeHost(host: string): string {
}
/**
- * Single form used for both adding a new backend and editing an
- * existing one. The shape of `Backend` is identical in both cases — the
- * only difference is whether we call `addBackend` or `updateBackend`.
+ * Live status row for the edit form: shows a connection dot, a
+ * "Local"/"Cloud" label, and the agent server's reported version when
+ * available. Replaces the legacy local/cloud radio fieldset (kind is
+ * now inferred from the host).
*/
-export function BackendFormModal({
+function BackendStatusBadge({
+ backend,
+ testIdRoot,
+}: {
+ backend: Backend;
+ testIdRoot: string;
+}) {
+ const { t } = useTranslation("openhands");
+ const healthByBackendId = useBackendsHealth([backend]);
+ const isConnected = healthByBackendId[backend.id]?.isConnected ?? null;
+
+ const { data: version } = useQuery({
+ queryKey: ["backend-version", backend.host, backend.apiKey],
+ queryFn: async () => {
+ const info = await createServerClient({
+ host: backend.host,
+ sessionApiKey: backend.apiKey || null,
+ timeout: 5000,
+ }).getServerInfo();
+ return info.version ?? null;
+ },
+ retry: false,
+ staleTime: 60_000,
+ enabled: backend.kind === "local",
+ });
+
+ let statusLabel: string;
+ if (isConnected === true) {
+ statusLabel = t(I18nKey.ONBOARDING$BACKEND_STATUS_CONNECTED);
+ } else if (isConnected === false) {
+ statusLabel = t(I18nKey.ONBOARDING$BACKEND_STATUS_DISCONNECTED);
+ } else {
+ statusLabel = t(I18nKey.ONBOARDING$BACKEND_STATUS_CHECKING);
+ }
+
+ const kindLabel =
+ backend.kind === "cloud"
+ ? t(I18nKey.BACKEND$KIND_CLOUD)
+ : t(I18nKey.BACKEND$KIND_LOCAL);
+
+ return (
+ <div
+ data-testid={`${testIdRoot}-status`}
+ className="flex items-center gap-3 text-sm"
+ >
+ <BackendStatusDot isConnected={isConnected} />
+ <span className="text-white" data-testid={`${testIdRoot}-status-label`}>
+ {statusLabel}
+ </span>
+ <span className="text-tertiary-alt">·</span>
+ <span className="text-gray-300">{kindLabel}</span>
+ {version ? (
+ <span
+ className="text-xs text-gray-400"
+ data-testid={`${testIdRoot}-version`}
+ >
+ {t(I18nKey.BACKEND$VERSION_LABEL, { version })}
+ </span>
+ ) : null}
+ </div>
+ );
+}
+
+export interface BackendFormProps {
+ mode: BackendFormMode;
+ /** Required when `mode === "edit"`. */
+ backend?: Backend;
+ /**
+ * Called after the form is submitted and the backend has been
+ * persisted. Use this to dismiss a containing modal, advance an
+ * onboarding step, etc.
+ */
+ onSubmitted: () => void;
+ /**
+ * Optional render slot rendered in place of the default
+ * Save / Cancel button row, so callers (e.g. the onboarding flow)
+ * can re-skin the action area while still owning submission via the
+ * standard `<form onSubmit>` flow. Receives the form's submit-ready
+ * state.
+ */
+ renderActions?: (state: {
+ canSubmit: boolean;
+ testIdRoot: string;
+ }) => React.ReactNode;
+ /** Used to disambiguate test ids across the same screen. */
+ testIdRoot?: string;
+}
+
+/**
+ * Reusable form body for adding / editing a backend. Renders the
+ * common name / host / API-key inputs plus the kind selector
+ * (radio buttons in `add` mode, status badge in `edit` mode).
+ *
+ * Rendered as a `<form>`, so consumers should put any extra controls
+ * either inside `renderActions` or as siblings inside a wrapping
+ * element — but submission flows through the standard form submit so
+ * Enter-to-submit still works.
+ */
+export function BackendForm({
mode,
backend,
- onClose,
-}: BackendFormModalProps) {
+ onSubmitted,
+ renderActions,
+ testIdRoot: explicitTestIdRoot,
+}: BackendFormProps) {
const { t } = useTranslation("openhands");
const { addBackend, updateBackend } = useActiveBackendContext();
@@ -61,12 +166,15 @@ export function BackendFormModal({
}
}, [host, touchedKind]);
+ const testIdRoot =
+ explicitTestIdRoot ?? (mode === "edit" ? "edit-backend" : "add-backend");
+
const canSubmit =
name.trim().length > 0 &&
host.trim().length > 0 &&
(kind === "local" || apiKey.trim().length > 0);
- const onSubmit = (event: React.FormEvent<HTMLFormElement>) => {
+ const handleSubmit = (event: React.FormEvent<HTMLFormElement>) => {
event.preventDefault();
if (!canSubmit) return;
@@ -89,67 +197,51 @@ export function BackendFormModal({
addBackend(payload);
}
- onClose();
+ onSubmitted();
};
- const titleKey =
- mode === "edit" ? I18nKey.BACKEND$EDIT_TITLE : I18nKey.BACKEND$ADD_TITLE;
- const testIdRoot = mode === "edit" ? "edit-backend" : "add-backend";
-
return (
- <ModalBackdrop
- onClose={onClose}
- closeOnEscape={false}
- aria-label={t(titleKey)}
+ <form
+ data-testid={`${testIdRoot}-form`}
+ onSubmit={handleSubmit}
+ className="flex flex-col gap-4"
>
- <form
- data-testid={`${testIdRoot}-modal`}
- onSubmit={onSubmit}
- className="bg-base-secondary p-6 rounded-xl flex flex-col gap-4 border border-tertiary"
- style={{ width: "480px" }}
- >
- <div className="flex flex-col gap-1">
- <h3 className="text-xl font-bold">{t(titleKey)}</h3>
- {mode === "add" ? (
- <p className="text-xs text-gray-400">
- {t(I18nKey.BACKEND$ADD_SUBTITLE)}
- </p>
- ) : null}
- </div>
-
- <SettingsInput
- testId={`${testIdRoot}-name`}
- name={`${testIdRoot}-name`}
- type="text"
- label={t(I18nKey.BACKEND$NAME_LABEL)}
- value={name}
- onChange={setName}
- placeholder="Production"
- className="w-full"
- />
+ <SettingsInput
+ testId={`${testIdRoot}-name`}
+ name={`${testIdRoot}-name`}
+ type="text"
+ label={t(I18nKey.BACKEND$NAME_LABEL)}
+ value={name}
+ onChange={setName}
+ placeholder="Production"
+ className="w-full"
+ />
- <SettingsInput
- testId={`${testIdRoot}-host`}
- name={`${testIdRoot}-host`}
- type="text"
- label={t(I18nKey.BACKEND$HOST_LABEL)}
- value={host}
- onChange={setHost}
- placeholder="https://app.all-hands.dev"
- className="w-full"
- />
+ <SettingsInput
+ testId={`${testIdRoot}-host`}
+ name={`${testIdRoot}-host`}
+ type="text"
+ label={t(I18nKey.BACKEND$HOST_LABEL)}
+ value={host}
+ onChange={setHost}
+ placeholder="https://app.all-hands.dev"
+ className="w-full"
+ />
- <SettingsInput
- testId={`${testIdRoot}-api-key`}
- name={`${testIdRoot}-api-key`}
- type="password"
- label={t(I18nKey.BACKEND$KEY_LABEL)}
- value={apiKey}
- onChange={setApiKey}
- placeholder=""
- className="w-full"
- />
+ <SettingsInput
+ testId={`${testIdRoot}-api-key`}
+ name={`${testIdRoot}-api-key`}
+ type="password"
+ label={t(I18nKey.BACKEND$KEY_LABEL)}
+ value={apiKey}
+ onChange={setApiKey}
+ placeholder=""
+ className="w-full"
+ />
+ {mode === "edit" && backend ? (
+ <BackendStatusBadge backend={backend} testIdRoot={testIdRoot} />
+ ) : (
<fieldset className="flex flex-col">
<legend className="text-sm mb-3">
{t(I18nKey.BACKEND$KIND_LABEL)}
@@ -188,7 +280,11 @@ export function BackendFormModal({
: t(I18nKey.BACKEND$KEY_HELPER_LOCAL)}
</p>
</fieldset>
+ )}
+ {renderActions ? (
+ renderActions({ canSubmit, testIdRoot })
+ ) : (
<div className="grid grid-cols-2 gap-2 mt-2 w-full">
<BrandButton
type="submit"
@@ -202,14 +298,61 @@ export function BackendFormModal({
<BrandButton
type="button"
variant="secondary"
- onClick={onClose}
+ onClick={onSubmitted}
testId={`${testIdRoot}-cancel`}
className="w-full text-center"
>
{t(I18nKey.BUTTON$CANCEL)}
</BrandButton>
</div>
- </form>
+ )}
+ </form>
+ );
+}
+
+/**
+ * Modal wrapper around `BackendForm`. Used by both the dropdown's
+ * "Add backend" trigger and the manage-backends modal's edit /
+ * add-inline buttons.
+ */
+export function BackendFormModal({
+ mode,
+ backend,
+ onClose,
+}: BackendFormModalProps) {
+ const { t } = useTranslation("openhands");
+
+ const titleKey =
+ mode === "edit" ? I18nKey.BACKEND$EDIT_TITLE : I18nKey.BACKEND$ADD_TITLE;
+ const testIdRoot = mode === "edit" ? "edit-backend" : "add-backend";
+
+ return (
+ <ModalBackdrop
+ onClose={onClose}
+ closeOnEscape={false}
+ aria-label={t(titleKey)}
+ >
+ <div
+ data-testid={`${testIdRoot}-modal`}
+ className="bg-base-secondary p-6 rounded-xl flex flex-col gap-4 border border-tertiary"
+ style={{ width: "480px" }}
+ >
+ <div className="flex flex-col gap-1">
+ <h3 className="text-xl font-bold">{t(titleKey)}</h3>
+ {mode === "add" ? (
+ <p className="text-xs text-gray-400">
+ {t(I18nKey.BACKEND$ADD_SUBTITLE)}
+ </p>
+ ) : null}
+ </div>
+
+ <BackendForm
+ mode={mode}
+ backend={backend}
+ onSubmitted={onClose}
+ testIdRoot={testIdRoot}
+ />
+ </div>
</ModalBackdrop>
);
}
diff --git a/src/components/features/onboarding/index.ts b/src/components/features/onboarding/index.ts
new file mode 100644
index 0000000000..57573b7b1a
--- /dev/null
+++ b/src/components/features/onboarding/index.ts
@@ -0,0 +1,7 @@
+export { OnboardingModal } from "./onboarding-modal";
+export { OnboardingHost } from "./onboarding-host";
+export { OnboardingProgressBar } from "./onboarding-progress-bar";
+export {
+ useOnboardingCompletion,
+ ONBOARDING_COMPLETED_STORAGE_KEY,
+} from "./use-onboarding-completion";
diff --git a/src/components/features/onboarding/onboarding-host.tsx b/src/components/features/onboarding/onboarding-host.tsx
new file mode 100644
index 0000000000..468b7acdc0
--- /dev/null
+++ b/src/components/features/onboarding/onboarding-host.tsx
@@ -0,0 +1,19 @@
+import React from "react";
+import { OnboardingModal } from "./onboarding-modal";
+import { useOnboardingCompletion } from "./use-onboarding-completion";
+
+/**
+ * Mounts the onboarding modal automatically the first time the user
+ * lands on a host route (i.e. when the localStorage onboarding flag
+ * isn't set yet). Closing or completing the flow marks it done so the
+ * modal won't re-appear on subsequent visits.
+ *
+ * Renders nothing once onboarding has been completed.
+ */
+export function OnboardingHost() {
+ const { isCompleted, markCompleted } = useOnboardingCompletion();
+
+ if (isCompleted) return null;
+
+ return <OnboardingModal onClose={markCompleted} />;
+}
diff --git a/src/components/features/onboarding/onboarding-modal.tsx b/src/components/features/onboarding/onboarding-modal.tsx
new file mode 100644
index 0000000000..dcae1215b8
--- /dev/null
+++ b/src/components/features/onboarding/onboarding-modal.tsx
@@ -0,0 +1,159 @@
+import React from "react";
+import { useTranslation } from "react-i18next";
+import { X } from "lucide-react";
+import { ModalBackdrop } from "#/components/shared/modals/modal-backdrop";
+import { I18nKey } from "#/i18n/declaration";
+import { cn } from "#/utils/utils";
+import { OnboardingProgressBar } from "./onboarding-progress-bar";
+import {
+ ChooseAgentStep,
+ type OnboardingAgentId,
+} from "./steps/choose-agent-step";
+import { CheckBackendStep } from "./steps/check-backend-step";
+import { SetupLlmStep } from "./steps/setup-llm-step";
+import { SayHelloStep } from "./steps/say-hello-step";
+
+const TOTAL_STEPS = 4;
+
+interface SlideProps {
+ /** Index of this slide in the step sequence. */
+ index: number;
+ /** Index of the currently visible step. */
+ currentStep: number;
+ children: React.ReactNode;
+}
+
+/**
+ * One step panel inside the slide rail.
+ *
+ * Only the active slide is in normal flow — it drives the surrounding
+ * container's height. Inactive slides are absolutely positioned so
+ * they don't add their height to the modal box (which previously made
+ * the modal "overhang" with empty space sized to the tallest step).
+ *
+ * Each slide is translated horizontally by `(index - currentStep) *
+ * 100%` so the active step sits at offset 0, with prior steps off to
+ * the left and upcoming steps off to the right. Changes to
+ * `currentStep` smoothly animate the transform.
+ */
+function Slide({ index, currentStep, children }: SlideProps) {
+ const isActive = index === currentStep;
+ const offsetPct = (index - currentStep) * 100;
+ return (
+ <div
+ data-testid={`onboarding-slide-${index}`}
+ data-active={isActive}
+ aria-hidden={!isActive}
+ style={{ transform: `translateX(${offsetPct}%)` }}
+ className={cn(
+ "w-full transition-transform duration-300 ease-out",
+ // Inactive slides are taken out of flow so the rail's height
+ // tracks just the active step; they stay overlaid via inset-0
+ // so they slide in/out of view across the same horizontal box.
+ !isActive && "pointer-events-none absolute inset-0",
+ )}
+ >
+ {children}
+ </div>
+ );
+}
+
+interface OnboardingModalProps {
+ /** Called when the user dismisses the modal (skip / X / launch). */
+ onClose: () => void;
+}
+
+/**
+ * Top-level onboarding modal for first-time users.
+ *
+ * The flow is a fixed sequence of four steps:
+ * 0. Choose agent
+ * 1. Check backend
+ * 2. Set up LLM
+ * 3. Say hello (creates a fresh conversation, then closes)
+ *
+ * Each step lives in its own slide; all four are mounted at once and
+ * the rail is translated horizontally by step index, so transitioning
+ * between steps animates the new step in from the right.
+ */
+export function OnboardingModal({ onClose }: OnboardingModalProps) {
+ const { t } = useTranslation("openhands");
+ const [currentStep, setCurrentStep] = React.useState(0);
+ const [selectedAgentId, setSelectedAgentId] =
+ React.useState<OnboardingAgentId>("openhands");
+
+ const goNext = React.useCallback(
+ () => setCurrentStep((step) => (step >= TOTAL_STEPS - 1 ? step : step + 1)),
+ [],
+ );
+ const goBack = React.useCallback(
+ () => setCurrentStep((step) => (step <= 0 ? 0 : step - 1)),
+ [],
+ );
+
+ return (
+ <ModalBackdrop
+ onClose={onClose}
+ closeOnEscape={false}
+ aria-label={t(I18nKey.ONBOARDING$TITLE)}
+ >
+ <section
+ data-testid="onboarding-modal"
+ data-current-step={currentStep}
+ className={cn(
+ "flex flex-col gap-6 rounded-2xl border border-white/10 bg-base-secondary shadow-2xl",
+ "w-[560px] max-w-[92vw]",
+ )}
+ >
+ <header className="flex flex-col gap-3 px-7 pt-7">
+ <div className="flex items-center justify-between gap-3">
+ <p className="text-sm text-gray-400">
+ {t(I18nKey.ONBOARDING$STEP_LABEL, {
+ current: currentStep + 1,
+ total: TOTAL_STEPS,
+ })}
+ </p>
+ <button
+ type="button"
+ data-testid="onboarding-skip"
+ onClick={onClose}
+ className="flex items-center gap-1 rounded-md px-2 py-1 text-xs text-gray-400 hover:bg-white/5 hover:text-white"
+ >
+ <span>{t(I18nKey.ONBOARDING$SKIP)}</span>
+ <X className="size-3.5" aria-hidden />
+ </button>
+ </div>
+ <OnboardingProgressBar
+ currentStep={currentStep}
+ totalSteps={TOTAL_STEPS}
+ />
+ </header>
+
+ <div className="px-7 pb-7">
+ <div
+ data-testid="onboarding-slide-rail"
+ data-current-step={currentStep}
+ className="relative overflow-hidden"
+ >
+ <Slide index={0} currentStep={currentStep}>
+ <ChooseAgentStep
+ selectedAgentId={selectedAgentId}
+ onSelect={setSelectedAgentId}
+ onNext={goNext}
+ />
+ </Slide>
+ <Slide index={1} currentStep={currentStep}>
+ <CheckBackendStep onBack={goBack} onNext={goNext} />
+ </Slide>
+ <Slide index={2} currentStep={currentStep}>
+ <SetupLlmStep onBack={goBack} onNext={goNext} />
+ </Slide>
+ <Slide index={3} currentStep={currentStep}>
+ <SayHelloStep onBack={goBack} onLaunched={onClose} />
+ </Slide>
+ </div>
+ </div>
+ </section>
+ </ModalBackdrop>
+ );
+}
diff --git a/src/components/features/onboarding/onboarding-progress-bar.tsx b/src/components/features/onboarding/onboarding-progress-bar.tsx
new file mode 100644
index 0000000000..244c4f37d3
--- /dev/null
+++ b/src/components/features/onboarding/onboarding-progress-bar.tsx
@@ -0,0 +1,50 @@
+import { cn } from "#/utils/utils";
+
+interface OnboardingProgressBarProps {
+ /** Index of the current step (0-based). */
+ currentStep: number;
+ /** Total number of steps in the flow. */
+ totalSteps: number;
+ className?: string;
+}
+
+/**
+ * Segmented progress bar rendered at the top of the onboarding modal.
+ * Each step is its own pill that fills in as the user moves forward,
+ * giving an at-a-glance sense of how far they have to go.
+ */
+export function OnboardingProgressBar({
+ currentStep,
+ totalSteps,
+ className,
+}: OnboardingProgressBarProps) {
+ return (
+ <div
+ role="progressbar"
+ aria-valuemin={1}
+ aria-valuemax={totalSteps}
+ aria-valuenow={currentStep + 1}
+ data-testid="onboarding-progress-bar"
+ className={cn("flex w-full items-center gap-2", className)}
+ >
+ {Array.from({ length: totalSteps }, (_, index) => {
+ const isCompleted = index < currentStep;
+ const isCurrent = index === currentStep;
+ return (
+ <div
+ key={index}
+ data-testid={`onboarding-progress-step-${index}`}
+ data-state={
+ // eslint-disable-next-line no-nested-ternary
+ isCompleted ? "completed" : isCurrent ? "current" : "upcoming"
+ }
+ className={cn(
+ "h-1.5 flex-1 rounded-full transition-colors duration-300",
+ isCompleted || isCurrent ? "bg-primary" : "bg-white/15",
+ )}
+ />
+ );
+ })}
+ </div>
+ );
+}
diff --git a/src/components/features/onboarding/steps/check-backend-step.tsx b/src/components/features/onboarding/steps/check-backend-step.tsx
new file mode 100644
index 0000000000..9b3c9f474c
--- /dev/null
+++ b/src/components/features/onboarding/steps/check-backend-step.tsx
@@ -0,0 +1,142 @@
+import React from "react";
+import { useTranslation } from "react-i18next";
+import { CheckCircle2, Loader2, AlertCircle } from "lucide-react";
+import { BackendForm } from "#/components/features/backends/backend-form-modal";
+import { BrandButton } from "#/components/features/settings/brand-button";
+import { useActiveBackendContext } from "#/contexts/active-backend-context";
+import { useBackendsHealth } from "#/hooks/query/use-backends-health";
+import { I18nKey } from "#/i18n/declaration";
+import { cn } from "#/utils/utils";
+
+interface CheckBackendStepProps {
+ onBack: () => void;
+ onNext: () => void;
+}
+
+function ConnectionBanner({ isConnected }: { isConnected: boolean | null }) {
+ const { t } = useTranslation("openhands");
+
+ if (isConnected === true) {
+ return (
+ <div
+ role="status"
+ data-testid="onboarding-backend-connected"
+ className={cn(
+ "flex items-start gap-3 rounded-xl border border-green-500/40 bg-green-500/10 px-4 py-3",
+ )}
+ >
+ <CheckCircle2 className="mt-0.5 size-5 shrink-0 text-green-400" />
+ <div className="flex flex-col gap-1">
+ <span className="text-sm font-medium text-green-200">
+ {t(I18nKey.ONBOARDING$BACKEND_CONNECTED_TITLE)}
+ </span>
+ <span className="text-xs text-green-200/80">
+ {t(I18nKey.ONBOARDING$BACKEND_CONNECTED_BODY)}
+ </span>
+ </div>
+ </div>
+ );
+ }
+
+ if (isConnected === false) {
+ return (
+ <div
+ role="alert"
+ data-testid="onboarding-backend-disconnected"
+ className="flex items-start gap-3 rounded-xl border border-red-500/40 bg-red-500/10 px-4 py-3"
+ >
+ <AlertCircle className="mt-0.5 size-5 shrink-0 text-red-400" />
+ <div className="flex flex-col gap-1">
+ <span className="text-sm font-medium text-red-200">
+ {t(I18nKey.ONBOARDING$BACKEND_DISCONNECTED_TITLE)}
+ </span>
+ <span className="text-xs text-red-200/80">
+ {t(I18nKey.ONBOARDING$BACKEND_DISCONNECTED_BODY)}
+ </span>
+ </div>
+ </div>
+ );
+ }
+
+ return (
+ <div
+ role="status"
+ data-testid="onboarding-backend-checking"
+ className="flex items-start gap-3 rounded-xl border border-white/10 bg-white/5 px-4 py-3"
+ >
+ <Loader2 className="mt-0.5 size-5 shrink-0 animate-spin text-gray-300" />
+ <span className="text-sm text-gray-200">
+ {t(I18nKey.ONBOARDING$BACKEND_CHECKING)}
+ </span>
+ </div>
+ );
+}
+
+/**
+ * Step 1: embed the "edit backend" form pre-populated with the
+ * default/active backend, plus a contextual success/error banner that
+ * reacts to the live health probe.
+ */
+export function CheckBackendStep({ onBack, onNext }: CheckBackendStepProps) {
+ const { t } = useTranslation("openhands");
+ const { active } = useActiveBackendContext();
+ const { backend } = active;
+ const healthByBackendId = useBackendsHealth([backend]);
+ const isConnected = healthByBackendId[backend.id]?.isConnected ?? null;
+
+ return (
+ <div
+ data-testid="onboarding-step-check-backend"
+ className="flex flex-col gap-6"
+ >
+ <header className="flex flex-col gap-2">
+ <h2 className="text-2xl font-semibold text-white">
+ {t(I18nKey.ONBOARDING$BACKEND_TITLE)}
+ </h2>
+ <p className="text-sm text-gray-400">
+ {t(I18nKey.ONBOARDING$BACKEND_SUBTITLE)}
+ </p>
+ </header>
+
+ <ConnectionBanner isConnected={isConnected} />
+
+ <BackendForm
+ mode="edit"
+ backend={backend}
+ onSubmitted={() => {}}
+ testIdRoot="onboarding-backend"
+ renderActions={({ canSubmit, testIdRoot }) => (
+ <div className="flex items-center justify-between gap-2 mt-2">
+ <BrandButton
+ testId="onboarding-backend-back"
+ type="button"
+ variant="secondary"
+ onClick={onBack}
+ >
+ {t(I18nKey.ONBOARDING$BACK)}
+ </BrandButton>
+ <div className="flex gap-2">
+ <BrandButton
+ testId={`${testIdRoot}-submit`}
+ type="submit"
+ variant="secondary"
+ isDisabled={!canSubmit}
+ >
+ {t(I18nKey.BACKEND$SAVE)}
+ </BrandButton>
+ <BrandButton
+ testId="onboarding-backend-next"
+ type="button"
+ variant="primary"
+ isDisabled={isConnected !== true}
+ onClick={onNext}
+ >
+ {t(I18nKey.ONBOARDING$NEXT)}
+ </BrandButton>
+ </div>
+ </div>
+ )}
+ />
+ </div>
+ );
+}
diff --git a/src/components/features/onboarding/steps/choose-agent-step.tsx b/src/components/features/onboarding/steps/choose-agent-step.tsx
new file mode 100644
index 0000000000..9cc03cdf74
--- /dev/null
+++ b/src/components/features/onboarding/steps/choose-agent-step.tsx
@@ -0,0 +1,139 @@
+import React from "react";
+import { useTranslation } from "react-i18next";
+import { Check, Sparkles } from "lucide-react";
+import { BrandButton } from "#/components/features/settings/brand-button";
+import { I18nKey } from "#/i18n/declaration";
+import { cn } from "#/utils/utils";
+
+export type OnboardingAgentId = "openhands" | "claude-code" | "codex";
+
+interface AgentOption {
+ id: OnboardingAgentId;
+ label: string;
+ descriptionKey: I18nKey;
+ enabled: boolean;
+}
+
+const AGENT_OPTIONS: AgentOption[] = [
+ {
+ id: "openhands",
+ label: "OpenHands",
+ descriptionKey: I18nKey.ONBOARDING$AGENT_OPENHANDS_DESCRIPTION,
+ enabled: true,
+ },
+ {
+ id: "claude-code",
+ label: "Claude Code",
+ descriptionKey: I18nKey.ONBOARDING$AGENT_CLAUDE_CODE_DESCRIPTION,
+ enabled: false,
+ },
+ {
+ id: "codex",
+ label: "Codex",
+ descriptionKey: I18nKey.ONBOARDING$AGENT_CODEX_DESCRIPTION,
+ enabled: false,
+ },
+];
+
+interface ChooseAgentStepProps {
+ selectedAgentId: OnboardingAgentId;
+ onSelect: (agentId: OnboardingAgentId) => void;
+ onNext: () => void;
+}
+
+export function ChooseAgentStep({
+ selectedAgentId,
+ onSelect,
+ onNext,
+}: ChooseAgentStepProps) {
+ const { t } = useTranslation("openhands");
+
+ return (
+ <div
+ data-testid="onboarding-step-choose-agent"
+ className="flex flex-col gap-6"
+ >
+ <header className="flex flex-col gap-2">
+ <h2 className="text-2xl font-semibold text-white">
+ {t(I18nKey.ONBOARDING$AGENT_TITLE)}
+ </h2>
+ <p className="text-sm text-gray-400">
+ {t(I18nKey.ONBOARDING$AGENT_SUBTITLE)}
+ </p>
+ </header>
+
+ <div
+ role="note"
+ data-testid="onboarding-agent-coming-soon"
+ className={cn(
+ "flex items-start gap-3 rounded-xl border border-primary/40 bg-primary/10 px-4 py-3",
+ )}
+ >
+ <Sparkles className="mt-0.5 size-5 shrink-0 text-primary" aria-hidden />
+ <p className="text-sm font-medium text-primary">
+ {t(I18nKey.ONBOARDING$AGENT_COMING_SOON)}
+ </p>
+ </div>
+
+ <div
+ role="radiogroup"
+ aria-label={t(I18nKey.ONBOARDING$AGENT_TITLE)}
+ className="flex flex-col gap-3"
+ >
+ {AGENT_OPTIONS.map((option) => {
+ const isSelected = option.id === selectedAgentId;
+ return (
+ <button
+ key={option.id}
+ type="button"
+ role="radio"
+ aria-checked={isSelected}
+ aria-disabled={!option.enabled}
+ disabled={!option.enabled}
+ data-testid={`onboarding-agent-option-${option.id}`}
+ data-selected={isSelected}
+ onClick={() => option.enabled && onSelect(option.id)}
+ className={cn(
+ "flex items-start justify-between gap-4 rounded-xl border px-4 py-3 text-left transition-colors",
+ option.enabled
+ ? "cursor-pointer hover:border-primary/60 hover:bg-white/5"
+ : "cursor-not-allowed opacity-50",
+ isSelected
+ ? "border-primary bg-primary/10"
+ : "border-white/10 bg-base-secondary",
+ )}
+ >
+ <div className="flex flex-col gap-1">
+ <span className="text-base font-medium text-white">
+ {option.label}
+ </span>
+ <span className="text-xs text-gray-400">
+ {t(option.descriptionKey)}
+ </span>
+ </div>
+ {isSelected ? (
+ <Check
+ width={18}
+ height={18}
+ className="mt-1 shrink-0 text-primary"
+ aria-hidden
+ />
+ ) : null}
+ </button>
+ );
+ })}
+ </div>
+
+ <div className="flex justify-end">
+ <BrandButton
+ testId="onboarding-agent-next"
+ type="button"
+ variant="primary"
+ onClick={onNext}
+ >
+ {t(I18nKey.ONBOARDING$NEXT)}
+ </BrandButton>
+ </div>
+ </div>
+ );
+}
diff --git a/src/components/features/onboarding/steps/say-hello-step.tsx b/src/components/features/onboarding/steps/say-hello-step.tsx
new file mode 100644
index 0000000000..e8ddf523e6
--- /dev/null
+++ b/src/components/features/onboarding/steps/say-hello-step.tsx
@@ -0,0 +1,105 @@
+import React from "react";
+import { useTranslation } from "react-i18next";
+import { Send } from "lucide-react";
+import { BrandButton } from "#/components/features/settings/brand-button";
+import { useNavigation } from "#/context/navigation-context";
+import { useCreateConversation } from "#/hooks/mutation/use-create-conversation";
+import { useIsCreatingConversation } from "#/hooks/use-is-creating-conversation";
+import { I18nKey } from "#/i18n/declaration";
+
+interface SayHelloStepProps {
+ onBack: () => void;
+ /** Called once the conversation has been created — used by the parent
+ * modal to mark the onboarding as complete before unmounting. */
+ onLaunched: () => void;
+}
+
+/**
+ * Step 3: a simple text input pre-filled with "hello OpenHands!" that
+ * launches a brand-new conversation with no workspace and navigates
+ * to it. Completing this step finishes the onboarding flow.
+ */
+export function SayHelloStep({ onBack, onLaunched }: SayHelloStepProps) {
+ const { t } = useTranslation("openhands");
+ const { navigate } = useNavigation();
+ const defaultMessage = t(I18nKey.ONBOARDING$HELLO_DEFAULT_MESSAGE);
+ const [message, setMessage] = React.useState(defaultMessage);
+
+ const {
+ mutate: createConversation,
+ isPending,
+ isSuccess,
+ } = useCreateConversation();
+ const isCreatingElsewhere = useIsCreatingConversation();
+ const isLaunching = isPending || isSuccess || isCreatingElsewhere;
+
+ const canSubmit = message.trim().length > 0 && !isLaunching;
+
+ const handleSubmit = (event: React.FormEvent<HTMLFormElement>) => {
+ event.preventDefault();
+ if (!canSubmit) return;
+
+ // Explicitly omit `repository` and `workingDir` so the
+ // conversation starts with no workspace, per the spec.
+ createConversation(
+ { query: message.trim() },
+ {
+ onSuccess: (data) => {
+ onLaunched();
+ navigate(`/conversations/${data.conversation_id}`);
+ },
+ },
+ );
+ };
+
+ return (
+ <form
+ data-testid="onboarding-step-say-hello"
+ onSubmit={handleSubmit}
+ className="flex flex-col gap-6"
+ >
+ <header className="flex flex-col gap-2">
+ <h2 className="text-2xl font-semibold text-white">
+ {t(I18nKey.ONBOARDING$HELLO_TITLE)}
+ </h2>
+ <p className="text-sm text-gray-400">
+ {t(I18nKey.ONBOARDING$HELLO_SUBTITLE)}
+ </p>
+ </header>
+
+ <input
+ data-testid="onboarding-hello-input"
+ aria-label={t(I18nKey.ONBOARDING$HELLO_TITLE)}
+ type="text"
+ value={message}
+ onChange={(event) => setMessage(event.target.value)}
+ placeholder={defaultMessage}
+ disabled={isLaunching}
+ className="w-full rounded-xl border border-white/10 bg-base-secondary px-4 py-3 text-base text-white placeholder:text-gray-500 focus:border-primary focus:outline-none disabled:opacity-60"
+ />
+
+ <div className="flex items-center justify-between gap-2">
+ <BrandButton
+ testId="onboarding-hello-back"
+ type="button"
+ variant="secondary"
+ onClick={onBack}
+ isDisabled={isLaunching}
+ >
+ {t(I18nKey.ONBOARDING$BACK)}
+ </BrandButton>
+ <BrandButton
+ testId="onboarding-hello-launch"
+ type="submit"
+ variant="primary"
+ isDisabled={!canSubmit}
+ startContent={<Send className="size-4" aria-hidden />}
+ >
+ {isLaunching
+ ? t(I18nKey.ONBOARDING$HELLO_LAUNCHING)
+ : t(I18nKey.ONBOARDING$HELLO_LAUNCH)}
+ </BrandButton>
+ </div>
+ </form>
+ );
+}
diff --git a/src/components/features/onboarding/steps/setup-llm-step.tsx b/src/components/features/onboarding/steps/setup-llm-step.tsx
new file mode 100644
index 0000000000..ce09fd1c08
--- /dev/null
+++ b/src/components/features/onboarding/steps/setup-llm-step.tsx
@@ -0,0 +1,96 @@
+import React from "react";
+import { useTranslation } from "react-i18next";
+import { BrandButton } from "#/components/features/settings/brand-button";
+import { I18nKey } from "#/i18n/declaration";
+import { LlmSettingsScreen } from "#/routes/llm-settings";
+import type { SdkSectionSaveControl } from "#/components/features/settings/sdk-settings/sdk-section-page";
+
+interface SetupLlmStepProps {
+ onBack: () => void;
+ onNext: () => void;
+}
+
+/**
+ * Pre-fills the LLM form with Anthropic / Claude Opus when the user
+ * lands on this onboarding step. The global `DEFAULT_SETTINGS` ships
+ * the OpenHands-prefixed Opus, but the onboarding spec calls for
+ * routing directly through Anthropic, and these overrides are also
+ * marked dirty so the Next button is enabled immediately.
+ */
+const ONBOARDING_LLM_OVERRIDES = {
+ "llm.model": "anthropic/claude-opus-4-5-20251101",
+} as const;
+
+/**
+ * Step 2: embed the LLM settings form. The screen runs in `embedded`
+ * mode (so it doesn't render its own sticky Save bar) and with
+ * `hideSaveButton` set, surfacing its save state via
+ * `onSaveControlChange`. We then render a single Next button at the
+ * modal footer level matching the other onboarding steps; clicking
+ * Next saves the form and `onSaveSuccess` advances to the next step.
+ *
+ * If the form happens to be untouched (no dirty fields), Next falls
+ * through to advancing without a save call, so users with already-
+ * configured settings aren't blocked.
+ */
+export function SetupLlmStep({ onBack, onNext }: SetupLlmStepProps) {
+ const { t } = useTranslation("openhands");
+ const [saveControl, setSaveControl] =
+ React.useState<SdkSectionSaveControl | null>(null);
+
+ const handleNext = () => {
+ if (saveControl?.isDirty) {
+ saveControl.save();
+ // `onSaveSuccess` (wired to `onNext` below) will advance once
+ // the mutation resolves successfully.
+ return;
+ }
+ onNext();
+ };
+
+ return (
+ <div
+ data-testid="onboarding-step-setup-llm"
+ className="flex flex-col gap-6"
+ >
+ <header className="flex flex-col gap-2">
+ <h2 className="text-2xl font-semibold text-white">
+ {t(I18nKey.ONBOARDING$LLM_TITLE)}
+ </h2>
+ <p className="text-sm text-gray-400">
+ {t(I18nKey.ONBOARDING$LLM_SUBTITLE)}
+ </p>
+ </header>
+
+ <div data-testid="onboarding-llm-settings">
+ <LlmSettingsScreen
+ embedded
+ hideSaveButton
+ initialValueOverrides={ONBOARDING_LLM_OVERRIDES}
+ onSaveSuccess={onNext}
+ onSaveControlChange={setSaveControl}
+ />
+ </div>
+
+ <div className="flex items-center justify-between gap-2">
+ <BrandButton
+ testId="onboarding-llm-back"
+ type="button"
+ variant="secondary"
+ onClick={onBack}
+ >
+ {t(I18nKey.ONBOARDING$BACK)}
+ </BrandButton>
+ <BrandButton
+ testId="onboarding-llm-next"
+ type="button"
+ variant="primary"
+ isDisabled={saveControl?.isSaving ?? false}
+ onClick={handleNext}
+ >
+ {t(I18nKey.ONBOARDING$NEXT)}
+ </BrandButton>
+ </div>
+ </div>
+ );
+}
diff --git a/src/components/features/onboarding/use-onboarding-completion.ts b/src/components/features/onboarding/use-onboarding-completion.ts
new file mode 100644
index 0000000000..3853e1869f
--- /dev/null
+++ b/src/components/features/onboarding/use-onboarding-completion.ts
@@ -0,0 +1,53 @@
+import React from "react";
+
+/**
+ * localStorage key persisting whether the welcome onboarding flow has
+ * been completed (or skipped). Once present, the modal won't auto-show
+ * again on subsequent visits.
+ */
+export const ONBOARDING_COMPLETED_STORAGE_KEY = "openhands-onboarded";
+
+function readCompletedFromStorage(): boolean {
+ if (typeof window === "undefined") return true;
+ try {
+ return (
+ window.localStorage.getItem(ONBOARDING_COMPLETED_STORAGE_KEY) !== null
+ );
+ } catch {
+ // Inaccessible localStorage (private mode, SSR, …) — assume the
+ // user has already onboarded so we don't loop on every render.
+ return true;
+ }
+}
+
+/**
+ * Tracks whether the welcome onboarding modal has been completed.
+ * The hook returns the current `isCompleted` flag plus an imperative
+ * `markCompleted()` callback. State is mirrored to localStorage and
+ * synced across tabs via the `storage` event.
+ */
+export function useOnboardingCompletion() {
+ const [isCompleted, setIsCompleted] = React.useState<boolean>(() =>
+ readCompletedFromStorage(),
+ );
+
+ React.useEffect(() => {
+ const handleStorage = (event: StorageEvent) => {
+ if (event.key !== ONBOARDING_COMPLETED_STORAGE_KEY) return;
+ setIsCompleted(readCompletedFromStorage());
+ };
+ window.addEventListener("storage", handleStorage);
+ return () => window.removeEventListener("storage", handleStorage);
+ }, []);
+
+ const markCompleted = React.useCallback(() => {
+ try {
+ window.localStorage.setItem(ONBOARDING_COMPLETED_STORAGE_KEY, "1");
+ } catch {
+ // best-effort; we still flip the in-memory flag below.
+ }
+ setIsCompleted(true);
+ }, []);
+
+ return { isCompleted, markCompleted } as const;
+}
diff --git a/src/components/features/settings/sdk-settings/sdk-section-page.tsx b/src/components/features/settings/sdk-settings/sdk-section-page.tsx
index 9ec9b14365..673867924f 100644
--- a/src/components/features/settings/sdk-settings/sdk-section-page.tsx
+++ b/src/components/features/settings/sdk-settings/sdk-section-page.tsx
@@ -101,6 +101,21 @@ export interface SdkSectionHeaderProps {
onChange: (key: string, value: string | boolean) => void;
}
+/**
+ * Snapshot of the page's save state, surfaced to the parent so it can
+ * render its own Save/Next button (e.g. in onboarding) when
+ * {@link SdkSectionPage}'s built-in button is hidden via
+ * `hideSaveButton`.
+ */
+export interface SdkSectionSaveControl {
+ /** Trigger a save of the currently-dirty fields. No-op while `isSaving` or `!isDirty`. */
+ save: () => void;
+ /** A save mutation is in flight. */
+ isSaving: boolean;
+ /** At least one field is dirty (or `extraDirty` was passed in). */
+ isDirty: boolean;
+}
+
/**
* A generic SDK-schema–driven settings page that renders fields
* from one or more schema sections.
@@ -122,6 +137,10 @@ export function SdkSectionPage({
getInitialView,
forceShowAdvancedView = false,
allowAllView = true,
+ initialValueOverrides,
+ embedded = false,
+ hideSaveButton = false,
+ onSaveControlChange,
testId = "sdk-section-settings-screen",
}: {
sectionKeys: string[];
@@ -146,6 +165,34 @@ export function SdkSectionPage({
) => SettingsView;
forceShowAdvancedView?: boolean;
allowAllView?: boolean;
+ /**
+ * Per-field initial value overrides that win over the values
+ * derived from `useSettings`. The keys of each override are also
+ * marked dirty on hydration so the user can save the form without
+ * having to touch the prefilled fields. Useful when the page is
+ * embedded in a flow that wants to nudge brand-new users toward a
+ * particular default (e.g. onboarding pre-filling Anthropic/Opus).
+ */
+ initialValueOverrides?: SettingsFormValues;
+ /**
+ * When true, the Save button container is rendered inline (no
+ * sticky positioning, no contrasting `bg-base` band) so the page
+ * can be dropped into a modal/card without a hard footer break.
+ */
+ embedded?: boolean;
+ /**
+ * Suppress the built-in Save Changes button entirely. Pair with
+ * {@link onSaveControlChange} to drive saving from a parent-rendered
+ * action (e.g. an onboarding "Next" button).
+ */
+ hideSaveButton?: boolean;
+ /**
+ * Fires whenever the save state changes (a mutation starts/finishes,
+ * dirty status flips). Provides a stable `save()` callback the
+ * parent can wire to its own button. Useful when the form is
+ * embedded in a custom flow and the built-in Save button is hidden.
+ */
+ onSaveControlChange?: (control: SdkSectionSaveControl) => void;
testId?: string;
}) {
const { t } = useTranslation("openhands");
@@ -201,14 +248,24 @@ export function SdkSectionPage({
[activeSchemaQuery.error, t],
);
+ const overridesSignature = React.useMemo(
+ () => (initialValueOverrides ? JSON.stringify(initialValueOverrides) : ""),
+ [initialValueOverrides],
+ );
+
const initialValues = React.useMemo(() => {
if (!settings || !filteredSchema) return null;
- return buildInitialSettingsFormValues(
+ const base = buildInitialSettingsFormValues(
settings,
filteredSchema,
settingsSource,
);
- }, [settings, filteredSchema, settingsSource]);
+ if (!initialValueOverrides) return base;
+ return { ...base, ...initialValueOverrides };
+ // overridesSignature keeps the memo reactive without depending on
+ // a (potentially recreated) object reference each render.
+ // eslint-disable-next-line react-hooks/exhaustive-deps
+ }, [settings, filteredSchema, settingsSource, overridesSignature]);
const initialView = React.useMemo(() => {
if (!settings || !filteredSchema) return null;
@@ -238,7 +295,16 @@ export function SdkSectionPage({
if (!initialValues || !initialView) return;
setValues(initialValues);
- setDirty({});
+ // Override-supplied keys are pre-populated for the user, so mark
+ // them dirty up-front; otherwise the Save button stays disabled
+ // until the user touches a field, defeating the point of the
+ // override.
+ const overrideDirty: SettingsDirtyState = initialValueOverrides
+ ? Object.fromEntries(
+ Object.keys(initialValueOverrides).map((key) => [key, true]),
+ )
+ : {};
+ setDirty(overrideDirty);
setView((currentView) => {
if (!hasHydratedViewRef.current) {
hasHydratedViewRef.current = true;
@@ -247,6 +313,10 @@ export function SdkSectionPage({
return getLessDetailedView(currentView, initialView);
});
+ // initialValueOverrides is intentionally tracked via
+ // overridesSignature on initialValues; including the object ref
+ // here would re-fire the effect every render.
+ // eslint-disable-next-line react-hooks/exhaustive-deps
}, [initialValues, initialView]);
const visibleSections = React.useMemo(() => {
@@ -275,6 +345,14 @@ export function SdkSectionPage({
[t],
);
+ // Stable save callback so `onSaveControlChange` can hand a single
+ // function reference to the parent across renders. The latest
+ // closure is kept up to date via `handleSaveRef`.
+ const handleSaveRef = React.useRef<() => void>(() => {});
+ const stableSave = React.useCallback(() => {
+ handleSaveRef.current();
+ }, []);
+
const handleSave = () => {
if (!filteredSchema || isReadOnly) return;
@@ -314,6 +392,25 @@ export function SdkSectionPage({
});
};
+ handleSaveRef.current = handleSave;
+
+ // Surface save state to the parent. Hooks must run before any
+ // conditional early-returns below, so this lives here rather than
+ // alongside the JSX. The dependency list deliberately excludes
+ // `stableSave` (it never changes) and `onSaveControlChange` (we
+ // tolerate ref-instability of the callback to avoid spamming the
+ // parent on every render).
+ const saveControlIsDirty = Object.keys(dirty).length > 0 || extraDirty;
+ React.useEffect(() => {
+ if (!onSaveControlChange) return;
+ onSaveControlChange({
+ save: stableSave,
+ isSaving: isPending,
+ isDirty: saveControlIsDirty,
+ });
+ // eslint-disable-next-line react-hooks/exhaustive-deps
+ }, [isPending, saveControlIsDirty]);
+
if (isLoading || isFetching || isSchemaLoading) {
return <LlmSettingsInputsSkeleton />;
}
@@ -338,7 +435,16 @@ export function SdkSectionPage({
isDisabled={isReadOnly}
/>
- <div className="flex flex-col gap-8 pb-20">
+ {/* `pb-20` reserves space for the sticky Save button. When the
+ button is hidden (or rendered inline via `embedded`) that
+ padding becomes a meaningless gap, so collapse it. */}
+ <div
+ className={
+ embedded || hideSaveButton
+ ? "flex flex-col gap-8"
+ : "flex flex-col gap-8 pb-20"
+ }
+ >
{header?.({
values,
isDisabled: isReadOnly,
@@ -365,8 +471,8 @@ export function SdkSectionPage({
))}
</div>
- {!isReadOnly ? (
- <div className="sticky bottom-0 bg-base py-4">
+ {!isReadOnly && !hideSaveButton ? (
+ <div className={embedded ? "pt-2" : "sticky bottom-0 bg-base py-4"}>
<BrandButton
testId="save-button"
type="button"
diff --git a/src/i18n/translation.json b/src/i18n/translation.json
index 41e46509fd..1fe23a8d6c 100644
--- a/src/i18n/translation.json
+++ b/src/i18n/translation.json
@@ -22834,5 +22834,89 @@
"de": "Aktionen einklappen",
"uk": "Згорнути дії",
"ca": "Replega les accions"
+ },
+ "ONBOARDING$TITLE": {
+ "en": "Welcome to OpenHands"
+ },
+ "ONBOARDING$STEP_LABEL": {
+ "en": "Step {{current}} of {{total}}"
+ },
+ "ONBOARDING$NEXT": {
+ "en": "Next"
+ },
+ "ONBOARDING$BACK": {
+ "en": "Back"
+ },
+ "ONBOARDING$SKIP": {
+ "en": "Skip for now"
+ },
+ "ONBOARDING$AGENT_TITLE": {
+ "en": "Choose your agent"
+ },
+ "ONBOARDING$AGENT_SUBTITLE": {
+ "en": "Pick the agent that will drive your conversations. You can change this later."
+ },
+ "ONBOARDING$AGENT_OPENHANDS_DESCRIPTION": {
+ "en": "The default OpenHands agent. Best for general-purpose coding and exploration."
+ },
+ "ONBOARDING$AGENT_CLAUDE_CODE_DESCRIPTION": {
+ "en": "Anthropic's Claude Code agent."
+ },
+ "ONBOARDING$AGENT_CODEX_DESCRIPTION": {
+ "en": "OpenAI's Codex agent."
+ },
+ "ONBOARDING$AGENT_COMING_SOON": {
+ "en": "Support for other agents coming soon!"
+ },
+ "ONBOARDING$BACKEND_TITLE": {
+ "en": "Check your backend"
+ },
+ "ONBOARDING$BACKEND_SUBTITLE": {
+ "en": "OpenHands talks to an agent server. Make sure the default backend is reachable."
+ },
+ "ONBOARDING$BACKEND_CONNECTED_TITLE": {
+ "en": "You're connected! 🎉"
+ },
+ "ONBOARDING$BACKEND_CONNECTED_BODY": {
+ "en": "Your agent server is up and running. Let's keep going."
+ },
+ "ONBOARDING$BACKEND_CHECKING": {
+ "en": "Checking your backend connection…"
+ },
+ "ONBOARDING$BACKEND_DISCONNECTED_TITLE": {
+ "en": "We can't reach your backend"
+ },
+ "ONBOARDING$BACKEND_DISCONNECTED_BODY": {
+ "en": "Update the connection details below and save to retry."
+ },
+ "ONBOARDING$BACKEND_STATUS_CONNECTED": {
+ "en": "Connected"
+ },
+ "ONBOARDING$BACKEND_STATUS_DISCONNECTED": {
+ "en": "Disconnected"
+ },
+ "ONBOARDING$BACKEND_STATUS_CHECKING": {
+ "en": "Checking…"
+ },
+ "ONBOARDING$LLM_TITLE": {
+ "en": "Set up your LLM"
+ },
+ "ONBOARDING$LLM_SUBTITLE": {
+ "en": "Pick a provider and model. We've pre-selected Anthropic Claude Opus."
+ },
+ "ONBOARDING$HELLO_TITLE": {
+ "en": "Say hello 👋"
+ },
+ "ONBOARDING$HELLO_SUBTITLE": {
+ "en": "Send your first message to OpenHands. We'll start a fresh conversation with no workspace."
+ },
+ "ONBOARDING$HELLO_DEFAULT_MESSAGE": {
+ "en": "hello OpenHands!"
+ },
+ "ONBOARDING$HELLO_LAUNCH": {
+ "en": "Send"
+ },
+ "ONBOARDING$HELLO_LAUNCHING": {
+ "en": "Starting conversation…"
}
}
diff --git a/src/routes/home.tsx b/src/routes/home.tsx
index 0d45345e8a..41d611dc55 100644
--- a/src/routes/home.tsx
+++ b/src/routes/home.tsx
@@ -4,6 +4,7 @@ import { RepoConnector } from "#/components/features/home/repo-connector";
import { TaskSuggestions } from "#/components/features/home/tasks/task-suggestions";
import { NewConversation } from "#/components/features/home/new-conversation/new-conversation";
import { RecentConversations } from "#/components/features/home/recent-conversations/recent-conversations";
+import { OnboardingHost } from "#/components/features/onboarding";
<PrefetchPageLinks page="/conversations/:conversationId" />;
@@ -34,6 +35,8 @@ function HomeScreen() {
<TaskSuggestions />
</div>
</div>
+
+ <OnboardingHost />
</div>
);
}
diff --git a/src/routes/llm-settings.tsx b/src/routes/llm-settings.tsx
index 0f0f039106..4adade7fd2 100644
--- a/src/routes/llm-settings.tsx
+++ b/src/routes/llm-settings.tsx
@@ -9,12 +9,14 @@ import { KeyStatusIcon } from "#/components/features/settings/key-status-icon";
import {
SdkSectionHeaderProps,
SdkSectionPage,
+ SdkSectionSaveControl,
} from "#/components/features/settings/sdk-settings/sdk-section-page";
import { I18nKey } from "#/i18n/declaration";
import { Settings, SettingsSchema, SettingsScope } from "#/types/settings";
import { extractModelAndProvider } from "#/utils/extract-model-and-provider";
import {
inferInitialView,
+ type SettingsFormValues,
type SettingsView,
} from "#/utils/sdk-settings-schema";
import { DEFAULT_SETTINGS } from "#/services/settings";
@@ -92,8 +94,23 @@ function OpenHandsApiKeyHelp({ testId }: OpenHandsApiKeyHelpProps) {
export function LlmSettingsScreen({
scope = "personal",
+ onSaveSuccess,
+ initialValueOverrides,
+ embedded,
+ hideSaveButton,
+ onSaveControlChange,
}: {
scope?: SettingsScope;
+ /** Optional hook fired after a successful save (e.g. advance an onboarding step). */
+ onSaveSuccess?: () => void;
+ /** Forwarded to {@link SdkSectionPage}. */
+ initialValueOverrides?: SettingsFormValues;
+ /** Forwarded to {@link SdkSectionPage}. */
+ embedded?: boolean;
+ /** Forwarded to {@link SdkSectionPage}. */
+ hideSaveButton?: boolean;
+ /** Forwarded to {@link SdkSectionPage}. */
+ onSaveControlChange?: (control: SdkSectionSaveControl) => void;
}) {
const { t } = useTranslation("openhands");
@@ -274,6 +291,11 @@ export function LlmSettingsScreen({
getInitialView={getInitialView}
forceShowAdvancedView
allowAllView
+ onSaveSuccess={onSaveSuccess}
+ initialValueOverrides={initialValueOverrides}
+ embedded={embedded}
+ hideSaveButton={hideSaveButton}
+ onSaveControlChange={onSaveControlChange}
testId="llm-settings-screen"
/>
);