Skip to content

🙌 OpenHands: AI-Driven Development

feat(onboarding): show the Super Admin setup guide on enterprise backends (#17969)

Hiep Lefd093cd554ac
diff --git a/__tests__/components/features/setup-guide/super-admin-setup-guide.test.tsx b/__tests__/components/features/setup-guide/super-admin-setup-guide.test.tsx
new file mode 100644
index 0000000000..7176dc3c90
--- /dev/null
+++ b/__tests__/components/features/setup-guide/super-admin-setup-guide.test.tsx
@@ -0,0 +1,342 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { render, screen, waitFor } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import { http, HttpResponse } from "msw";
+import {
+ __resetActiveStoreForTests,
+ setActiveSelection,
+ setRegisteredBackends,
+} from "#/api/backend-registry/active-store";
+import type { Backend } from "#/api/backend-registry/types";
+import type { CloudSetupGuideSteps } from "#/api/cloud/types";
+import SuperAdminSetupGuide from "#/components/features/setup-guide/super-admin-setup-guide";
+import { NavigationProvider } from "#/context/navigation-context";
+import { ActiveBackendProvider } from "#/contexts/active-backend-context";
+import { I18nKey } from "#/i18n/declaration";
+import { server } from "#/mocks/node";
+
+const CLOUD_HOST = "https://ohe.example.com";
+const GUIDE_ORG_ID = "org-1";
+
+const cloudBackend: Backend = {
+ id: "cloud-1",
+ name: "OHE",
+ host: CLOUD_HOST,
+ apiKey: "",
+ kind: "cloud",
+};
+
+const localBackend: Backend = {
+ id: "local-1",
+ name: "Local",
+ host: "http://localhost:8000",
+ apiKey: "local-key",
+ kind: "local",
+};
+
+function guideState(steps: Partial<CloudSetupGuideSteps> = {}) {
+ return {
+ wizard_pending: false,
+ guide_org_id: GUIDE_ORG_ID,
+ guide_dismissed: false,
+ guide_steps: {
+ org_llm: false,
+ mcp_server: false,
+ automation: false,
+ invite: false,
+ ...steps,
+ },
+ };
+}
+
+/**
+ * Serves `/me` and the setup state for the cloud host and counts the
+ * requests, so cases can assert who asks the server for a guide.
+ */
+function serveSetupGuide({
+ permissions = ["manage_super_admins"],
+ setupState = () => HttpResponse.json(guideState()),
+}: {
+ permissions?: string[];
+ setupState?: () => Response;
+} = {}) {
+ const requests = { me: 0, setupState: 0 };
+ server.use(
+ http.get("*/api/organizations/:orgId/me", ({ params }) => {
+ requests.me += 1;
+ return HttpResponse.json({
+ org_id: params.orgId,
+ user_id: "user-1",
+ role: "owner",
+ permissions,
+ });
+ }),
+ http.get("*/api/admin/setup-state", () => {
+ requests.setupState += 1;
+ return setupState();
+ }),
+ );
+ return requests;
+}
+
+function activateBackend(backend: Backend) {
+ setRegisteredBackends([backend]);
+ setActiveSelection({ backendId: backend.id, orgId: GUIDE_ORG_ID });
+}
+
+function renderGuide(currentPath = "/conversations") {
+ const queryClient = new QueryClient({
+ defaultOptions: { queries: { retry: false } },
+ });
+ const ui = (path: string) => (
+ <QueryClientProvider client={queryClient}>
+ <ActiveBackendProvider>
+ <NavigationProvider
+ value={{
+ currentPath: path,
+ conversationId: null,
+ isNavigating: false,
+ navigate: vi.fn(),
+ }}
+ >
+ <SuperAdminSetupGuide />
+ </NavigationProvider>
+ </ActiveBackendProvider>
+ </QueryClientProvider>
+ );
+ const view = render(ui(currentPath));
+ return { navigateTo: (path: string) => view.rerender(ui(path)) };
+}
+
+async function expectNoGuide() {
+ await expect(
+ screen.findByTestId("super-admin-setup-guide", undefined, {
+ timeout: 200,
+ }),
+ ).rejects.toThrow();
+}
+
+describe("SuperAdminSetupGuide", () => {
+ beforeEach(() => {
+ localStorage.clear();
+ __resetActiveStoreForTests();
+ });
+
+ afterEach(() => {
+ __resetActiveStoreForTests();
+ });
+
+ it("shows the first Super Admin the progress the server reports", async () => {
+ activateBackend(cloudBackend);
+ serveSetupGuide({
+ setupState: () => HttpResponse.json(guideState({ org_llm: true })),
+ });
+
+ renderGuide();
+
+ expect(
+ await screen.findByTestId("super-admin-setup-guide-panel"),
+ ).toBeInTheDocument();
+ expect(screen.getByText("1/4")).toBeInTheDocument();
+ expect(screen.getByRole("progressbar")).toHaveAttribute(
+ "aria-valuenow",
+ "25",
+ );
+ });
+
+ it("links each step to the page where it is done", async () => {
+ activateBackend(cloudBackend);
+ serveSetupGuide();
+
+ renderGuide();
+
+ await screen.findByTestId("super-admin-setup-guide-panel");
+ expect(
+ screen.getByTestId("super-admin-setup-guide-step-add-llm"),
+ ).toHaveAttribute(
+ "href",
+ `${CLOUD_HOST}/settings/org-defaults?org=${GUIDE_ORG_ID}`,
+ );
+ expect(
+ screen.getByTestId("super-admin-setup-guide-step-add-integration"),
+ ).toHaveAttribute("href", "/mcp");
+ expect(
+ screen.getByTestId("super-admin-setup-guide-step-invite-users"),
+ ).toHaveAttribute(
+ "href",
+ `${CLOUD_HOST}/settings/org-members?org=${GUIDE_ORG_ID}`,
+ );
+ expect(
+ screen.getByTestId("super-admin-setup-guide-step-optional-saml"),
+ ).toHaveAttribute("href", `${CLOUD_HOST}/super-admin/instance`);
+ expect(
+ screen.getByTestId("super-admin-setup-guide-step-first-automation"),
+ ).toHaveAttribute("href", "/automations/templates");
+ expect(screen.getByTestId("super-admin-setup-guide-page")).toHaveAttribute(
+ "href",
+ `${CLOUD_HOST}/super-admin/setup`,
+ );
+ });
+
+ it("opens the next step from Start", async () => {
+ activateBackend(cloudBackend);
+ serveSetupGuide({
+ setupState: () => HttpResponse.json(guideState({ org_llm: true })),
+ });
+
+ renderGuide();
+
+ expect(
+ await screen.findByTestId("super-admin-setup-guide-start"),
+ ).toHaveAttribute("href", "/automations/templates");
+ });
+
+ it("opens the Canvas MCP page from Start for the integration step", async () => {
+ activateBackend(cloudBackend);
+ serveSetupGuide({
+ setupState: () =>
+ HttpResponse.json(guideState({ org_llm: true, automation: true })),
+ });
+
+ renderGuide();
+
+ expect(
+ await screen.findByTestId("super-admin-setup-guide-start"),
+ ).toHaveAttribute("href", "/mcp");
+ });
+
+ it("opens an enterprise step from Start on the guide's organization", async () => {
+ activateBackend(cloudBackend);
+ serveSetupGuide({
+ setupState: () =>
+ HttpResponse.json(
+ guideState({ org_llm: true, automation: true, mcp_server: true }),
+ ),
+ });
+
+ renderGuide();
+
+ expect(
+ await screen.findByTestId("super-admin-setup-guide-start"),
+ ).toHaveAttribute(
+ "href",
+ `${CLOUD_HOST}/settings/org-members?org=${GUIDE_ORG_ID}`,
+ );
+ });
+
+ it("closes the panel from Start, even on the next step's own page", async () => {
+ activateBackend(cloudBackend);
+ serveSetupGuide({
+ setupState: () => HttpResponse.json(guideState({ org_llm: true })),
+ });
+ const user = userEvent.setup();
+ renderGuide("/automations/templates");
+
+ await user.click(
+ await screen.findByTestId("super-admin-setup-guide-start"),
+ );
+
+ expect(
+ screen.queryByTestId("super-admin-setup-guide-panel"),
+ ).not.toBeInTheDocument();
+ expect(
+ screen.getByTestId("super-admin-setup-guide-toggle"),
+ ).toHaveAttribute("aria-expanded", "false");
+ });
+
+ it("re-reads progress when the admin moves to another page", async () => {
+ activateBackend(cloudBackend);
+ let state = guideState({ org_llm: true });
+ serveSetupGuide({ setupState: () => HttpResponse.json(state) });
+ const { navigateTo } = renderGuide("/automations/templates");
+ expect(await screen.findByText("1/4")).toBeInTheDocument();
+
+ state = guideState({ org_llm: true, automation: true });
+ navigateTo("/automations/automation-1");
+
+ expect(await screen.findByText("2/4")).toBeInTheDocument();
+ });
+
+ it("closes to the pill and opens again from it", async () => {
+ const user = userEvent.setup();
+ activateBackend(cloudBackend);
+ serveSetupGuide();
+ renderGuide();
+ await screen.findByTestId("super-admin-setup-guide-panel");
+
+ await user.click(
+ screen.getByRole("button", { name: I18nKey.BUTTON$CLOSE }),
+ );
+ expect(
+ screen.queryByTestId("super-admin-setup-guide-panel"),
+ ).not.toBeInTheDocument();
+
+ await user.click(screen.getByTestId("super-admin-setup-guide-toggle"));
+ expect(
+ screen.getByTestId("super-admin-setup-guide-panel"),
+ ).toBeInTheDocument();
+ });
+
+ it("does not ask for the setup state for a user who is not a Super Admin", async () => {
+ activateBackend(cloudBackend);
+ const requests = serveSetupGuide({ permissions: ["view_automations"] });
+
+ renderGuide();
+
+ await waitFor(() => expect(requests.me).toBe(1));
+ await expectNoGuide();
+ expect(requests.setupState).toBe(0);
+ });
+
+ it.each([
+ [
+ "the caller is not the first Super Admin",
+ () =>
+ HttpResponse.json({
+ wizard_pending: false,
+ guide_org_id: null,
+ guide_dismissed: false,
+ guide_steps: null,
+ }),
+ ],
+ [
+ "the guide was dismissed",
+ () => HttpResponse.json({ ...guideState(), guide_dismissed: true }),
+ ],
+ [
+ "every step is done",
+ () =>
+ HttpResponse.json(
+ guideState({
+ org_llm: true,
+ mcp_server: true,
+ automation: true,
+ invite: true,
+ }),
+ ),
+ ],
+ [
+ "the server has the Super Admin feature off and serves its web page",
+ () => HttpResponse.html("<!doctype html><html></html>"),
+ ],
+ ])("shows nothing when %s", async (_case, setupState) => {
+ activateBackend(cloudBackend);
+ const requests = serveSetupGuide({ setupState });
+
+ renderGuide();
+
+ await waitFor(() => expect(requests.setupState).toBeGreaterThan(0));
+ await expectNoGuide();
+ });
+
+ it("never asks a local backend for a guide", async () => {
+ activateBackend(localBackend);
+ const requests = serveSetupGuide();
+
+ renderGuide();
+
+ await expectNoGuide();
+ expect(requests).toEqual({ me: 0, setupState: 0 });
+ });
+});
diff --git a/__tests__/components/features/sidebar/sidebar-onboarding-checklist.test.tsx b/__tests__/components/features/sidebar/sidebar-onboarding-checklist.test.tsx
index 46e3eadade..94db61b10d 100644
--- a/__tests__/components/features/sidebar/sidebar-onboarding-checklist.test.tsx
+++ b/__tests__/components/features/sidebar/sidebar-onboarding-checklist.test.tsx
@@ -10,6 +10,15 @@ import {
import { render, screen } from "@testing-library/react";
import userEvent from "@testing-library/user-event";
import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import { http, HttpResponse } from "msw";
+import {
+ __resetActiveStoreForTests,
+ setActiveSelection,
+ setRegisteredBackends,
+} from "#/api/backend-registry/active-store";
+import SuperAdminSetupGuide from "#/components/features/setup-guide/super-admin-setup-guide";
+import { ActiveBackendProvider } from "#/contexts/active-backend-context";
+import { server } from "#/mocks/node";
import { ONBOARDING_COMPLETED_STORAGE_KEY } from "#/components/features/onboarding/use-onboarding-completion";
import { SidebarOnboardingChecklist } from "#/components/features/sidebar/sidebar-onboarding-checklist";
import {
@@ -402,4 +411,99 @@ describe("SidebarOnboardingChecklist", () => {
});
});
});
+
+ describe("with the Super Admin setup guide", () => {
+ function serveCloudUser(permissions: string[]) {
+ server.use(
+ http.get("*/api/organizations/:orgId/me", ({ params }) =>
+ HttpResponse.json({
+ org_id: params.orgId,
+ user_id: "user-1",
+ role: "owner",
+ permissions,
+ }),
+ ),
+ http.get("*/api/admin/setup-state", () =>
+ HttpResponse.json({
+ wizard_pending: false,
+ guide_org_id: "org-1",
+ guide_dismissed: false,
+ guide_steps: {
+ org_llm: false,
+ mcp_server: false,
+ automation: false,
+ invite: false,
+ },
+ }),
+ ),
+ );
+ }
+
+ function renderOnCloud() {
+ const navigation: NavigationContextValue = {
+ currentPath: "/",
+ conversationId: null,
+ isNavigating: false,
+ navigate: vi.fn(),
+ };
+ render(
+ <QueryClientProvider
+ client={
+ new QueryClient({ defaultOptions: { queries: { retry: false } } })
+ }
+ >
+ <ActiveBackendProvider>
+ <NavigationProvider value={navigation}>
+ <SidebarOnboardingChecklist collapsed={false} />
+ <SuperAdminSetupGuide />
+ </NavigationProvider>
+ </ActiveBackendProvider>
+ </QueryClientProvider>,
+ );
+ }
+
+ beforeEach(() => {
+ __resetActiveStoreForTests();
+ setRegisteredBackends([
+ {
+ id: "cloud-1",
+ name: "OHE",
+ host: "https://ohe.example.com",
+ apiKey: "",
+ kind: "cloud",
+ },
+ ]);
+ setActiveSelection({ backendId: "cloud-1", orgId: "org-1" });
+ });
+
+ afterEach(() => {
+ __resetActiveStoreForTests();
+ });
+
+ it("steps aside while the setup guide is shown", async () => {
+ serveCloudUser(["manage_super_admins"]);
+
+ renderOnCloud();
+
+ expect(
+ await screen.findByTestId("super-admin-setup-guide"),
+ ).toBeInTheDocument();
+ expect(
+ screen.queryByTestId("sidebar-onboarding-checklist"),
+ ).not.toBeInTheDocument();
+ });
+
+ it("stays for cloud users who have no setup guide", async () => {
+ serveCloudUser(["view_automations"]);
+
+ renderOnCloud();
+
+ expect(
+ await screen.findByTestId("sidebar-onboarding-checklist"),
+ ).toBeInTheDocument();
+ expect(
+ screen.queryByTestId("super-admin-setup-guide"),
+ ).not.toBeInTheDocument();
+ });
+ });
});
diff --git a/__tests__/hooks/mutation/use-add-mcp-server.test.ts b/__tests__/hooks/mutation/use-add-mcp-server.test.ts
index 2b81b1e62c..7a4f727e97 100644
--- a/__tests__/hooks/mutation/use-add-mcp-server.test.ts
+++ b/__tests__/hooks/mutation/use-add-mcp-server.test.ts
@@ -4,6 +4,7 @@ import { renderHook } from "@testing-library/react";
import { beforeEach, describe, expect, it, vi } from "vitest";
import SettingsService from "#/api/settings-service/settings-service.api";
import { useAddMcpServer } from "#/hooks/mutation/use-add-mcp-server";
+import { SUPER_ADMIN_SETUP_QUERY_KEYS } from "#/hooks/query/query-keys";
const useSettingsMock = vi.fn();
vi.mock("#/hooks/query/use-settings", () => ({
@@ -87,6 +88,31 @@ describe("useAddMcpServer", () => {
});
});
+ it("marks the Super Admin setup guide's progress stale after adding a server", async () => {
+ vi.spyOn(SettingsService, "createMcpServer").mockResolvedValue(true);
+ const client = new QueryClient({
+ defaultOptions: {
+ queries: { retry: false },
+ mutations: { retry: false },
+ },
+ });
+ const setupStateKey = SUPER_ADMIN_SETUP_QUERY_KEYS.state("cloud-1", 0);
+ client.setQueryData(setupStateKey, { guide_steps: { mcp_server: false } });
+ const { result } = renderHook(() => useAddMcpServer(), {
+ wrapper: ({ children }: { children: React.ReactNode }) =>
+ React.createElement(QueryClientProvider, { client }, children),
+ });
+
+ await result.current.mutateAsync({
+ id: "",
+ type: "shttp",
+ name: "docs",
+ url: "https://docs.example/mcp",
+ });
+
+ expect(client.getQueryState(setupStateKey)?.isInvalidated).toBe(true);
+ });
+
it("fails instead of reporting a successful install before settings load", async () => {
useSettingsMock.mockReturnValue({ data: undefined });
const createSpy = vi.spyOn(SettingsService, "createMcpServer");
diff --git a/src/api/cloud/setup-state-service.api.ts b/src/api/cloud/setup-state-service.api.ts
new file mode 100644
index 0000000000..77af470691
--- /dev/null
+++ b/src/api/cloud/setup-state-service.api.ts
@@ -0,0 +1,27 @@
+import type { Backend } from "../backend-registry/types";
+import { callCloudProxy } from "./proxy";
+import type { CloudSetupState } from "./types";
+
+/**
+ * Fetch `GET /api/admin/setup-state`: the Super Admin setup guide's
+ * organization, dismissal and server-derived step progress.
+ *
+ * Enterprise backends only mount the route while the Super Admin feature is
+ * on; otherwise the path falls through to the web app and the response is
+ * not JSON. Anything that is not an object is treated as "no guide".
+ */
+export async function getCloudSetupState(
+ backend: Backend,
+): Promise<CloudSetupState> {
+ const data = await callCloudProxy<Partial<CloudSetupState> | string>({
+ backend,
+ method: "GET",
+ path: "/api/admin/setup-state",
+ });
+ const state = typeof data === "object" && data !== null ? data : {};
+ return {
+ guide_org_id: state.guide_org_id ?? null,
+ guide_dismissed: state.guide_dismissed ?? false,
+ guide_steps: state.guide_steps ?? null,
+ };
+}
diff --git a/src/api/cloud/types.ts b/src/api/cloud/types.ts
index 270e5ec73b..808b7ba575 100644
--- a/src/api/cloud/types.ts
+++ b/src/api/cloud/types.ts
@@ -61,3 +61,25 @@ export interface CloudGitUser {
name: string | null;
email: string | null;
}
+
+/**
+ * Server-derived Super Admin setup-guide steps, from
+ * `GET /api/admin/setup-state` on an OpenHands Enterprise backend.
+ */
+export interface CloudSetupGuideSteps {
+ org_llm: boolean;
+ mcp_server: boolean;
+ automation: boolean;
+ invite: boolean;
+}
+
+/**
+ * Subset of the enterprise setup-state the GUI reads. `guide_steps` is
+ * non-null only for the first Super Admin while the guide has an
+ * organization and has not been dismissed.
+ */
+export interface CloudSetupState {
+ guide_org_id: string | null;
+ guide_dismissed: boolean;
+ guide_steps: CloudSetupGuideSteps | null;
+}
diff --git a/src/components/features/setup-guide/super-admin-setup-guide.constants.ts b/src/components/features/setup-guide/super-admin-setup-guide.constants.ts
new file mode 100644
index 0000000000..13b1b938e0
--- /dev/null
+++ b/src/components/features/setup-guide/super-admin-setup-guide.constants.ts
@@ -0,0 +1,90 @@
+import type { CloudSetupGuideSteps } from "#/api/cloud/types";
+import { I18nKey } from "#/i18n/declaration";
+import { automationTemplatesPath } from "#/manifests/automation-interface";
+
+/** Server permission held by instance Super Admins (`/me` `permissions`). */
+export const MANAGE_SUPER_ADMINS_PERMISSION = "manage_super_admins";
+
+/** The enterprise setup guide page, on the cloud host. */
+export const SUPER_ADMIN_SETUP_GUIDE_PAGE_PATH = "/super-admin/setup";
+
+export type SuperAdminSetupStepId =
+ | "add-llm"
+ | "add-integration"
+ | "first-automation"
+ | "invite-users"
+ | "optional-saml";
+
+/**
+ * What marks a step done: a server-derived flag from `guide_steps`, or
+ * "optional" for a link that never counts toward progress.
+ */
+export type SuperAdminSetupStepCompletion =
+ | keyof CloudSetupGuideSteps
+ | "optional";
+
+/**
+ * Where a step opens: a page on the cloud host (`withOrg` adds the guide's
+ * organization so enterprise settings open on it) or a Canvas route.
+ */
+export type SuperAdminSetupStepDestination =
+ | { kind: "cloud"; path: string; withOrg: boolean }
+ | { kind: "canvas"; path: string };
+
+export interface SuperAdminSetupStep {
+ id: SuperAdminSetupStepId;
+ labelKey: I18nKey;
+ completion: SuperAdminSetupStepCompletion;
+ destination: SuperAdminSetupStepDestination;
+}
+
+/**
+ * Mirrors the enterprise guide's steps and order so both apps show the same
+ * progress. Steps that Canvas can do itself (automation templates, MCP
+ * servers) open in Canvas; the rest open the enterprise app.
+ */
+export const SUPER_ADMIN_SETUP_STEPS: readonly SuperAdminSetupStep[] = [
+ {
+ id: "add-llm",
+ labelKey: I18nKey.ONBOARDING$SETUP_GUIDE_STEP_LLM,
+ completion: "org_llm",
+ destination: {
+ kind: "cloud",
+ path: "/settings/org-defaults",
+ withOrg: true,
+ },
+ },
+ {
+ id: "first-automation",
+ labelKey: I18nKey.ONBOARDING$SETUP_GUIDE_STEP_AUTOMATION,
+ completion: "automation",
+ destination: { kind: "canvas", path: automationTemplatesPath() },
+ },
+ {
+ id: "add-integration",
+ labelKey: I18nKey.ONBOARDING$SETUP_GUIDE_STEP_INTEGRATION,
+ completion: "mcp_server",
+ // Canvas's MCP page saves to the same cloud settings the step checks.
+ destination: { kind: "canvas", path: "/mcp" },
+ },
+ {
+ id: "invite-users",
+ labelKey: I18nKey.ONBOARDING$SETUP_GUIDE_STEP_INVITE,
+ completion: "invite",
+ destination: {
+ kind: "cloud",
+ path: "/settings/org-members",
+ withOrg: true,
+ },
+ },
+ {
+ id: "optional-saml",
+ labelKey: I18nKey.ONBOARDING$SETUP_GUIDE_STEP_SAML,
+ completion: "optional",
+ destination: {
+ kind: "cloud",
+ path: "/super-admin/instance",
+ withOrg: false,
+ },
+ },
+];
diff --git a/src/components/features/setup-guide/super-admin-setup-guide.tsx b/src/components/features/setup-guide/super-admin-setup-guide.tsx
new file mode 100644
index 0000000000..ae77663994
--- /dev/null
+++ b/src/components/features/setup-guide/super-admin-setup-guide.tsx
@@ -0,0 +1,249 @@
+import { type ReactNode, useEffect, useState } from "react";
+import { useTranslation } from "react-i18next";
+import { ArrowUpRight, Check, ClipboardList, X } from "lucide-react";
+import { getLockedCloudHost } from "#/api/agent-server-config";
+import { NavigationLink } from "#/components/shared/navigation-link";
+import { useNavigation } from "#/context/navigation-context";
+import { useActiveBackend } from "#/contexts/active-backend-context";
+import { I18nKey } from "#/i18n/declaration";
+import { formControlButtonClassName } from "#/utils/form-control-classes";
+import { cn } from "#/utils/utils";
+import {
+ SUPER_ADMIN_SETUP_GUIDE_PAGE_PATH,
+ type SuperAdminSetupStep,
+} from "./super-admin-setup-guide.constants";
+import { useSuperAdminSetupGuide } from "./use-super-admin-setup-guide";
+
+const ICON_BUTTON_CLASS = cn(
+ "inline-flex size-7 shrink-0 items-center justify-center rounded-md",
+ "text-muted hover:bg-surface hover:text-contrast",
+);
+
+const STEP_ROW_CLASS =
+ "flex w-full min-w-0 items-center gap-2.5 rounded-md px-2.5 py-1.5 hover:bg-surface";
+
+// The enterprise guide's primary button: light on dark. Canvas's `primary`
+// is its gold accent, so this uses `foreground` like the enterprise app.
+const START_BUTTON_CLASS = cn(
+ formControlButtonClassName,
+ "w-full bg-foreground font-medium text-on-primary hover:opacity-80",
+);
+
+const START_TEST_ID = "super-admin-setup-guide-start";
+
+/**
+ * Floating lower-right setup guide for the enterprise Super Admin, matching
+ * the guide in the OpenHands Enterprise app. Steps that live in the
+ * enterprise app link back to it; progress is read from the server.
+ */
+export default function SuperAdminSetupGuide() {
+ const { t } = useTranslation("openhands");
+ const { currentPath } = useNavigation();
+ const { backend } = useActiveBackend();
+ const {
+ steps,
+ completedCount,
+ totalCount,
+ nextStep,
+ guideOrgId,
+ visible,
+ refetch,
+ } = useSuperAdminSetupGuide();
+ const [open, setOpen] = useState(true);
+
+ // Progress is read from the server, so re-read it as the admin moves around.
+ useEffect(() => {
+ if (visible) {
+ refetch();
+ }
+ }, [currentPath, visible, refetch]);
+
+ if (!visible) {
+ return null;
+ }
+
+ const cloudHost = backend.host.replace(/\/+$/, "");
+ // Locked-to-Cloud serves the canvas on the cloud host itself, so enterprise
+ // pages open in this tab; standalone / Electron keep a new tab.
+ const isLockedToCloud = getLockedCloudHost() !== null;
+ const cloudLinkProps = {
+ target: isLockedToCloud ? undefined : "_blank",
+ rel: isLockedToCloud ? undefined : "noopener noreferrer",
+ };
+ const cloudUrl = (path: string, withOrg: boolean) =>
+ withOrg && guideOrgId
+ ? `${cloudHost}${path}?org=${encodeURIComponent(guideOrgId)}`
+ : `${cloudHost}${path}`;
+ // A step row and Start open the same page for a step.
+ const renderStepLink = (
+ step: SuperAdminSetupStep,
+ testId: string,
+ className: string,
+ children: ReactNode,
+ onClick?: () => void,
+ ) =>
+ step.destination.kind === "canvas" ? (
+ <NavigationLink
+ to={step.destination.path}
+ data-testid={testId}
+ className={className}
+ onClick={onClick}
+ >
+ {children}
+ </NavigationLink>
+ ) : (
+ <a
+ href={cloudUrl(step.destination.path, step.destination.withOrg)}
+ {...cloudLinkProps}
+ data-testid={testId}
+ className={className}
+ onClick={onClick}
+ >
+ {children}
+ </a>
+ );
+
+ const title = t(I18nKey.ONBOARDING$SETUP_GUIDE_TITLE);
+ const progressPct = Math.round((completedCount / totalCount) * 100);
+
+ return (
+ <div
+ className="fixed bottom-5 right-5 z-30 flex flex-col items-end gap-2"
+ data-testid="super-admin-setup-guide"
+ >
+ {open ? (
+ <div
+ data-testid="super-admin-setup-guide-panel"
+ className={cn(
+ "flex w-80 flex-col gap-3 rounded-xl border border-border",
+ "bg-surface-raised p-4 shadow-lg",
+ )}
+ >
+ <div className="flex items-center justify-between gap-2">
+ <p className="min-w-0 text-sm font-semibold text-content">
+ {title}
+ </p>
+ <div className="flex shrink-0 items-center gap-0.5">
+ <a
+ href={cloudUrl(SUPER_ADMIN_SETUP_GUIDE_PAGE_PATH, false)}
+ {...cloudLinkProps}
+ data-testid="super-admin-setup-guide-page"
+ aria-label={title}
+ title={title}
+ className={ICON_BUTTON_CLASS}
+ >
+ <ArrowUpRight className="size-4" strokeWidth={2} aria-hidden />
+ </a>
+ <button
+ type="button"
+ aria-label={t(I18nKey.BUTTON$CLOSE)}
+ className={ICON_BUTTON_CLASS}
+ onClick={() => setOpen(false)}
+ >
+ <X className="size-4" strokeWidth={2} aria-hidden />
+ </button>
+ </div>
+ </div>
+
+ <div className="flex items-center gap-3">
+ <div
+ className="h-1.5 flex-1 overflow-hidden rounded-full bg-border"
+ role="progressbar"
+ aria-valuemin={0}
+ aria-valuemax={100}
+ aria-valuenow={progressPct}
+ aria-label={title}
+ >
+ <div
+ className="h-full rounded-full bg-foreground transition-all duration-300"
+ style={{ width: `${progressPct}%` }}
+ />
+ </div>
+ <span className="shrink-0 text-xs tabular-nums text-muted">
+ {completedCount}/{totalCount}
+ </span>
+ </div>
+
+ <ul className="flex flex-col gap-0.5">
+ {steps.map((step) => {
+ const label = (
+ <>
+ <span
+ aria-hidden
+ className={cn(
+ "inline-flex size-4 shrink-0 items-center justify-center rounded-full border",
+ step.done
+ ? "border-foreground bg-foreground text-on-primary"
+ : "border-border bg-transparent",
+ )}
+ >
+ {step.done ? (
+ <Check className="size-2.5" strokeWidth={3} />
+ ) : null}
+ </span>
+ <span
+ className={cn(
+ "min-w-0 flex-1 truncate text-xs",
+ step.done ? "text-muted line-through" : "text-content",
+ )}
+ >
+ {t(step.labelKey)}
+ </span>
+ </>
+ );
+ const testId = `super-admin-setup-guide-step-${step.id}`;
+ const rowClassName = cn(
+ STEP_ROW_CLASS,
+ nextStep?.id === step.id && "bg-surface",
+ );
+ return (
+ <li key={step.id}>
+ {renderStepLink(step, testId, rowClassName, label)}
+ </li>
+ );
+ })}
+ </ul>
+
+ {nextStep ? (
+ <div className="flex flex-col gap-2">
+ <p
+ className="text-xs text-muted"
+ data-testid="super-admin-setup-guide-next"
+ >
+ {t(I18nKey.ONBOARDING$SETUP_GUIDE_NEXT, {
+ step: t(nextStep.labelKey),
+ })}
+ </p>
+ {/* Like the enterprise Start, close the panel before opening
+ the step, so Start does something even when the admin is
+ already on that step's page. */}
+ {renderStepLink(
+ nextStep,
+ START_TEST_ID,
+ START_BUTTON_CLASS,
+ t(I18nKey.ONBOARDING$SETUP_GUIDE_START),
+ () => setOpen(false),
+ )}
+ </div>
+ ) : null}
+ </div>
+ ) : null}
+
+ <button
+ type="button"
+ data-testid="super-admin-setup-guide-toggle"
+ aria-label={title}
+ aria-expanded={open}
+ onClick={() => setOpen((current) => !current)}
+ className={cn(
+ "flex items-center gap-2 rounded-full border border-border",
+ "bg-surface-raised px-3.5 py-2 text-sm font-medium text-content",
+ "shadow-sm hover:bg-surface",
+ )}
+ >
+ <ClipboardList className="size-4" strokeWidth={2} aria-hidden />
+ {title}
+ </button>
+ </div>
+ );
+}
diff --git a/src/components/features/setup-guide/use-super-admin-setup-guide.ts b/src/components/features/setup-guide/use-super-admin-setup-guide.ts
new file mode 100644
index 0000000000..34f4877dde
--- /dev/null
+++ b/src/components/features/setup-guide/use-super-admin-setup-guide.ts
@@ -0,0 +1,101 @@
+import { useQuery } from "@tanstack/react-query";
+import { getCloudOrganizationMe } from "#/api/cloud/organization-service.api";
+import { getCloudSetupState } from "#/api/cloud/setup-state-service.api";
+import type { CloudSetupGuideSteps } from "#/api/cloud/types";
+import { useActiveBackend } from "#/contexts/active-backend-context";
+import {
+ CONFIG_CACHE_OPTIONS,
+ SUPER_ADMIN_SETUP_QUERY_KEYS,
+} from "#/hooks/query/query-keys";
+import {
+ MANAGE_SUPER_ADMINS_PERMISSION,
+ SUPER_ADMIN_SETUP_STEPS,
+ type SuperAdminSetupStep,
+} from "./super-admin-setup-guide.constants";
+
+export interface SuperAdminSetupStepState extends SuperAdminSetupStep {
+ done: boolean;
+}
+
+const REQUIRED_STEPS = SUPER_ADMIN_SETUP_STEPS.filter(
+ (step) => step.completion !== "optional",
+);
+
+function isStepDone(
+ step: SuperAdminSetupStep,
+ guideSteps: CloudSetupGuideSteps | null,
+): boolean {
+ if (!guideSteps || step.completion === "optional") {
+ return false;
+ }
+ return guideSteps[step.completion];
+}
+
+/**
+ * The enterprise Super Admin setup guide for the active cloud backend.
+ *
+ * Only instance Super Admins (per `/me` permissions) ask for the setup state,
+ * and the server returns a guide only to the first Super Admin while it has
+ * an organization and is not dismissed. Local backends never see it.
+ */
+export function useSuperAdminSetupGuide() {
+ const { backend, orgId } = useActiveBackend();
+ const isCloud = backend.kind === "cloud";
+
+ // Same query as `useAutomationPermissions`, so no extra request is issued.
+ // eslint-disable-next-line @tanstack/query/exhaustive-deps
+ const meQuery = useQuery({
+ queryKey: [
+ "cloud-current-user",
+ backend.id,
+ orgId,
+ backend.connectionRevision ?? 0,
+ ],
+ queryFn: () => getCloudOrganizationMe(orgId!, backend),
+ enabled: isCloud && !!orgId,
+ staleTime: 1000 * 60 * 5,
+ retry: false,
+ meta: { disableToast: true },
+ });
+ const isSuperAdmin =
+ meQuery.data?.permissions?.includes(MANAGE_SUPER_ADMINS_PERMISSION) ===
+ true;
+
+ // eslint-disable-next-line @tanstack/query/exhaustive-deps
+ const setupStateQuery = useQuery({
+ queryKey: SUPER_ADMIN_SETUP_QUERY_KEYS.state(
+ backend.id,
+ backend.connectionRevision ?? 0,
+ ),
+ queryFn: () => getCloudSetupState(backend),
+ enabled: isCloud && isSuperAdmin,
+ ...CONFIG_CACHE_OPTIONS,
+ retry: false,
+ meta: { disableToast: true },
+ });
+
+ const setupState = isSuperAdmin ? setupStateQuery.data : undefined;
+ const guideSteps = setupState?.guide_steps ?? null;
+ const steps: SuperAdminSetupStepState[] = SUPER_ADMIN_SETUP_STEPS.map(
+ (step) => ({ ...step, done: isStepDone(step, guideSteps) }),
+ );
+ const completedCount = REQUIRED_STEPS.filter((step) =>
+ isStepDone(step, guideSteps),
+ ).length;
+ const nextStep =
+ REQUIRED_STEPS.find((step) => !isStepDone(step, guideSteps)) ?? null;
+ const guideOrgId = setupState?.guide_org_id ?? null;
+ // Only the first Super Admin's guide has an organization; it stays until dismissed.
+ const active = Boolean(guideOrgId) && !setupState?.guide_dismissed;
+
+ return {
+ steps,
+ completedCount,
+ totalCount: REQUIRED_STEPS.length,
+ nextStep,
+ guideOrgId,
+ visible: active && nextStep !== null,
+ isLoading: meQuery.isLoading || setupStateQuery.isLoading,
+ refetch: setupStateQuery.refetch,
+ };
+}
diff --git a/src/components/features/sidebar/use-sidebar-onboarding-checklist.ts b/src/components/features/sidebar/use-sidebar-onboarding-checklist.ts
index 03376fca64..52b2111780 100644
--- a/src/components/features/sidebar/use-sidebar-onboarding-checklist.ts
+++ b/src/components/features/sidebar/use-sidebar-onboarding-checklist.ts
@@ -1,5 +1,6 @@
import { useEffect, useMemo, useState, useSyncExternalStore } from "react";
import { useOnboardingCompletion } from "#/components/features/onboarding/use-onboarding-completion";
+import { useSuperAdminSetupGuide } from "#/components/features/setup-guide/use-super-admin-setup-guide";
import { useNavigation } from "#/context/navigation-context";
import { useAutomations } from "#/hooks/query/use-automations";
import { useAutomationHealth } from "#/hooks/query/use-automation-health";
@@ -38,6 +39,7 @@ function hasConfiguredMcpServers(mcpConfig: unknown): boolean {
export function useSidebarOnboardingChecklist() {
const { isCompleted: onboardingCompleted } = useOnboardingCompletion();
+ const setupGuide = useSuperAdminSetupGuide();
const { currentPath } = useNavigation();
const isDismissed = useSyncExternalStore(
subscribeSidebarOnboardingChecklistDismissed,
@@ -133,7 +135,13 @@ export function useSidebarOnboardingChecklist() {
const completedCount = items.filter((item) => item.isComplete).length;
const isAllComplete = completedCount === items.length;
- const isVisible = onboardingCompleted && !isDismissed && !isAllComplete;
+ // The Super Admin setup guide replaces this checklist while it is shown.
+ const isVisible =
+ onboardingCompleted &&
+ !isDismissed &&
+ !isAllComplete &&
+ !setupGuide.isLoading &&
+ !setupGuide.visible;
const dismiss = () => {
writeSidebarOnboardingChecklistDismissed(true);
diff --git a/src/hooks/mutation/use-add-mcp-server.ts b/src/hooks/mutation/use-add-mcp-server.ts
index 5472de7c58..c597433c44 100644
--- a/src/hooks/mutation/use-add-mcp-server.ts
+++ b/src/hooks/mutation/use-add-mcp-server.ts
@@ -7,7 +7,10 @@ import {
parseMcpConfig,
toCanonicalMcpServer,
} from "#/utils/mcp-config";
-import { SETTINGS_QUERY_KEYS } from "#/hooks/query/query-keys";
+import {
+ SETTINGS_QUERY_KEYS,
+ SUPER_ADMIN_SETUP_QUERY_KEYS,
+} from "#/hooks/query/query-keys";
// @spec MCP-001 — Sparse mutations preserve sibling servers
export function useAddMcpServer() {
@@ -37,6 +40,11 @@ export function useAddMcpServer() {
queryClient.invalidateQueries({
queryKey: SETTINGS_QUERY_KEYS.personal(),
});
+ // The enterprise setup guide's "Add an integration" step counts MCP
+ // servers, and adding one does not change the page that re-reads it.
+ queryClient.invalidateQueries({
+ queryKey: SUPER_ADMIN_SETUP_QUERY_KEYS.all,
+ });
},
});
}
diff --git a/src/hooks/query/query-keys.ts b/src/hooks/query/query-keys.ts
index afa45d0259..d909e6ae3a 100644
--- a/src/hooks/query/query-keys.ts
+++ b/src/hooks/query/query-keys.ts
@@ -95,6 +95,14 @@ export const CANVAS_EXTENSIONS_QUERY_KEYS = {
] as const,
} as const;
+export const SUPER_ADMIN_SETUP_QUERY_KEYS = {
+ /** Every backend's setup-guide state, for invalidation. */
+ all: ["super-admin-setup-state"] as const,
+ /** Enterprise Super Admin setup-guide state for a cloud backend. */
+ state: (backendId: string, connectionRevision: number) =>
+ ["super-admin-setup-state", backendId, connectionRevision] as const,
+} as const;
+
export const SETUP_QUERY_KEYS = {
/** What the deployment supports. The same answer for every setup entry. */
capabilities: () => ["setup-capabilities"] as const,
diff --git a/src/i18n/translation.json b/src/i18n/translation.json
index b5e5bdda04..8416cda60c 100644
--- a/src/i18n/translation.json
+++ b/src/i18n/translation.json
@@ -43060,6 +43060,142 @@
"uk": "Пропустити контрольний список «Початок роботи»",
"ca": "Omet la llista Per començar"
},
+ "ONBOARDING$SETUP_GUIDE_TITLE": {
+ "en": "Setup guide",
+ "ja": "セットアップガイド",
+ "zh-CN": "设置指南",
+ "zh-TW": "設定指南",
+ "ko-KR": "설정 가이드",
+ "no": "Oppsettsveiledning",
+ "ar": "دليل الإعداد",
+ "de": "Einrichtungsleitfaden",
+ "fr": "Guide de configuration",
+ "it": "Guida alla configurazione",
+ "pt": "Guia de configuração",
+ "es": "Guía de configuración",
+ "ca": "Guia de configuració",
+ "tr": "Kurulum rehberi",
+ "uk": "Посібник із налаштування"
+ },
+ "ONBOARDING$SETUP_GUIDE_STEP_LLM": {
+ "en": "Add an LLM",
+ "ja": "LLM を追加",
+ "zh-CN": "添加 LLM",
+ "zh-TW": "新增 LLM",
+ "ko-KR": "LLM 추가",
+ "no": "Legg til en LLM",
+ "ar": "إضافة نموذج LLM",
+ "de": "LLM hinzufügen",
+ "fr": "Ajouter un LLM",
+ "it": "Aggiungi un LLM",
+ "pt": "Adicionar um LLM",
+ "es": "Añadir un LLM",
+ "ca": "Afegeix un LLM",
+ "tr": "Bir LLM ekleyin",
+ "uk": "Додайте LLM"
+ },
+ "ONBOARDING$SETUP_GUIDE_STEP_INTEGRATION": {
+ "en": "Add an integration",
+ "ja": "連携を追加",
+ "zh-CN": "添加集成",
+ "zh-TW": "新增整合",
+ "ko-KR": "통합 추가",
+ "no": "Legg til en integrasjon",
+ "ar": "إضافة تكامل",
+ "de": "Integration hinzufügen",
+ "fr": "Ajouter une intégration",
+ "it": "Aggiungi un'integrazione",
+ "pt": "Adicionar uma integração",
+ "es": "Añadir una integración",
+ "ca": "Afegeix una integració",
+ "tr": "Bir entegrasyon ekleyin",
+ "uk": "Додайте інтеграцію"
+ },
+ "ONBOARDING$SETUP_GUIDE_STEP_AUTOMATION": {
+ "en": "Choose an automation template",
+ "ja": "自動化テンプレートを選択",
+ "zh-CN": "选择自动化模板",
+ "zh-TW": "選擇自動化範本",
+ "ko-KR": "자동화 템플릿 선택",
+ "no": "Velg en automatiseringsmal",
+ "ar": "اختر قالب أتمتة",
+ "de": "Automatisierungsvorlage auswählen",
+ "fr": "Choisir un modèle d'automatisation",
+ "it": "Scegli un modello di automazione",
+ "pt": "Escolher um modelo de automação",
+ "es": "Elegir una plantilla de automatización",
+ "ca": "Tria una plantilla d'automatització",
+ "tr": "Bir otomasyon şablonu seçin",
+ "uk": "Виберіть шаблон автоматизації"
+ },
+ "ONBOARDING$SETUP_GUIDE_STEP_INVITE": {
+ "en": "Invite users",
+ "ja": "ユーザーを招待",
+ "zh-CN": "邀请用户",
+ "zh-TW": "邀請使用者",
+ "ko-KR": "사용자 초대",
+ "no": "Inviter brukere",
+ "ar": "دعوة المستخدمين",
+ "de": "Benutzer einladen",
+ "fr": "Inviter des utilisateurs",
+ "it": "Invita utenti",
+ "pt": "Convidar usuários",
+ "es": "Invitar usuarios",
+ "ca": "Convida usuaris",
+ "tr": "Kullanıcıları davet edin",
+ "uk": "Запросіть користувачів"
+ },
+ "ONBOARDING$SETUP_GUIDE_STEP_SAML": {
+ "en": "Optional: SAML / instance",
+ "ja": "任意: SAML / インスタンス",
+ "zh-CN": "可选:SAML / 实例",
+ "zh-TW": "選用:SAML / 執行個體",
+ "ko-KR": "선택 사항: SAML / 인스턴스",
+ "no": "Valgfritt: SAML / instans",
+ "ar": "اختياري: SAML / المثيل",
+ "de": "Optional: SAML / Instanz",
+ "fr": "Facultatif : SAML / instance",
+ "it": "Facoltativo: SAML / istanza",
+ "pt": "Opcional: SAML / instância",
+ "es": "Opcional: SAML / instancia",
+ "ca": "Opcional: SAML / instància",
+ "tr": "İsteğe bağlı: SAML / örnek",
+ "uk": "Необов'язково: SAML / екземпляр"
+ },
+ "ONBOARDING$SETUP_GUIDE_NEXT": {
+ "en": "Next: {{step}}",
+ "ja": "次: {{step}}",
+ "zh-CN": "下一步:{{step}}",
+ "zh-TW": "下一步:{{step}}",
+ "ko-KR": "다음: {{step}}",
+ "no": "Neste: {{step}}",
+ "ar": "التالي: {{step}}",
+ "de": "Nächster Schritt: {{step}}",
+ "fr": "Suivant : {{step}}",
+ "it": "Prossimo: {{step}}",
+ "pt": "Próximo: {{step}}",
+ "es": "Siguiente: {{step}}",
+ "ca": "Següent: {{step}}",
+ "tr": "Sıradaki: {{step}}",
+ "uk": "Далі: {{step}}"
+ },
+ "ONBOARDING$SETUP_GUIDE_START": {
+ "en": "Start",
+ "ja": "開始",
+ "zh-CN": "开始",
+ "zh-TW": "開始",
+ "ko-KR": "시작",
+ "no": "Start",
+ "ar": "ابدأ",
+ "de": "Starten",
+ "fr": "Commencer",
+ "it": "Inizia",
+ "pt": "Começar",
+ "es": "Empezar",
+ "ca": "Comença",
+ "tr": "Başla",
+ "uk": "Почати"
+ },
"AUTOMATIONS$GIT_SYNC$NAV_BUTTON": {
"en": "Git Sync",
"ja": "Git同期",
diff --git a/src/routes/root-layout.tsx b/src/routes/root-layout.tsx
index da7a70c9ce..ed78969e8d 100644
--- a/src/routes/root-layout.tsx
+++ b/src/routes/root-layout.tsx
@@ -41,6 +41,9 @@ const CommandMenu = React.lazy(() =>
default: m.CommandMenu,
})),
);
+const SuperAdminSetupGuide = React.lazy(
+ () => import("#/components/features/setup-guide/super-admin-setup-guide"),
+);
export function ErrorBoundary() {
const error = useRouteError();
@@ -159,6 +162,9 @@ function MainAppContent() {
<EnvironmentSwitchOverlay />
<CommandMenu />
</React.Suspense>
+ <React.Suspense fallback={null}>
+ <SuperAdminSetupGuide />
+ </React.Suspense>
{showOnboardingPreview ? <OnboardingHost /> : null}
</SidebarMobileNavProvider>
</CanvasExtensionsRuntimeProvider>