Deploy the engine and console into your own Cloudflare account

This is the first-deploy walkthrough for standing the engine and console up in your own Cloudflare account, from an empty account to a working engine that reports ready: true. It is for the operator who runs the deploy: an SRE or platform engineer with access to the Cloudflare account, working from a trusted machine.

A deploy writes a Worker, so it is one of the two deliberate operator command-line actions in downpipes (the other is an upgrade). A first install runs that one action twice, once in the engine checkout and once in the console checkout, because they are separate Workers in separate repositories. Everything after both deploys, attaching sources, setting a destination, running a restore, is done from the console with no terminal. The guided deploy script front-loads as much as it can: on a fresh engine it generates your keys on your own machine, installs the public halves as secrets, drops the offline recovery key into a local folder, and asks once how you will claim the first Owner. This page is the written reference behind that flow; the console mirrors the same steps interactively.

Prerequisites

Confirm all of these before you deploy, rather than discovering a gap from a failed run later. The engine’s own preflight (downpipe preflight before deploy, and GET /admin/preflight after) verifies most of them, but the plan and the domains are yours to arrange first.

openssl s_client -connect console.example.com:443 -servername console.example.com -tls1_2 -cipher 'AES128-SHA:@SECLEVEL=0' </dev/null

openssl s_client -connect console.example.com:443 -servername console.example.com -tls1_2 -cipher 'ECDHE:@SECLEVEL=0' </dev/null

The deploy, step by step

1. Get the source

   The engine and the console are separate repositories, published at github.com/downpipes-io, and you deploy each into your own account. Clone both before you start this page:

   git clone https://github.com/downpipes-io/engine
   git clone https://github.com/downpipes-io/console

   They are source-available under the Elastic License 2.0, so your security team can read exactly what will run in your account before you deploy it. downpipes-io/downpipe is a third, separately published repository and is not part of this: it is the MIT-licensed Go offline reader you use to recover archives with no engine and no vendor in the loop, covered in break-glass offline recovery.

   Check out the release tag named on the changelog rather than an arbitrary branch tip. Run npm run deploy from that checkout. For a source-available product this is what deploying the release means: npm run deploy always builds from the checkout in front of it.

   The release workflow builds the signed channel’s artefact from the tagged commit. The build is reproducible: a rebuild of the tagged source gives the same bytes, which verify a release shows how to check. There is no separate “download the pre-built release” step to look for.

2. Create a scoped, short-lived deploy token

   Create a Cloudflare API token scoped to the single account you are deploying into, to the relevant zone for the DNS record, and ideally to the named scripts. Give it a short expiry as a backstop. This token can write Workers, create KV namespaces and R2 buckets, write Secrets Store entries and edit DNS, so it is powerful and short-lived by design. The permission list is on the deploy token scopes page.

   Export it for this deploy session only, alongside your account id, and never write it to a file that outlives the session:

   export CLOUDFLARE_API_TOKEN=<the token>
   export CLOUDFLARE_ACCOUNT_ID=<your account id>

   The token stays on this machine and is sent only to api.cloudflare.com. It is never sent to the vendor and never pasted into the console for routine use. You will revoke it in the final step.

3. Set the console origin

   The engine scopes its CORS to your console’s origin. In the engine’s wrangler.toml, set CONSOLE_ORIGIN to your console’s custom domain so the browser is allowed to call the engine:

   [vars]
   CONSOLE_ORIGIN = "https://console.example.com"

   Leave the source bindings out of wrangler.toml. The engine declares no sources there on purpose, because you attach every source from the console later, and the deploy path preserves them. The reasoning is on the deploy safety and bindings page.

