Operations and self-hosting: running your own downpipes engine
downpipes is a self-hosted backup and recovery engine for the Cloudflare data and configuration layer. You deploy it, and a console, into your own Cloudflare account, and from then on the whole system is yours: the data it backs up, the keys that seal and recover it, and the Cloudflare account it runs in. This section is for the person who operates that deployment, whether you are an SRE standing it up for the first time, a reviewer checking how privilege is held, or the on-call engineer at three in the morning.
The defining property is the one to hold in your head before anything else. The vendor never holds your data, never holds your keys, and never holds a Cloudflare API token for your account. There is no inbound path from the vendor into your account, so for any given customer the production system is their own account, and the vendor cannot deploy for them, cannot read their backups, and cannot recover on their behalf. That is not a policy promise layered on top of the software. It is how the deployment is built, and the rest of this section is mostly an explanation of the mechanics that make it true.
Three mental models to start with
Almost every operating question becomes easy once these three are clear. Read them once here, and the rest of the section is detail.
The two-credential model
There are two quite different credentials in play, and conflating them is the most common source of confusion.
The first is a Cloudflare API token used to deploy and upgrade. It is powerful, because writing a Worker and creating bindings is a privileged act, so it is short-lived. You create it, use it on your own machine for the minutes a deploy takes, confirm the engine is healthy, and then revoke it. It does not live in CI, it is not pasted into the console for routine use, and it is never sent to the vendor. Between deploys there is no standing deploy token anywhere.
The second is the running engine itself, which holds zero Cloudflare API tokens. It reaches your data only through Worker bindings: a KV namespace binding, an R2 bucket binding, a D1 database binding, a Secrets Store binding, and its own Durable Objects. A binding is the capability itself, scoped by the platform to exactly the named resource, so even a full compromise of the running Worker yields only what its bindings grant and never the ability to enumerate or rewrite the wider account. This is what the no-custody guarantee rests on at runtime, and the Cloudflare token scopes page is the evidence a reviewer wants.
Separate from both is the offline break-glass private key. It is generated on your own machine (or in your browser during the key ceremony), and it is the one key that recovers every backup the engine ever writes. It is never transmitted to the engine or the vendor. There is no engine binding for it. Where you do enter it in the browser, during the key ceremony, an in-console break-glass restore, or a split-key reassembly at /restore/recover-key, it is read locally and never uploaded, and only a per-run key for the archive being recovered reaches your own engine. Keeping the private in the browser that way is defence in depth for your own account, not the no-custody line, which is simply that the vendor holds nothing. The key ceremony and recovery kit page covers how it is born and where it should live.
No customer command line, scoped correctly
Day-2 operations are deliberately terminal-free. Attaching a source, setting the destination, running a restore, reviewing the audit log, predicting cost: every one of those is a portal action, and the portal completes the privileged step itself by collecting a scoped one-shot token in the browser when one is needed. You are not expected to open a terminal to operate the product.
The two exceptions are deliberate and are operator actions, not customer-portal actions: the first deploy of the engine and console, and a version upgrade. Both write a Worker, which is an act that lives with the operator and their own credentials on a trusted machine, not in a web form. So when you read “no command line” in these docs it means day-2 operations in the portal, and the first deploy and upgrades and rollback pages are honest that those two are CLI steps you run yourself.
What ready:true means, and what never gates a backup
The engine reports ready: true from GET /admin/status once exactly the minimum to run a backup is configured: a signer secret is present, a break-glass recipient public key is present, and a destination resolves (an R2 binding, or the S3-compatible settings). Until then the engine accepts admin calls but will not run a backup, which is the honest “not configured yet” state rather than a silent failure later.
Two things are explicitly outside that minimum. The assurance licence and the signed update channel are both optional, and neither ever gates a backup or a recovery. A backup and recovery product must never hold your data hostage to a subscription, so the engine enforces none of its data paths against the licence, and the offline recovery tool never reads one. If the licence lapses, backups, restores and the offline tool keep working unchanged; what changes is the assurance and support tier, not your ability to recover.
A map of this section
This section is ordered roughly the way a deployment’s life runs, from first deploy through steady-state operation to the day something goes wrong, and then to the day you leave. Every page in the section is listed; the sidebar carries the same set.
| Page | What it covers |
|---|---|
| First deploy | The end-to-end first deploy: prerequisites, the scoped token, the mandatory npm run deploy, on-machine key generation, the bootstrap owner, and reaching ready: true. |
| Deploy token scopes | The exact Cloudflare API token permissions a deploy or upgrade needs, the create-use-revoke lifecycle, and the runtime-holds-no-token property. |
| Deploy safety and bindings | Why you always deploy with npm run deploy and never a bare wrangler deploy, the reconcile that keeps your console-attached sources, and how to recover a source that has gone missing. |
| Topology | The shipped routeless engine behind the console, and the split topology that gives the engine its own custom domain. |
| Identity and access | Retiring the bootstrap token, wiring Cloudflare Access, and moving from the amber shared-token verdict to the verified per-email one. |
| Upgrades and rollback | The operator-run upgrade runbook, what a rollback can and cannot undo, and the schema-epoch boundary that bounds it. |
| Incident response | The decision tree for an outage, a suspected compromise, or a lost credential, and why recovery never depends on the vendor. |
| Self-host runbook | The whole self-hosted lifecycle in one place, for an operator who wants the runbook rather than the walkthrough. |
| Scale and limits | The platform limits a large estate meets, and what the engine does at each of them. |
| Outbound email | How the engine sends invitations and alerts, and what it needs configured before it can. |
| Licensing and editions | What the assurance licence buys, what lapses when it does, and why no data path is gated on it. |
| Cloudflare config backup | Backing up your Cloudflare account configuration, and the deliberately out-of-band restore. |
| Config surface reference | The surfaces that backup covers, generated from the engine rather than kept by hand. |
| Recover downpipes itself | Rebuilding the engine and console from an archive when the account holding them is gone. |
| Account compromise | The eviction sequence for a suspected compromise, in the order that never strands you. |
| Offboarding and exit | The controlled exit: what to capture, what to remove, and the order that keeps recovery possible. |
| Activating updates | The one-time owner ceremony that switches the signed update channel on. |
| Applying updates | The day-to-day apply, the settle, and the four recorded outcomes including a rollback that itself failed. |
| Update trust and rollback | What the channel signature proves, and the recovery controls when an apply goes wrong. |
| Verify a release | Verifying a release’s provenance yourself, before you apply it. |
| Publishing releases | The vendor-side publish, for the operator who signs and ships a channel. |
Common entry points
If you have arrived here with a specific job in mind, start at one of these.
Deploy for the first time
The spine walkthrough: prerequisites, the scoped deploy token, npm run deploy, on-machine keys into the recovery kit, the bootstrap owner, and confirming ready: true.
Review the token scopes
For a security reviewer: the exact account-level permissions the deploy token needs, why each is there, and the proof that the running engine holds no Cloudflare token.
Something is wrong
The on-call decision tree for an outage, a suspected compromise, or a lost passkey, and the offline recovery path that needs neither the vendor nor Cloudflare.
Understand the trust model
The reasoning behind no custody: what the vendor can and cannot do, and why the architecture, not a promise, is what enforces it.
A note on what is running today
These pages describe the operating model for a customer deployment, which always lives in the customer’s own account. The vendor itself does not run a standing production downpipes instance on anyone’s behalf; there is a demonstration deployment and a small vendor-side control-plane for licensing, and that is all. When these pages say “your engine” they mean exactly that: the engine in your account, that you deployed, that only you can reach and recover. The licensing and editions material describes the one internet-facing component the vendor operates and how little it holds.
Where this fits
For the conceptual grounding behind the operating model, read the no-custody trust model and the key ceremony and recovery kit. To understand what a backup run actually does end to end, see the anatomy of a backup run. When you are ready to stand the engine up, start at the first deploy walkthrough.
Last updated .