Before you start: Cloudflare account prerequisites and what you will need
downpipes runs inside your own Cloudflare account. The console’s setup opens on a Welcome step, and Welcome names what you need before you start: the Workers Paid plan and three credentials. This page explains each one, which setup step uses it, and why.
This page is for the Owner who is about to deploy and run setup. You do not run a terminal command for any of these prerequisites. You make each credential in a dashboard, and you paste it into the setup step that asks for it.
What Welcome asks you to have
Welcome lists three credentials to make before you start. Welcome also says that your Cloudflare account needs the Workers Paid plan. It quotes about 15 minutes for the whole setup, dashboard time included (welcome, console/src/screens/setup/b/q-start.ts).
Welcome has nothing to tick. Its Start button waits for your engine and nothing else: the engine check, then a read of your engine’s setup state. Setup asks for each credential later, at the step that uses it.
| Prerequisite | Step that asks for it | What it is for | Does your engine keep it? |
|---|---|---|---|
| A read-only API token | Connect | Your engine lists what you can protect, and names its own account for the key install. | Yes, until you remove it. |
| An access key for your backup bucket | Destination | Your engine writes your archives to the bucket you choose. | Yes, in your own account. |
| A deploy token | Apply | Your engine installs your keys and attaches the sources you picked. You use it once. | No. You revoke it after Apply. |
With a Cloudflare R2 bucket, you make all three in the Cloudflare dashboard. With another storage provider, the bucket key comes from that provider’s own console.
The Workers Paid plan
The engine sets a raised CPU limit, and a deploy on the free plan refuses it. Backup runs also need more subrequests than the free plan allows. The plan costs about $5 a month. Turn it on in the Cloudflare dashboard, under Workers and Pages, then Plans, then Workers Paid.
The engine cannot see your plan from inside its Worker, so setup does not check it for you. The deploy is the check: wrangler deploy refuses the engine’s raised CPU limit on an unpaid account (probeWorkersPlan, engine/src/admin/preflight-probes.ts).
The read-only API token
Connect asks for this token. You can make it in two ways, and both are read-only (TOKEN_SCOPES, MINIMAL_TOKEN_PERMISSIONS, console/src/lib/setup-flow/inventory.ts):
| Token | How to make it | What it covers |
|---|---|---|
| Read all resources | The dashboard template of that name. | Your data and your Cloudflare configuration, so configuration backup works too. |
| Minimal, data only | A custom token with five permissions, each as Read: Account Settings, Workers KV Storage, Workers R2 Storage, D1 and Secrets Store. | Your data only. Configuration, Workers, Stream and Images backup stay unavailable until you widen the token. |
Set an expiry of 90 days or less. Your engine refuses a token with no expiry, and a token that expires more than 90 days away (discoveryTokenExpiryVerdict, engine/src/admin/cf-api.ts; DISCOVERY_TOKEN_MAX_DAYS, engine/src/admin/discovery-health.ts).
Your engine checks the token with Cloudflare before it stores it. Your engine refuses a token that sees no account, too. It keeps the token until you remove it, and it never shows the token again. See Cloudflare token scopes and connecting a source for what the token can reach.
The access key for your backup bucket
Destination asks for this key. It is the one credential that depends on where your archives go. Any one of four stores will do: Cloudflare R2, an S3-compatible store, Google Cloud Storage or Azure Blob Storage.
| Store | What to make |
|---|---|
| Cloudflare R2 | In the dashboard, open R2, then Manage R2 API Tokens. Make a token with Object Read and Write for this bucket only. |
| S3-compatible | An access key ID and secret access key with read and write on this bucket only, from your provider. |
| Google Cloud | An HMAC access key ID and secret. |
| Azure Blob | The storage account name, and an access key, a SAS or a client secret. |
R2 is the quickest way, because it is in the same account. R2 itself is not required. If you archive to Amazon S3, Google Cloud Storage or Azure Blob Storage, you do not need R2 at all. The engine’s R2 binding is optional and ships commented out in its own wrangler.toml. A run lands wherever the destination you save points.
Your engine checks the key before it stores it: it writes a test file to your bucket, then reads it back. Creating the destination credential has the steps for each provider.
The deploy token
Apply asks for this token. Make it from the “Edit Cloudflare Workers” template, and limit it to this account. Add D1 Edit when you protect a D1 database. Add Secrets Store Edit when you protect a Secrets Store secret. Set the shortest expiry the dashboard offers (deployTokenPermissions, console/src/lib/setup-flow/inventory.ts).
Apply uses the token once. Your engine installs your keys with it, then attaches the sources you picked. The engine does not keep the token, so setup asks you to revoke it in the Cloudflare dashboard straight afterwards (applyWithDeployToken, console/src/lib/setup-flow/actions-apply.ts).
You can apply without a deploy token. Apply also offers “My own wrangler or CI”, which lists the secrets and the binding stanzas for you to deploy yourself. The first run page covers both routes.
The engine check
Welcome checks your engine before Start works. The check asks the engine for its 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. When it fails, Welcome names the cause and offers “Check again”:
| What Welcome says | What it means |
|---|---|
| The console could not reach your engine. | No answer came back. Check that the engine is deployed. |
| Your engine answers but reports that it is not healthy. | The engine answered, and its own logs hold the reason. |
| Your engine answers, but not to this signed-in browser. | Health answered and the signed-in read did not. Check your Cloudflare Access policy and the engine’s CONSOLE_ORIGIN. |
Welcome also names an unusual sign-in. A session from a recovery code or from the admin token gets its own line, because each one needs a follow-up.
Cloudflare charges you for what this uses
downpipes is free software and we take nothing from you, but it runs in your own Cloudflare account, so Cloudflare bills you directly. The Workers Paid plan above is a floor, not the whole cost: on top of it you pay Cloudflare’s ordinary rates for the Workers requests and Durable Objects the engine runs on, and for the archive storage itself, including the operations each run performs against it. Backing up more data, more often, and keeping it for longer all cost more, and a verify or restore reads those objects back.
We add no markup and see none of it. What downpipes itself costs is a separate and much shorter answer, on licensing and editions: Community is free forever. We sell Business through a Stripe checkout, but never Enterprise, Custom or MSP / MSSP, which we quote and invoice. Work out what this will cost against Cloudflare’s own current rates, for the data you intend to back up. Use the frequency and retention you intend to keep. Only you know your volumes, and Cloudflare’s rates are theirs to change, so we do not restate them here.
The console does project storage and read cost, but do not lean on it as your budget. Before you have runs, it starts from default figures that you can edit. It is a planning estimate rather than a spend cap. What it is good for, once you are running, is spotting read amplification and the cost of a retention change. That is covered in predicting storage cost.
The two optional add-ons that never block
Two add-ons are not on Welcome, and setup never waits for either of them. Finish lists both as optional hardening suggestions, after your first backup. You can set them up then, later, or not at all.
| Optional add-on | What it gives you | When you would set it up |
|---|---|---|
| Cloudflare Access | Single sign-on or IP gating in front of the console. Free for up to 50 users. | When you want your identity provider, or an IP allowlist, in front of the console. In Zero Trust, create an Access application for the console’s address, then set the Access variables at deploy. |
| Outbound email | Lets the engine send alert, expiry, invite and custody-share emails. | When you want notifications. Onboard your sender domain in the dashboard under Compute, Email Service, Email Sending, then set EMAIL_FROM at deploy. Invite emails also need INVITE_EMAIL_FROM. The walkthrough is on outbound email. Without it the console still works, but the engine cannot send email. |
Passkeys are a complete alternative to Access
You do not need Cloudflare Access to protect the console. Passkeys need no setup at all and are a full alternative for guarding access to the console. If you would rather not stand up an Access application, sign in with a passkey instead and skip Access entirely. Access and passkeys both protect the front door; you choose one, both, or, during evaluation, neither. The engine still enforces roles on every privileged call regardless of which front-door control you pick.
Optional means optional
Setup never waits for Access or for outbound email. If you are evaluating downpipes and want the shortest path to a first backup, make the three credentials and the Workers Paid plan your only preparation. Leave Access and email for later, and protect the console with a passkey.
What your engine checks for itself
The manual preparation above is the exception. Setup reads every step’s progress from facts your engine reports, so a step your engine has already done reads as done.
After your first backup, Finish offers “Check my engine” under its hardening suggestions. Once setup is complete, the command palette offers “Check engine wiring” as well. Both open a read-only list called “What your engine reports”. The first row is always the keys: present, or not installed. After it comes each preflight item the engine has verified or has seen fail, failures first (readEngineChecks, console/src/lib/setup-flow/actions-apply.ts).
An item the engine has not observed is left off the list, never shown as a false pass. Items you will often see include “Durable Objects (scheduler authority)”, “Reconciliation cron” and “Sliced runs (large environments)” (engine/src/admin/preflight-probes.ts). Across the console, coverage and posture show an unverified state as unknown, not green.
You are deployed into your own account
One framing that matters before you start: downpipes is deployed into your own Cloudflare account, and you reach the console on a custom domain you control. There is no shared service and no vendor-hosted address. The console talks only to the engine that sits in the same account, on the same origin, so during setup there is no separate host and no credential to enter to reach the engine itself.
Because the address is yours, examples in this documentation use a custom domain such as console.example.com. Your real console address is whatever custom domain you map at deploy time. You will never reach a working console at a workers.dev address; that is a build artefact, not a customer endpoint.
What to have on hand
When you sit down to run setup, have these ready:
- Dashboard access to turn on the Workers Paid plan. Every install needs it.
- The three credentials, or the access to make them. The read-only API token, the access key for your backup bucket, and the deploy token. You can make each one when its step asks for it. Connect and Apply link to the Cloudflare API Tokens page, and Destination links to R2 API tokens for an R2 bucket.
- A bucket you own that holds nothing else. Destination lists your R2 buckets once Connect has run, and you can also type a bucket name.
- Somewhere offline to keep one file. Keys makes a break-glass private key,
identity.key, in your browser. Decide before you start where it will live: a password manager, an encrypted drive with a printed copy, or custodians who hold shares of it.
That last point is the one piece of preparation people skip and regret. The break-glass key is the only thing that can recover your backups on its own. The engine never holds it, and it is made in your browser.
Where this fits
Run the quickstart
The hands-on path from a fresh deploy to a proven first backup, in setup’s own order.
How the first run works
Each setup step, what it asks and why, the receipt, and how setup progress comes from engine facts.
Token scopes
What each Cloudflare token can reach, and why the deploy token is used once and revoked.
The key ceremony
What the in-browser ceremony generates, the files it produces, and why the break-glass key stays offline.
What it costs
The commercial side of the same question: what downpipes itself costs, and how you pay for a paid plan.
Last updated .