4. Deploy with npm run deploy

   Always deploy the engine with npm run deploy, never a bare wrangler deploy. The npm script runs a binding reconcile (scripts/sync-bindings.mjs) before it deploys, which reads the live worker’s bindings and deploys a superset, so a code deploy can never silently drop a source you attached from the console. A bare wrangler deploy would replace the worker’s binding set with exactly what wrangler.toml lists, dropping every console-attached source. This matters on every later deploy, but it shapes the first deploy too.

   On a first deploy nothing is attached yet, and the reconcile handles that by itself: it sees the worker does not exist, reports that there is nothing to preserve, and continues. So the command is just:

   cd engine
   npm run deploy

   Do not reach for DOWNPIPE_ALLOW_BINDING_RESET

   You do not need DOWNPIPE_ALLOW_BINDING_RESET=1 on a first deploy, and you should not learn it as part of one. That flag does not mean “allow an empty reconcile”. It means “if I cannot read the live bindings, deploy anyway”, so on a later redeploy, when the reconcile cannot read them (an expired or revoked deploy token, for instance), it ships wrangler.toml as-is and silently drops every source you attached from the console. Leave it unset and let a failed reconcile stop the deploy, which is the behaviour that protects your sources.

   The deploy creates the downpipe-engine Worker, the scheduler Durable Object, the per-run seal Durable Object, and the */15 reconciliation cron that drives new runs. The console is a separate repository with its own deploy, and its wrangler.toml pins a route you must change to your own custom domain. For the full rationale and the recovery path if a source ever goes missing, see why never a bare wrangler deploy.

5. Let the deploy generate your keys on this machine

   On a fresh engine (when the signer secret is not yet set), npm run deploy generates the full default key set on your own machine, using scripts/generate-keys.ts. Nothing is sent to the vendor at any point. The key material it produces has very different custody.

   The signer key pair (Ed25519 with ML-DSA-87) signs every run. Its private half is installed to the engine as the SIGNER_PRIVATE secret. The break-glass recipient key pair (X25519 with ML-KEM-1024) is what archives are sealed to. Only its public half goes to the engine, as BREAK_GLASS_PUBLIC; the private half is your offline recovery key. The operational recipient pair exists only if you choose the two-recipient posture, and then the engine holds both halves.

   In both postures it also generates the configuration recovery key pair and the configuration wrap key, and installs them to the engine. The configuration recovery private opens only this engine’s own sealed configuration export, never an archive. The wrap key encrypts the credentials the engine stores. Neither is written to the recovery kit.

   It buys less than the name suggests: it buys the UNATTENDED work, the scheduled restore tests, the scheduled drills and the in-account retention pruning that need a key at a moment when nobody is present to supply one. Verification at seal and the hourly canary do not need it. Nor does an in-console restore, which works in either posture; without the operational key you supply your break-glass key to the browser for that restore and it is wiped when the restore finishes.

   Both paths ask you to choose a posture before they generate any key, and neither lands you in the two-recipient posture unless you choose it. Strict break-glass-only custody, where the engine holds no key that can read an archive, is where a terminal deploy lands by default: a bare Enter keeps it at the npm run deploy prompt. The console has no default and waits for you to choose, with break-glass-only listed first. The operational key is something you opt into on either path. You can relax break-glass-only later with no re-key, because the Keys screen adds an operational key; the reverse does not fully undo, because archives sealed while that key was present stay readable by it.

   The script installs the public and signer-private halves as Worker secrets for you, then writes the things you must keep into a local ./recovery-kit/ folder:

   recovery-kit/identity.key          the break-glass PRIVATE key: the only thing that can decrypt an archive
   recovery-kit/recovery-sheet.txt    a printable sheet: public fingerprints and custody notes
   recovery-kit/recipient.pub         the break-glass PUBLIC key, safe to keep anywhere; the engine has it
   recovery-kit/signer.pub            the signer PUBLIC key: keep it, the reader refuses to run without a pinned signer

   Two of those four are must-keeps and they are must-keeps for different reasons. identity.key is the only thing that can decrypt an archive, and signer.pub is the only thing that can verify one. downpipe verify and downpipe restore both refuse to run without a pinned signer, and --allow-unverified downgrades a bad signature rather than waiving that, so it is not a way out. The printed sheet carries its fingerprint, not the key. From engine 0.3.6, the bucket holds a copy of the current signer’s signer.pub that the sheet’s fingerprint can pin (reader 0.3.4, --signer-fingerprint). A bucket from an older engine has no copy, and after a re-key the copy is the new signer’s, so keep the file.

   The engine never sees identity.key. There is no upload path for it anywhere, and there is no server-side copy.

