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.

​
The three steps

The web wizard is a split screen: the form on the left, a live preview of what is being built on the right. The stepper names the three things you decide about — Workspace, Model, Crew — and each step persists what it collected before the next one opens, so a reload or re-login resumes where you left off.
  1. Workspace — a name and the language your agents reply in. A “Before you start” checklist on this step tells you the two things you will need: a Claude Code CLI token (with a copyable claude setup-token) and Docker running on the server (checked automatically).
  2. Model — the agent toolchain and its CLI token. Only Claude Code is fully supported today, so it is the one card shown; the other adapters (OpenCode, Codex CLI, Gemini CLI, Cursor CLI, Factory Droid) sit behind a “Show experimental toolchains” disclosure and cannot finish setup yet. The model list offers every curated model for the toolchain (from config/models.json), with the catalog’s default marked recommended and older generations marked older. The token field says what you pasted before the server verifies it: an sk-ant-api… console key is flagged immediately, an sk-ant-oat… CLI token is confirmed on Continue.
  3. Crew — a conversation with Crewship Guide on the right. The chat opens with a short greeting and four starter prompts in your chosen language; pick one or describe the work in your own words, and the Guide proposes a crew. Nothing is created until you click Create on the proposal card. The card shows the crew’s icon and colour (the Guide picks them from the same set the crews page uses), one row per agent with its name, role and model, the extra container tools and the network access — never a summary in place of the rows. “Prefer to pick a template instead?” is the escape hatch to the four built-in templates.

​
Guards against dead ends

  • A disabled Continue or Launch always says why, in one line beside the button (no workspace name, no container runtime, an experimental toolchain, no token, no crew yet).
  • Skip setup asks first. The wizard is one-shot, so skipping lands on an empty dashboard; the confirmation says so and points at the dashboard checklist.
  • If Crewship Guide cannot be reached, the Crew step switches to templates and says so, rather than showing templates with no explanation.
  • The Guide is not a colleague. It lives in a crew of kind setup, and both the crew and its agent are hidden from every roster — /crews, /agents, the chat column, the Agents facet, mention pickers and routine reach — so a fresh workspace’s /chat opens on nothing rather than on the Guide’s seeded conversation. GET /api/v1/agents?include_setup=1 and crewship agent list --include-setup are the explicit opt-in.
  • A reload after Create does not strand you. The “Built so far” panel reads the workspace’s real crews back; when one exists but the page no longer holds its proposal, Launch stays enabled and finishes setup through POST /api/v1/onboarding/complete without deploying a second crew.
  • Phones and tablets stack the form above the preview; the stepper collapses to one row, every control meets the 44px touch target, and nothing scrolls horizontally.
  • 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.