The guided first run: each setup step, the receipt, and how setup progress is tracked
A new console opens on its setup, at /setup. Setup asks one question at a time. Beside each question, a column called “Your backup plan” shows every decision so far, and a decision you can still change has a Change link. Setup ends when your first backup seals, and at that point the plan becomes your receipt.
Setup reads its progress from facts your engine reports, not from a saved position. An interrupted setup resumes at the first question you have not answered. A step your engine has already done, such as keys that your deploy made, reads as done and setup moves past it.
This page is for the Owner who runs setup. An operator can read it too, to learn why setup locks some screens and why that lock never shuts out a working console.
The steps at a glance
| Step | What it asks for | Why it asks |
|---|---|---|
| Welcome | Nothing. It checks your engine and lists what to have ready. | Setup cannot do anything until your engine answers. |
| 1. Connect | A read-only Cloudflare API token. | Your engine lists what you can protect, and learns which account it runs in. |
| 2. Destination | Where your archives go: the provider, the bucket, an object lock and an access key. | A run has nowhere to write without it. |
| 3. Protect | What to back up. | Each pick becomes a downpipe at the first backup. |
| 4. Keys | Your key posture, where your offline key lives, then the keys themselves, made in your browser. | Every run is sealed to your keys, so they exist before the first run. |
| 5. Apply | One deploy token, used once. | Your engine installs your keys and attaches the sources you picked. |
| 6. First backup | A schedule, retention and restore tests, then Create and run now. | You watch a real run seal, so you see the whole pipeline work. |
| 7. Finish | Nothing new. It shows your receipt and the optional next steps. | You see every decision, and anything that is still open. |
The seven numbered steps are the ones the setup strip and Overview count (MAIN_STEPS, console/src/lib/setup-flow/steps.ts; STEP_NUMBER, console/src/screens/setup/b/flow.ts). Welcome carries no number.
Setup asks for three credentials in total: one at Connect, one at Destination and one at Apply. Prerequisites says how to make each one.
Welcome
Welcome checks your engine first. It asks for the engine’s health, then for its status as you, then for how you signed in (probeEngine, console/src/lib/setup-flow/engine-probe.ts). When the check passes, Welcome says “Your engine answers” and shows the engine version.
Start stays unavailable until the check passes. A failed check names its cause and offers “Check again”. The three causes are on prerequisites.
Welcome also lists the three credentials to make in the Cloudflare dashboard. It says that your account needs the Workers Paid plan, and it estimates about 15 minutes for the whole setup (SETUP_TIME_ESTIMATE, console/src/lib/setup-flow/inventory.ts). Welcome has nothing to tick.
1. Connect
Connect asks for a read-only API token, and for how you made it. The “Read all resources” template covers your data and your Cloudflare configuration. The minimal token has five Read permissions and covers your data only. With the minimal token, configuration, Workers, Stream and Images backup stay unavailable until you widen it (TOKEN_SCOPES, console/src/lib/setup-flow/inventory.ts).
“Verify token” sends the token to your engine once. Your engine checks it with Cloudflare before it stores it (verifyToken, console/src/lib/setup-flow/actions.ts). The engine refuses a token with no expiry, a token that expires more than 90 days away, and a token that sees no account. Setup shows the engine’s reason, and your engine stores nothing.
When the token sees more than one account, a sheet asks two questions. Which accounts should downpipes list, and which account does your engine run in? Your keys and your source bindings belong to the account your engine runs in.
Connect comes first because later steps use it. Destination and Protect list your buckets and resources from it. Apply cannot install your keys until your engine has named its own account from the token (lockReason, console/src/lib/setup-flow/steps.ts).
2. Destination
Destination asks four questions, one at a time (console/src/screens/setup/b/q-destination.ts).
| Question | What you answer |
|---|---|
| Provider | Cloudflare R2, S3-compatible, Google Cloud or Azure Blob. R2 is selected when the question opens. |
| Bucket | For R2, a bucket from the list of R2 buckets in your engine’s account, a bucket name you type, or a bucket in another Cloudflare account. For the others, the endpoint and the bucket or container, plus the region for S3-compatible and Google Cloud. An optional name for the destination in downpipes. |
| Lock | Off, Governance or Compliance, and the number of days to lock each archive: a whole number, 1 or more. R2 skips this question, because R2 cannot lock objects. |
| Credentials | The access key for the bucket. An S3 bucket can also sign in with an AWS role, and an Azure container with Microsoft Entra. |
“Verify and save” uses the same save as the Destinations screen (commitDestination, console/src/screens/destination-submit.ts). Your engine writes a test file to your bucket and reads it back before it stores anything. When a check fails, the engine says why and stores nothing. Your engine then keeps the access key in your own Cloudflare account.
The plan also has a line for storage prices. Setup uses the prices for cost estimates only. For R2 the prefill is the R2 list price, and for the other providers it is the Amazon S3 Standard list price (pricingDefaults, console/src/lib/setup-flow/inventory.ts).
3. Protect
Protect shows one list, grouped by type, in your own resource names. Tick what to back up. Each group has an All or None button. When you tick a Stream or Images account, a second tick also copies the video or image files, not only the list of them.
Your backup bucket shows in the list, but you cannot tick it. “Add a resource by its id” adds a KV namespace, an R2 bucket, a D1 database or a Secrets Store secret that your token does not list. Setup checks each id’s shape as the Sources screen does. Its binding attaches at Apply, as SRC_<type>_<name>. Setup refuses a name that makes that binding longer than the engine’s limit of 64 characters (manualBindingFor, console/src/lib/setup-flow/model.ts).
An engine deployed with source bindings already in place, from wrangler or from infrastructure as code, has chosen its sources. The first time Protect lists them, while you have picked nothing and no downpipe exists, they become your picks. An untick stays.
4. Keys
Keys asks three questions: your posture, where your offline key lives, and whether you have moved it off this computer. The keys are made in your browser, and nothing leaves it while they are made.
Who can decrypt your backups
The posture question shows two choices side by side, with no default. “Offline key only” is first, then “Operational key”. Six rows compare them: whether the engine can decrypt, restore tests, pruning old runs, a breach or malicious update, a lost offline key, and changing later (CELLS, console/src/screens/setup/b/q-posture.ts).
When you choose one, its full acceptance statement appears with its version, and a tick: “I have read the implications and understand my choice.” Confirm records the statement with your engine (acknowledgePosture, console/src/lib/setup-flow/actions.ts). Choosing your key posture quotes both statements in full.
When your engine does not record the statement, your choice still stands. Setup shows the engine’s reason, and Finish keeps the statement as an open item with “Record it again”.
When your engine already holds keys, Keys says so and offers “Use these keys”. Setup takes the posture those keys set and never makes a second key set. Replace keys on the Keys screen if you need to (keysAlready, console/src/screens/setup/b/q-posture.ts).
Where your offline key lives
The custody question comes before the keys exist, so the first recovery sheet records your choice.
| Choice | What it means |
|---|---|
| Corporate password manager | A password manager or team vault. |
| Encrypted USB plus a paper companion | A hardware-encrypted drive, with a printed copy. |
| M-of-N custodian split | Any M of N people recover the key together. From 2 to 16 shares, with at least 2 needed; setup starts at any 3 of 5. |
“Make my keys” makes the keys in this browser and downloads the key files at once. The files are identity.key, recipient.pub, signer.pub and recovery-sheet.txt, plus operational.pub under the operational posture (ceremonyFileNames, console/src/lib/setup-flow/inventory.ts).
Move identity.key off this computer
The last Keys question shows each file in one of two groups. “Keep offline” holds identity.key, the recovery sheet and signer.pub. “Public copies” holds the rest. Each file shows its download state, and each has its own “Download again”.
Move identity.key where your custody choice says, then tick “I moved identity.key off this computer.” Continue waits for any file your browser did not download. With the split, you make the custodian shares here first, then delete identity.key.
Two optional checks read files in your browser and upload nothing. “Check identity.key” compares the file you saved with the key made here. With the split, “Check your shares” rebuilds the key from the shares and identity.key.enc and compares it the same way.
At Apply your engine gets the signing key, the configuration keys and the public keys. Under the operational posture it also gets the operational key. identity.key has no field in the install, so it never leaves this device (KEYS_TRUST_OFFLINE, console/src/screens/setup/b/q-keys.ts; installCeremonyKeys, console/src/lib/setup-flow/install.ts).
Keys live only in this tab until Apply
The keys are in this tab’s memory. Leaving setup or reloading the page clears them, and setup asks before it lets you leave. After a reload, make the keys again and delete the files you saved before, because they no longer match.
5. Apply
Apply offers two routes, side by side: a deploy token, or your own wrangler or CI.
The deploy token
Make the token from the “Edit Cloudflare Workers” template, and limit it to this account. Add D1 Edit when you protect a D1 database, and Secrets Store Edit when you protect a Secrets Store secret. Paste the token and press “Install and attach”. A passkey check may follow.
A live checklist shows four stages, each with its own time (applyWithDeployToken, console/src/lib/setup-flow/actions-apply.ts):
| Stage | What happens |
|---|---|
| Install your keys | Your engine writes its own secrets with the token. |
| Engine loads the keys | Setup reads the engine status until it reports the signer and the break-glass key, about two minutes at most. |
| Attach, with the names of your picks | Your engine adds a binding for each picked resource that needs one. |
| Bindings go live | Setup reads your engine’s bindings until each new one is live. |
The token stays in one function call. Setup never stores it, logs it or puts it in the setup draft. Under the operational posture, Apply warns first that the install also puts the operational key in your engine, and that it can decrypt your backups.
Apply is safe to run again. It skips keys already installed and bindings already live. Sometimes an install’s answer does not come back. Before setup sends the keys again, it asks your engine for about ten seconds whether it holds them. When your engine took the keys and has not reported them yet, Apply offers “Check again” and says not to make new keys.
Your own wrangler or CI
This route needs no token. Apply lists a wrangler secret put command for each secret, the binding stanzas for your wrangler.toml, and the deploy command. While this tab holds your keys, each command has a Copy button for its value. After you deploy, “Check my engine” reads the keys and the bindings (selfDeployPlan, console/src/lib/setup-flow/actions-apply.ts).
Revoke the deploy token
Your engine does not keep the deploy token, so the next question asks you to revoke it in the Cloudflare dashboard. Tick “I revoked the deploy token.”, then Continue. If you pasted a token more than once, the question asks for each one.
“Remind me at the end” lets you continue first. A reminder then stays on the First backup views, on the receipt and on Overview, until you tick it. The reminder outside setup keeps a count and a date only (console/src/lib/setup-flow/revoke-reminder.ts).
Credentials saved before the keys
Connect and Destination store two credentials before your keys exist: the read-only token and the bucket’s access key. Your engine encrypts a stored credential under its configuration wrap key, CONFIG_WRAP_KEY, which the key install puts in place.
At the key install, your engine encrypts each stored credential that the wrap key covers and that is not encrypted yet. The wrap key covers the destination keys and the read-only token, and also the secrets of the push, ticketing and identity provider integrations. Your engine checks that each encrypted copy opens before it replaces the original. It then answers the install with a report of what it encrypted, and writes one config-secrets-rewrapped event to your audit log. That event carries counts and credential classes, never a value (rewrapAfterKeyInstall, engine/src/admin/config-rewrap.ts).
Setup reads that report and does not assume it. Finish shows a “Saved credentials” row:
| What your engine reported | What the row says |
|---|---|
| Every credential encrypted | Encrypted by your engine when your keys were installed, with a count. |
| No report | Open: your engine did not report encrypting them. Save them again. |
| A credential left unencrypted | Open: how many, and which classes. Save them again. |
| You used your own wrangler or CI | Open: a wrap key set with wrangler secret put runs no engine route, so nothing was encrypted. Save them again. |
To close an open row, save the token again on Sources and the destination key again on Destinations, then tick “I saved them again.”
6. First backup
First backup turns each pick into a downpipe, a scheduled backup. Each row shows what it backs up and its name. You can rename a row that backs up one resource. Ticked Secrets Store secrets share one downpipe.
| Setting | Choices |
|---|---|
| Schedule | Daily, which is selected and recommended, Every 6 hours, Hourly or Weekly. |
| Retention | Keep every run, which is selected. Under the operational posture you can also keep 90 days, keep 365 days, or set your own limits. Under offline key only, your engine keeps every run, and you prune old runs yourself, in the console or with the offline reader. |
| Restore tests | Under the operational posture: Weekly, which is selected, Daily or Off. Under offline key only: attended, with your key. |
Prefixes, cron, timezone, maintenance windows, ID overrides, capture mode and extra destinations are not in setup. They are in each downpipe’s editor under Downpipes.
“Create and run now” creates the downpipes and starts a run of each one (createDownpipes, runNow, console/src/lib/setup-flow/actions-apply.ts). The run view adds a line for each stage your engine reports, with one clock for the whole view.
| How the run ends | What the run view says |
|---|---|
| The run is sealed and the engine verified the seal | Sealed and verified. |
The run is sealed and the engine has verify-at-seal switched off (VERIFY_AT_SEAL) | Sealed, seal not verified, with a note that a restore test proves the backup restores. |
| The run failed, or its seal is suspect | Did not finish, with the downpipe’s name and the engine’s reason, and “Run it again”. |
“See your receipt” opens Finish. When your engine already has downpipes that setup did not make, First backup runs those instead of making more. On a console that is already set up, the run is optional in a tab that is working through setup. “Leave setup” skips it.
7. Finish and the receipt
Finish turns “Your backup plan” into your receipt. Each row shows a decision and its final value (receiptRows, console/src/screens/setup/b/q-finish.ts; buildReceipt, console/src/lib/setup-flow/receipt.ts):
| Row | What it shows |
|---|---|
| Key posture | The posture, the statement version, and whether your engine recorded it. |
| Custody | The custody scheme, the custodians, and whether you confirmed identity.key is offline. |
| Saved credentials | Only when setup stored credentials before the keys. See above. |
| Destination | The provider, the bucket, the account and the object lock. |
| Sources | Each pick, with its type. |
| Schedule | The schedule, the retention and the restore tests. |
| Deploy token | Not used, used and revoked, or used and not confirmed revoked. |
| First run | The result, when it ran, and the engine’s own run time. |
The headline says “You are protected” only when your engine has sealed and verified your first run and no item is still open. With an open item, the headline says only what is true, and the receipt marks each open item with the action that closes it:
| Open item | How to close it |
|---|---|
| The deploy token is not confirmed revoked. | Revoke it in Cloudflare, then tick “I revoked it in Cloudflare.” |
| Your engine did not record the posture statement. | “Record it again”. |
| Your engine holds keys for a different posture from the one you confirmed. | “Open Keys”, and check the posture there. |
| Saved credentials are not reported encrypted. | Save them again, then tick “I saved them again.” |
| The first run is sealed, but not verified. | “Run a restore test”. |
| You chose the split, and the shares are not made. | Make the shares from your identity.key on the Keys screen’s Custody tab. |
“Print receipt” prints it. “Open the console” tells your engine that setup is done, then opens Overview. A “Setup complete” message appears only after a sealed and verified first run (finishSetup, console/src/lib/setup-flow/install.ts).
After a sealed first run, Finish also says that a sealed backup is not yet a proven restore. Overview lists a downpipe as not proven until a restore test passes. Straight after “You are protected”, Overview therefore reads “backed up but not proven”.
The optional steps
Finish lists three optional next steps. Each one says what happens if you skip it (finishNextSteps, console/src/lib/setup-flow/receipt.ts).
| Step | What it does | If you skip it |
|---|---|---|
| Your team | Grants a teammate a built-in role by email. It offers only the roles you can grant, and says which it holds back. The engine makes a one-time invite link, which setup shows once and does not store. Needs permission to manage roles, held by the Owner and Access admin roles. A passkey check may follow. | Only you can sign in. Add people later under Access. |
| Restore approval | “On my own”, “A second approver” or “Decide later”. Setup marks “A second approver” unavailable while you are the only Owner. The engine refuses it then too, except from the bare admin token (setRequireRestoreApproval, engine/src/sched/scheduler-do-change-control.ts). | You restore on your own, the engine default. Change it later in Security Centre. |
| Hardening | Suggestions that fit your setup, such as a second destination outside this account, a destination with Object Lock, or an attended verification. It also offers Cloudflare Access, outbound email, and “Check my engine”. | Nothing changes. Security Centre lists them later. |
“Check my engine” opens a read-only list of what your engine reports: the keys, then each preflight item it has verified or seen fail. Prerequisites explains that list.
Setup progress comes from engine facts
Setup never stores a step position. Each step’s state comes from what your engine reports, plus the answers you gave in this tab (computeSteps, console/src/lib/setup-flow/steps.ts):
| Step | Done when |
|---|---|
| Welcome | You pressed Start, or an engine fact shows setup has begun. |
| Connect | Your engine holds the read-only token and it sees an account, or your engine already has downpipes. |
| Destination | Your engine has a destination, from the console or from your deployment. |
| Protect | You picked something, or your engine has a source bound, or it already has downpipes. |
| Keys | Your engine holds keys. Also done while this tab holds keys you confirmed saved, or after your engine took this setup’s key install. |
| Apply | Your engine holds keys, and every picked resource that needs a binding is live. |
| First backup | This setup’s first run ended ok and its seal is not suspect. With no run of this setup’s own, a downpipe whose integrity your engine has recorded. |
| Finish | Never. Finish is where setup ends. |
Two steps wait for earlier ones. Apply waits for Connect, Protect and Keys. First backup waits for a saved destination and for Apply. Finish, the step after the first backup, lists your team and restore approval as optional next steps.
An engine set up outside the console therefore skips what it already has. Keys that npm run deploy made read as done, and setup takes their posture from the engine. A destination your deployment set reads as done, and the receipt says “set by your deployment”. Source bindings your deployment made become your picks.
The setup strip, the rail and Overview
Until the shell counts setup complete, the console shows where setup is (renderSetupStrip, console/src/shell/rail.ts; setupLockReason, console/src/lib/setup-state.ts):
| Where | What it shows |
|---|---|
| The setup strip | “Setting up, step N of 7:” and the step’s name, with “Continue setup”. It steps aside on Overview, where the setup card says the same. |
| The rail | A screen that is not meaningful yet is greyed, with “Available after setup. Step N of 7, Label, comes first.” It is never hidden. |
| Overview | A “Set up your first backup” card with the seven steps, a count of the steps done, and “Continue setup”. |
| The command palette | “Continue setup”. Once setup is complete, it offers “Check engine wiring” instead, which opens “Check my engine”. |
While setup is unfinished, the first load of / opens /setup, once per page load. After that, “Leave setup” and every visit to / show Overview and its setup card.
A deep link to a locked screen shows a message naming the current step, then opens /setup, which resumes at the first open question. Reaching a step unlocks the screen that owns the same thing after setup. Connect unlocks Sources, Destination unlocks Destinations, and First backup unlocks Downpipes and Runs. Setup never locks Overview, Keys, Settings, Licence and updates, Costs or Security centre.
When setup is complete, the strip says “Setup complete.” with “Open Downpipes”. It adds “Your first backup is sealed.” only when First backup is done. It stays until you dismiss it.
Setup never locks a console that was past it
The shell, meaning the strip, the rail, the gate, the first load and the palette, counts setup complete in two cases (shellComplete, setUpByEstateFacts, console/src/lib/setup-flow/steps.ts):
- Every numbered step before Finish is done.
- Your engine holds keys and a destination, your account is connected, and at least one downpipe exists. These are the facts the console counted as setup done before this setup existed.
The second case keeps an existing install open after an upgrade, even when none of its downpipes has a sealed run yet. Once the shell counts setup complete, it stays complete for the life of that page, whatever a later read says. The setup page keeps its own step states. In a tab that is working through setup on such an install, it offers the first backup run as optional, and “Leave setup” skips it.
A tab that has not worked through setup holds none of the answers the plan and the receipt read. On a console the shell counts set up, /setup in such a tab opens Overview with the message “Setup is already done on this engine. Each setting is on its own screen.”
The team step (/setup/team) and “Check my engine” (/setup/finish/check) read your engine, not the tab. They stay open, with “Open the console” as the way out (setupDoneElsewhere, console/src/screens/setup/b/flow.ts). “Invite your team”, after a new Owner registers a passkey, opens that team step. Only a sealed and verified first run makes setup say “protected”.
The gate is fail-open
The setup gate is built so that a hiccup never locks you out of a working console. The console shows no gate, no strip and no lock until it has read both the setup state and the downpipe list. It shows none on a refresh where either read failed (setupViewOf, console/src/lib/setup-state.ts). The support ring records a failed setup-state read, so a support pack shows it.
Who can do each step
In setup, only an Owner can do Welcome, Connect, Destination, Protect, Keys, Apply and restore approval (OWNER_STEPS, console/src/lib/setup-flow/steps.ts). The engine refuses the token, destination, key install, attach and restore-approval calls from any other role, and Welcome and Protect lead only into those calls. Anyone else sees “An Owner sets up downpipes” on those steps, with the step setup is at. The strip says “An Owner does this step.” and offers “View setup” instead of “Continue setup”.
An Operator or higher can create and run the first backup. Inviting your team needs permission to manage roles. The engine enforces each role on every call.
Leaving setup and coming back
Setup keeps your answers in this tab’s session storage. The draft holds no token, no credential and no key material. Signing out, or a session that ends, removes it.
Your keys are the exception, because they live only in the tab’s memory until Apply. Setup asks before you leave with keys that your engine does not hold yet. After a reload, the Keys step asks you to make them again.
Your engine can hold a key that reads your backups
The break-glass private key, identity.key, is made 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 choice you make, not a default. The posture question has no default. Offline key only comes first, and it needs no further action to keep. An operational key 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 protect archives it could already read while it was present.
Where to go next
- Prerequisites says how to make the three credentials before you start.
- The quickstart walks the same steps as a task list, then proves your first backup with a drill.
- Choosing your key posture sets out what each posture lets your engine do, and quotes both statements.
- The key ceremony and recovery kit covers the keys that Keys makes and the files you keep.
- Connecting a source covers the Sources screen, where the read-only token and your bindings live after setup.
Last updated .