6. Move the recovery kit offline

   This is the one irreversible custody step, so do it deliberately. Move the recovery-kit/ folder to offline storage (an encrypted USB drive, a corporate password manager, a printed sheet in a safe) and remove it from this machine. Move the whole folder rather than the key alone. identity.key is the only thing that can decrypt your backups if the engine or the account is ever lost, and signer.pub is what the reader checks their signatures against. The engine cannot regenerate identity.key. The bucket holds only the current signer’s signer.pub, so the kit file is the only copy for runs sealed before a re-key. downpipe restore refuses to run without the key and a pinned signer. Consider splitting custody across more than one holder; the console’s Keys screen explains the M-of-N pattern.

   The break-glass private key opens your archived data offline. It differs from the admin recovery codes you save in a later step, which are only for signing back in to administer the engine.

7. Set a one-time admin token to bootstrap the first owner

   The admin token is a one-time bootstrap credential for claiming the first Owner. It is the lower-assurance break-glass path: anyone with the engine URL and the token can administer the engine, and a token caller is not attributable in the audit log, so you retire it as soon as a better path exists.

   This happens during Step 4’s npm run deploy, not as a separate manual step. When neither BOOTSTRAP_OWNER_EMAIL nor ADMIN_TOKEN is already set, deploy.sh prompts you to choose: an emailed set-up link, or a no-email admin token. On the admin-token path the script generates the value itself with openssl rand -base64 32, sets it as the ADMIN_TOKEN secret, and prints it once:

   First-Owner set-up. Choose how you will claim the first Owner account:
     1) Email link  (needs Cloudflare Email Sending)
     2) Admin token (no email; one-time break-glass bearer)
   Enter 1 or 2 [2]:

   Store the printed value in your secrets manager; wrangler never echoes it, and no copy exists to recover later. The first Owner is claimed once and once only: the engine latches a flag the moment the first Owner exists, so the token can never mint a second Owner afterwards, even if the role table is later emptied.

8. Deploy the console

   Nothing so far has put a console in your account, and the next step opens one, so deploy it now. The console is a separate repository and a separate Worker on its own custom domain, with a service binding to the engine. Set the custom-domain route in console/wrangler.toml to the same domain you put in the engine’s CONSOLE_ORIGIN in step 3, then deploy from the console checkout:

   cd console
   npm run deploy

   npm run deploy here is the console’s guided scripts/deploy.sh: it builds the single-page app into public/app.js, runs a blocking preflight (typecheck, validate, lint) that stops the deploy on any failure, then runs wrangler deploy against console/wrangler.toml. Never deploy the console with a bare wrangler deploy, which skips that preflight. This is the deploy an assistant can safely run for you, unlike the engine’s; see deploying with an AI assistant below.

   Unlike the engine, the console has no keys, no secrets and no source bindings of its own, so redeploying it is not the hazard a bare engine deploy is. The full runbook, including the licence pin note, is on self-host.

9. Claim the first Owner, enrol a passkey, and save recovery codes

   Open the console you just deployed and sign in once with the admin token to claim the first Owner. Then either register your Owner passkey or claim the first Owner through Cloudflare Access. When you complete passkey enrolment the console shows you a set of recovery codes, once. Save them offline immediately, the same way any application’s recovery codes are saved. The engine stores only salted hashes of them, never the codes, so there is no way to see them again later; if you lose the set you regenerate a fresh one, which invalidates the old.

   These recovery codes are your ongoing admin break-glass: if you ever lose your passkey, you enter a code at the sign-in screen to get back in, then enrol a new passkey and regenerate the codes. Recovery-code sign-ins are hard rate-limited and every attempt is audited, so misuse is loud.

   Your keys already exist by the time you sign in here, because the deploy generated them. The console’s own first-run ceremony, and the custody posture you have landed in, are set out in which ceremony generated your keys.

10. Confirm ready:true

    Check GET /admin/status (the console’s setup reads it for you). The engine reports ready: true once the signer is present, the break-glass public key is present, and a destination resolves. If you set the destination from the console rather than in wrangler.toml, the status reflects that console-set choice, exactly as a run would resolve it.

    GET /admin/status

    {
      "service": "downpipe-engine",
      "engineVersion": "<version>",
      "signerConfigured": true,
      "breakGlassConfigured": true,
      "operationalConfigured": { "public": true, "private": true },
      "destConfigured": true,
      "destKind": "r2",
      "ready": true
    }

    Field	Meaning
    signerConfigured	The SIGNER_PRIVATE secret is present. Presence only, never validity: a malformed value still reads true here, and preflight is what parse-checks it.
    breakGlassConfigured	The BREAK_GLASS_PUBLIC recipient key is present.
    operationalConfigured.private	The operational private half is present, so the engine can run drills and restore tests unattended, and restore with no key from you. Its absence is a deliberate higher-assurance posture, not a fault.
    configKeysConfigured	From engine 0.3.6: whether CONFIG_RECIPIENT_PRIVATE (recipient) and CONFIG_WRAP_KEY (wrapKey) are present. Presence only. The Keys screen reads it to offer the add for an engine keyed without them.
    destConfigured / destKind	A destination resolves, and which kind. An ambiguous configuration (both an R2 binding and S3 settings with no DEST_KIND) reports not configured rather than guessing.
    ready	True when the signer, the break-glass public key and a destination are all present. This is the minimum to run a backup. The licence and update channel are not part of it.

    The status response never returns a secret, a key fingerprint, a destination endpoint or a downpipe name. It is presence booleans, the destination kind, the engine version and a count, so it is safe to poll during setup.

