Onboarding Steps
Rule
If a feature requires user-facing setup (API keys, OAuth, connecting a third-party service), register an onboarding step so it appears in the agent sidebar's setup checklist.
Onboarding must point users to a secure credential path; it must never encode
the credential value in source, docs, fixtures, prompts, or generated content.
For a provider represented in the workspace connection catalog, check the
connection readiness and app grant first, then resolve credentials through the
scoped workspace-connection helper. Only when no reusable connection exists
should API keys and service tokens use registerRequiredSecret() from the
secrets skill. For OAuth, check the scoped OAuth token store. Use deployment
env vars only for deploy-level configuration, not per-user credentials.
Model onboarding around the logical connection outcome, not its individual
fields. Because registerRequiredSecret({ required: true }) auto-injects a
checklist item per registration, do not mark every credential/config field as
required by reflex. Use one composite onboarding step or connection readiness
check when several values are needed for one provider.
A custom setup page is appropriate only when it adds provider-specific prerequisites, sequencing, or health checks. Keep it as a thin guide over the shared settings, vault, OAuth, and action surfaces; never make it a second place that stores or manages credentials.
Registering a Step
import { registerOnboardingStep } from "@agent-native/core/onboarding";
import { hasOAuthTokens } from "@agent-native/core/oauth-tokens";
registerOnboardingStep({
id: "gmail",
order: 100,
title: "Connect Gmail",
description: "Grant read/send access.",
methods: [
{
id: "oauth",
kind: "link",
primary: true,
label: "Sign in with Google",
payload: { url: "/_agent-native/google/auth-url" },
},
],
isComplete: async (ctx) =>
ctx?.userEmail ? hasOAuthTokens("google", ctx.userEmail) : false,
});
See packages/core/docs/content/onboarding.md for method kinds and built-in steps.
For S3-compatible file storage, declare a kind: "file-storage" method instead
of a form with S3_* fields. It renders the shared StorageSettingsForm,
which saves through the manage-file-storage action (owners and admins only),
so onboarding, Settings, and templates cannot drift into different rules. A
provider that serves files without a public URL sets
publicBaseUrlOptional: true on its FileUploadProvider.
Shared services: one list for first-run and Infrastructure
WORKSPACE_SERVICES (packages/core/src/onboarding/workspace-services.ts,
exported from @agent-native/core/onboarding) is the one list of services
every app shares: AI model, storage, voice, images, embeddings, and the
Builder.io-only services. First-run "Choose your setup" reads it through
getOnboardingAppProfile(), which tags each capability with its service id
(and builderOnly). Settings › Organization › Infrastructure renders one
Services row per entry and takes its Required/Recommended tags from those ids.
- To add a shared service, add it to
WORKSPACE_SERVICESand give it a row inInfrastructureSettingsPage.tsx; its records are keyed by service id, so the page won't compile without one. Never add a label to first-run alone. - To tailor a service for one app, declare a capability in that app's profile
with one of the service's
capabilityIds(Clips'video-storage). It replaces the default copy and can raise the tag, never lower it. - An app's own capabilities (a Figma token, a Gmail connection) stay out of
WORKSPACE_SERVICES. First-run shows them only when required or suggested. - List a Builder.io capability only if Builder.io actually powers it in code.
Transactional email is deployment configuration, not an onboarding form. The
built-in email step links to the host variables (RESEND_API_KEY or
SENDGRID_API_KEY, plus EMAIL_FROM) and is hidden when the deployment
already provides email. Don't add a step that saves those keys.
Related Skills
adding-a-feature— The four-area checklist; onboarding is often part of a new integrationauthentication— Most onboarding steps involve OAuth or credentials