The guided first run: the onboarding carousel and how setup progress is tracked
When you open a freshly deployed console for the first time, two separate systems shape what you see. The first is the onboarding carousel: a full-bleed deck of cards that walks you through connecting, generating your keys, configuring your engine and inviting your team. The second is a quieter setup-progress model that watches the engine’s own facts and decides which parts of the console are meaningful yet.
These two systems are easy to conflate because both happen to have five parts, but they are not the same thing and they do not share a position. The carousel is a guided walkthrough you can re-run; the setup-progress model is derived live from what the engine reports, never from a stored wizard step. This page documents each one as it actually ships, so an Owner knows how the carousel gates and resumes, and an operator understands why a rail item is sometimes locked and why that lock can never wall a working console off.
The first run is a card deck, not a side-railed wizard
The shipped first-run experience is a full-bleed carousel: a stage of cards grouped into five chapters, moved with the side chevrons, the keyboard arrows, a swipe, or the action on each card. There is no persistent step rail down the side. Each card mounts lazily the first time you reach it, so it reads live store state (the engine connection, the in-browser ceremony result) at the moment it is shown rather than at page load.
The tagline on the first card sets the tone: “Back up your data automatically. Recover it yourself, even offline.”
The twelve cards across five chapters
The deck is twelve cards. Five of them gate forward movement (marked below); the rest advance freely.
| # | Card | Chapter | Gated | What it does |
|---|---|---|---|---|
| 1 | welcome | Connect | no | The opening hero and the tagline. |
| 2 | prereqs | Connect | yes | Tick the account prerequisites only you can confirm. |
| 3 | connect | Connect | yes | Probes the engine on this same address and reports the sign-in verdict. |
| 4 | keys-intro | Your keys | no | Introduces the small key set generated in your browser. |
| 5 | break-glass | Your keys | no | Explains the break-glass key that never leaves the browser. |
| 6 | tradeoff | Your keys | yes | Makes you choose a key posture, strict break-glass-only or add an operational key, and tick the acceptance statement for your choice (see the warning below). |
| 7 | generate | Your keys | yes | Runs the key ceremony in the browser and downloads the files. |
| 8 | keys-ready | Your keys | no | The file manifest, fingerprints and the optional offline custody menu. |
| 9 | install | Configure | yes | Installs the keys to your engine using a one-shot token. |
| 10 | team | Your team | no | Invite a teammate by role. Optional, with a Skip. |
| 11 | readiness | Ready | no | A posture check of what the engine can verify for itself. |
| 12 | done | Ready | no | The completion hero, which opens the console. |
The five chapters are Connect, Your keys, Configure, Your team and Ready. The chapter rail along the top shows which chapter you are in and lets you jump back to a chapter you have already reached.
How forward navigation is gated
Forward movement is locked on five action cards: prereqs, connect, tradeoff, generate and install. On a gated card the Next chevron stays disabled until the card’s own action is satisfied, at which point the card calls an internal markPassed and the chevron unlocks. The card’s own primary button (for example “Generate my keys” or “Continue”) is the sanctioned forward move and bypasses the gate once it is enabled. The tradeoff card’s gate is easy to miss if you are expecting it to be informational only: it will not let you continue until you have picked a posture and ticked the acceptance statement for that choice.
If you try to move forward from a gated card before it is satisfied, two things happen: a short per-card nudge appears as a toast (for example “Tick the required items to continue” on prereqs, or “Generate your keys to continue” on generate), and the Next button shakes. Every other card advances freely with no gate.
The prereqs card is worth a note because its gate is the one part of setup the engine cannot check for you. It asks you to confirm two required items in your own Cloudflare account, the Workers Paid plan and R2 object storage, plus two optional ones, Cloudflare Access and outbound email. Ticking both required items unlocks the card; the optional items never block.
Deep links, resuming and re-running
The carousel can be opened at a specific card. The route still uses the old step names, and each maps to a card:
| Deep-link step | Opens at card |
|---|---|
| connect | welcome |
| ceremony | keys-intro |
| configure | install |
| invite | team |
| readiness | readiness |
Any step name that is not in that map opens the deck at the first card, welcome. The flow is re-runnable from the command palette (“Re-run setup or verify wiring”), which lands on the connect step, the safe entry that resumes forward. Because the carousel mounts each card against live state, resuming works without a stored position: a card that finds the engine already has its keys, for instance, reframes itself to lead with “Continue with these keys” instead of asking you to generate again.
Your engine holds a key that can read your backups by default
The break-glass private key, identity.key, is generated in your browser and never leaves it. There is no field, button or command anywhere in the console that uploads it.
The operational key is different, and it is a forced choice rather than an assumed default. The carousel’s tradeoff card makes you pick a posture before you can continue: strict break-glass-only, which leads the fork and needs no further action to keep, or add an operational key as a deliberate opt-in, which the card tells you in plain words means your engine can test-restore your backups on its own, so it can read them, and so could anyone who broke into your Cloudflare account. Adding an operational key later, from the Keys screen, needs no re-key. Removing one later does not retroactively protect archives it could already read while it was present.
Setup progress is derived from facts, not from where you are
Separate from the carousel, the console tracks setup progress with a small model that derives five steps from the engine’s reported facts. It reads GET /admin/setup-state and turns the answer into a view; it never stores or reads a wizard position. The practical effect is that a deployment which already has its sources in place, an infrastructure-as-code or wrangler-bound engine, for example, skips the steps those facts already satisfy. There is no progress to lose and nothing to resume from a saved cursor; the steps simply reflect what is true right now.
The five setup-state steps
| # | Step | Done when | Route |
|---|---|---|---|
| 1 | keys | The engine reports the signer and break-glass keys present (keysReady). |
/onboarding/connect |
| 2 | destination | The destination is configured. For a deploy or environment-bound R2 or S3 destination this is presence only, no write probe; only a destination set from the console separately reports as verified. | /destinations |
| 3 | connect | A read-only discovery token is present, or sources are already bound. | /sources |
| 4 | sources | At least one source is bound to the engine (boundSourceCount > 0), or a downpipe already exists, so a later dropped binding does not re-lock a console that is already past setup. |
/sources |
| 5 | downpipe | At least one downpipe exists, or the count is absent. | /downpipes |
The first incomplete step in that order is the current step. When every step is done the view is complete and the gate dissolves.
The two five-item models are not the same
The carousel has five chapters (Connect, Your keys, Configure, Your team, Ready). The setup-progress model has five steps (keys, connect, destination, sources, downpipe). They differ, and they must not be conflated. In particular, the setup-state keys step routes to /onboarding/connect, which opens the carousel at its welcome card. It does not route to /keys.
The setup strip and the locked rail
While setup is incomplete, the shell shows a quiet setup strip between the context bar and the main content: step pips, a “step N of 5” line naming the current step, and one Continue link to it. It is a single quiet line, not a banner. On the Overview screen the strip steps aside, because the Overview checklist already states the same thing there. When the current step is owner-only and you are signed in as something other than an Owner, the strip’s line adds “(an Owner finishes this step)” and its link reads “View the step” instead of “Continue”, an honest hand-off rather than a Continue that would fail.
The shell also re-shapes the navigation rail. A rail item whose step is not yet meaningful is shown locked: greyed, with the reason carried inline (“Available after setup, step N of 5 … comes first”), never hidden and never a dead click. That inline reason is the same fixed string for every caller; it does not vary by role. Reaching a step unlocks its whole screen, including that screen’s sub-routes.
Navigating still works even while items are locked. If you reach a screen that is beyond the current step, the route gate redirects you to the current step’s home and shows the same reason as a toast, so you land somewhere useful rather than at a wall.
The gate is fail-open
The setup gate is built so a hiccup can never lock you out of a working console. Two cases make the read itself come back unknown, so the model yields no view at all:
- A setup-state read fails for any reason.
- The engine is an older build that does not have the
/admin/setup-stateendpoint.
In either case a null view never engages the gate: a console that was past setup a moment ago is not re-locked by a transient blip.
A third case is handled differently, inside the derivation rather than by suppressing the view: when a fact-derived count is absent (for example the downpipe count is missing), that one step reads as done rather than not-done, but the view returned is still a normal one, and every other step keeps gating exactly as its own facts say. This is the safety rule throughout: the gate forces order only when the facts clearly say a step is outstanding.
How the gate and the strip refresh
The setup view refreshes when your identity resolves and after navigations while setup is incomplete, coalesced so a burst of navigations (such as a redirect chain) makes at most one read every couple of seconds. It is not a polling loop. The route gate reads the same view: while the view is incomplete and a target route is not yet allowed, it defers a redirect to the current step’s route by a microtask, so the redirect resolves cleanly rather than interleaving with the blocked navigation.
There is also a one-shot self-heal for a known demo case. After a demo reset the signer and break-glass secrets survive but a marker can pin the keys step as not done. When the keys step reads not done, the console asks the engine to acknowledge setup; the engine clears the marker only if it actually observes the keys present, so a genuinely keyless engine is a safe no-op. If anything clears, the view is refetched. Any failure falls back to the original view, so this never blocks either.
Where to go next
- Recovery postures explains the two-recipient posture and the strict break-glass-only opt-out the tradeoff card points to.
- The no-custody trust model sets out what the vendor and the engine each hold, and what the engine can read by default.
- The key ceremony and recovery kit covers the in-browser key generation the generate card runs and the files it produces.
- Connecting a source is the connect and sources steps of setup, where you paste a read-only token and bind what to protect.
Last updated .