11. Probe the live prerequisites with preflight

    Where status reports presence, GET /admin/preflight probes the runtime prerequisites live and affirmatively. It does a real Durable Object round-trip, confirms the cron has genuinely ticked recently, does a read-only existence check against the destination to prove it is reachable and authorised, parse-checks the keys, and enumerates every configured source binding to confirm it is present. Each item is verified, configured, unconfigured or failed, with the observed evidence and a remediation that names the Cloudflare product to enable. Do not consider the deploy finished over a red required item.

    GET /admin/preflight

    One item is not directly observable from inside a Worker: the Workers plan itself, because the engine holds no account API token to introspect it. Preflight says so, and names the deploy-time gate that covers it (the deploy refuses the configured CPU limit on an unpaid account).

12. Revoke the deploy token

    As soon as the engine is confirmed healthy, revoke the deploy token from the Cloudflare dashboard. After this the system runs with no Cloudflare API token anywhere: the engine holds none by design, and there is no stored deploy credential left to leak. You re-create the same scoped token only when you next deploy, upgrade, or rotate a secret, and revoke it again each time. The deploy capability is never left standing.

Which ceremony generated your keys

There are two real ways a downpipes engine can come by its keys. A first-time reader can meet both without being told they are alternatives. This section is the reconciliation, because picking the wrong one is the most expensive mistake available on this page.

The on-machine path, which is the one you just took. On a fresh engine, before the SIGNER_PRIVATE secret is set, npm run deploy generates the full key set on your own machine. The same command installs the halves the engine needs. Nothing is sent to the vendor.

The in-browser path, which is the console’s setup. Setup’s Keys step generates a key set in the tab. Its Apply step installs the set to the engine with one deploy token that you paste. It is the path for an engine that has no keys yet. The Keys screen keeps the same ceremony afterwards for rotation and for an M-of-N custodian split.

From console 0.2.7 the in-browser set also includes the two configuration keys, which install straight to the engine with the signer key and are never files. An engine that console 0.2.6 keyed gains them from the Keys screen (“Add configuration keys”).

The byte formats are identical, so a key from either path is read the same way by the engine and by the offline reader. What is not interchangeable is the key material itself.

Both paths ask, and neither installs an operational key unasked

This is the choice that decides what your engine can read, and neither path lands you in a posture you did not choose.

Strict break-glass-only custody, where the engine holds no key that can decrypt an archive, is the stricter posture, and both paths put it first. npm run deploy asks before it generates anything: Enter 1 or 2 [1], where 1 is break-glass-only and a bare Enter keeps it. With no terminal attached it takes break-glass-only and says what it skipped. From engine 0.3.6 a later npm run deploy keeps that choice: the console ceremony records break-glass-only with the OPERATIONAL_RETIRED marker, and a deploy that finds keys but no operational key asks the same question rather than installing one. Only --enable-operational, --yes or typing 2 installs the operational pair, and that is the two-recipient posture: the engine can decrypt your archives, and so could anyone who took over your Cloudflare account. The step above spells out what the operational key buys, which is the unattended work only.

If you did choose two-recipient, leaving it is a switch rather than a re-key: choose break-glass-only on the console’s Keys screen and the engine’s operational secrets are removed. Runs sealed before you make that switch stay readable by the engine, because they were sealed to a key it still knows; removing the key does not retroactively protect them. The postures and what each costs you are set out in full on recovery postures.

After the deploy

Two follow-ups close out a clean deployment.

