Skip to main content

​
Onboarding

​
Overview

Onboarding is the path Crewship takes a fresh installation through on its very first start — from an empty SQLite database to a single admin account, a configured LLM provider, and a ready-to-run first crew. It owns the moment between crewship start and the user’s first agent message, and is the only flow where most of Crewship’s safety rails (auth required, RBAC enforced, credentials encrypted at rest) get bootstrapped from defaults rather than from existing rows. The flow is two-stage. Stage one is /bootstrap: a fresh instance redirects there from /login, and POST /api/v1/bootstrap creates the first admin user (idempotent — it refuses a second admin). The CLI equivalent is crewship init. Stage two is the wizard. Two surfaces drive it: the web wizard at /onboarding (app/(onboarding)/onboarding/page.tsx) is the default experience — a multi-step, auth-gated form that walks the (already-created) admin through workspace naming, LLM provider selection, and first-crew templating, with a live preview pane on the right showing the chat surface that’s being provisioned. The CLI mirror crewship setup (cmd/crewship/cmd_setup.go) covers headless installs and CI-driven provisioning, accepting the same inputs as flags and emitting the same final state. Behind both surfaces the onboarding service (internal/api/onboarding.go and internal/services/onboarding.go) is the single funnel: it validates inputs, resolves the chosen LLM provider against the same resolveLLMProvider registry that the agents API uses (so a value accepted here cannot be rejected later when the first agent runs), encrypts and stores the supplied credential as an AI_CLI_TOKEN-typed credential (regardless of provider — see insertOnboardingCredential in internal/api/onboarding.go), creates the workspace + first crew rows transactionally (the admin user already exists from the /bootstrap stage), and marks setup complete.
Onboarding takes a CLI token, not a raw provider API key. For Anthropic it expects a Claude Code OAuth token (sk-ant-oat…, produced by claude setup-token) and validateOnboardingCredential rejects a raw account key (sk-ant-api…) with a fix-it message, then probes api.anthropic.com to confirm the token works before completing. On the CLI, crewship setup takes this as --token (the older --api-key alias is deprecated).
After that flag flips, both /onboarding and the bootstrap auth page redirect to the regular sign-in flow — the wizard is intentionally one-shot.
  • First Crew — what the wizard’s “first crew” step actually provisions.
  • Credentials — how the CLI token entered during onboarding is encrypted and surfaced to agents.
  • Installation — getting the binary onto the host before the wizard can run.