Retire the admin token and prefer attributable identity. Once your Owner passkey works (or Cloudflare Access is wired) and your recovery codes are saved, dispose of the bootstrap token. You can retire it in the console’s Security Centre, which is immediate and needs no redeploy: the engine stops honouring the token bearer the instant you retire it. With dual control on, the retire waits for a second Owner’s approval. The engine cannot delete its own Worker secret, because by design it holds no standing Cloudflare token, so the retire flag is how it stops honouring the string; deleting the secret with wrangler is the equivalent. The engine refuses to retire the token until a way back in exists (recovery codes for an Owner, or a second Owner; see creating a second Owner from the admin token if the original Owner’s passkey and codes are both gone), so disposing of it can never strand you.

The amber shared-token verdict shows only for a caller that presents the admin token. A passkey or identity-provider sign-in shows its own verified verdict. To put Cloudflare Access in front of the engine as well, follow the procedure on the identity and access page.

Expect email to be inert until you onboard a sending domain. Outbound engine email (alerts, expiry warnings, the role-invite, the first-run set-up link) needs Workers Paid plus a separate send-email binding and dashboard onboarding of a verified sender domain. Until you complete that, every send is a clean, logged no-op rather than an error: notifications simply skip the email channel. So do not treat a quiet inbox after the first deploy as a fault; it is the fail-open default until you enable sending. The mechanics are covered in the day-2 notifications material.

[[r2_buckets]]
binding = "DEST_R2"
bucket_name = "<your-archive-bucket>"

Deploying with an AI assistant

These docs are served as an MCP server at https://docs.downpipes.io/mcp, so an MCP-compatible coding assistant can use its search_docs tool to find and quote the right step here rather than guess at it. The index is a crawl of the published site and can lag a recent edit by hours, so if a search result and this page differ, follow this page. There is a copy-paste prompt on the deploy page of the website that sets this up for you.

An assistant is useful here, because most of a deploy is repetitive command-line work. But do not let an assistant run the engine’s first deploy: the script writes your break-glass private key and prints an owner-equivalent token.

An assistant can safely do these. Run npm ci in each checkout, confirm npx wrangler whoami points at the right account, show you the wrangler.toml changes you need (the console’s custom-domain route, the engine’s CONSOLE_ORIGIN, and your destination), and deploy the console with npm run deploy.

Run these yourself, and do not delegate them.

• The engine’s first deploy. On a fresh engine, npm run deploy generates your keys on this machine and writes the break-glass PRIVATE key to recovery-kit/identity.key. It also prints a one-time, owner-equivalent admin token to the terminal, and it asks you an interactive question about how to bootstrap the first Owner. Run it in a terminal you control. Anything an assistant runs, it can read.
• The recovery kit. Tell your assistant never to read, copy, print or commit anything under recovery-kit/. That break-glass key is your universal way back into your archives, the one that still works when every other system is gone, and it belongs offline with you.
• The admin API. Do not have an assistant call /admin/*. The only credential it could authenticate with is your admin token, which resolves to Owner unconditionally. Finish in the console instead: the destination, your sources, your downpipes and notifications are all console screens.
• The dashboard steps. Onboarding the sending domain under Compute, Email Service, Email Sending, and creating the Zero Trust Access application, are browser tasks. An assistant should give you the exact clicks and then wait for you to confirm each one is done.

The order to work in is the order of this page: clone, install and configure, run the engine deploy yourself and move the recovery kit offline, deploy the console, then bootstrap the first Owner in it, and attach a destination and sources from the console. The console deploy comes before the Owner bootstrap because the bootstrap is done in the console. There is nothing to open until it is deployed. Outbound email and Cloudflare Access are configuration you add to a working engine afterwards, so leave them until the engine reports ready: true.

Where this fits

This page is the spine the operations overview hands off to. The closing checks of this page, ready: true, a green preflight and the follow-ups, are consolidated with the first run and the restore drill on the verify your installation checklist.

For the token permissions and the create-use-revoke lifecycle, read deploy token scopes. For why npm run deploy is mandatory and how the reconcile keeps your sources, read deploy safety and bindings. To retire the admin token and wire Cloudflare Access once a passkey works, see identity and access. To choose between the routeless and split layouts, see topology. The conceptual grounding for the keys you generated here is in the key ceremony and recovery kit.

Last updated 25 September 2026.