External Cloudflare setup

For Shiplet platform operators—not reviewers or ordinary Shiplet owners.

This guide graduates the already-working managed static product to optional external Cloudflare capabilities. The Wizard never asks for a pasted API token, and optional failures never disable managed static review.

Return to managed publishing if you only need to publish or review a Shiplet.

Who acts	External change	Safe stopping point
Ordinary Shiplet owner	None	Stay on managed publishing; do not run this Wizard.
Authorized repository operator	Creates or updates named Workers, D1 databases, and narrow bindings	Decline any confirmation; the Wizard records an incomplete safe stop for resumption.
Cloudflare account administrator	Completes human-controlled provider login, verification, or policy	Stop before the ceremony; the existing managed product remains available.

npm run setup:external -- --help
npm run setup:external -- --preflight
npm run setup:external

Read help first, then run the value-free preflight before setup. Plan for 10 stages and about 135 minutes; the Wizard shows the remaining estimate at each stage. Preflight checks only local commands and locked repository files. It does not call Cloudflare, read a credential, or create the resume ledger or operator lock.

Run setup only from a clean checkout at a trusted release commit. The Wizard shows and confirms the exact commit before provider access. It is repeatable and resumable, but pauses before persistent access, DNS, OAuth promotion, policy acceptance, deployment, production smoke, and rollback.

After the separately confirmed named-profile OAuth proof, every deployment or recovery operation receives a public UUIDv4 operation ID before the first account-resource mutation. The local operator grant is not customer deployment authority. Worker versions use an operation-specific tag containing the trusted commit prefix and that operation ID. The ID and tag are recovery evidence, not credentials: a checkout refuses provider state from another operation even when both runs started from the same commit.

Prerequisites

• An intended Shiplet-owned Cloudflare account, exact public HTTPS origin, and permission to administer Workers, D1, and the public OAuth client.
• Bash 3.2 or newer, Node 22 or newer, npm, Git, and OpenSSL. Stock macOS /bin/bash is supported, and value-free preflight checks the same local prerequisites as guided setup.
• Repository-locked Wrangler 4.120.0. After exact-release approval, the Wizard asks before creating or re-authenticating the fixed shiplet-external-setup named profile through browser OAuth. Named profiles are experimental in this Wrangler release, so Shiplet pins and contract-tests it. Continuing replaces any profile with that name and requires OS-backed encrypted credential storage.
• Workers for Platforms is optional preparatory support infrastructure; paid Dynamic Workers through a Worker Loader binding are required for custom MCP.
• Domain-verification authority only when Cloudflare requires it. Shiplet never changes DNS ownership automatically.
• A captured previous main Worker version when production already has shiplet; a true first deploy instead uses a provider-disabled baseline with scoped removal recovery.

Shiplet states that managed arbitrary Worker execution remains unavailable in this release because the main kernel has no managed-runtime invocation entrypoint. WFP namespace provisioning cannot change that status.

Real service and binding contracts

Worker	Responsibility
shiplet-cloudflare-control-plane	OAuth, encrypted grants, temporary account, and claim custody
shiplet-managed-runtime-gateway	Customer health, preparatory WFP support, and custom MCP compartments
shiplet-deny-egress	Deny-by-default managed-code outbound policy

The main Worker receives five narrow entrypoints: CLOUDFLARE_OAUTH_CONTROL_PLANE, CLOUDFLARE_GRANT_VAULT_RPC, CLOUDFLARE_TEMPORARY_ACCOUNT_RPC, CLOUDFLARE_VERSION_HEALTH_RPC, and CLOUDFLARE_CUSTOM_MCP_RUNTIME_RPC. It intentionally receives no managed-WFP invocation entrypoint. The support Worker may bind shiplet-managed-staging and shiplet-managed-production.

Ten-stage contract

Stage 1: Preflight · Stage 2: Release artifacts · Stage 3: Runtime entitlements · Stage 4: Support services · Stage 5: PKCE client · Stage 6: Public promotion · Stage 7: Main bindings · Stage 8: Temporary claim · Stage 9: Isolation proof · Stage 10: MCP proof, deploy, and smoke

Stage 1: Preflight, authentication, and account

Prerequisite: clean checkout at a trusted commit; Bash 3.2 or newer, Git, Node 22 or newer, npm, and OpenSSL. The Wizard runs npm ci --ignore-scripts and uses only repository-local Wrangler and Vitest binaries before provider access. Mutation: after exact-release approval, an immediate confirmation creates or re-authenticates the persistent shiplet-external-setup named profile through browser OAuth in OS-backed encrypted credential storage. This local operator profile is separate from customer-owned deployment access, which still requires the public client and a later owner Connect action. Evidence: every Wrangler subprocess removes ambient API token, global API key, service-auth, issuer, and endpoint variables; supplies one empty environment file; and pins provider calls to the named profile. Project .env and .env.local cannot supply, restore, or override provider authentication. A temporary profile binding must return machine-readable OAuth Token identity and deactivate successfully before work continues. The Wizard then records the commit, exact selected account, app origin, and control-plane origin fence; all account-scoped resource mutations and status checks after selection are pinned. Stop or resume: changed fence values invalidate dependent flags, while first-time control-origin binding preserves same-run support evidence. The fence repeats before every source-derived Wizard mutation and before entering each human-controlled mutation ceremony. Emergency rollback validates the captured immutable Worker UUID and remains available after checkout drift.

Stage 2: Verify release artifacts

Prerequisite: Stage 1. Mutation: regenerates local client output but makes no external/provider mutation. Evidence: types, focused tests, build, three dry runs, and a repeated trusted-release fence. Stop or resume: any failure stops before resource creation.

Stage 3: Verify WFP and Dynamic Workers

Prerequisite: relevant entitlements. Mutation: none; dormant WFP namespaces are not created. Evidence: entitlement and existing namespace status. Stop or resume: missing WFP namespaces omit unused bindings without blocking OAuth or Dynamic Workers setup.

Stage 4: Deploy support services

Prerequisite: green artifacts. Mutation: confirmed D1 creation, additive migrations, three Worker deploys tagged with the exact trusted release commit, and direct-to-store control keys followed by a final trusted-tag control-plane deploy. Evidence: Cloudflare must machine-verify the exact D1 database bindings, no pending migrations, all three operation-tagged releases at 100% traffic, and both required secret names. A saved completion flag is not evidence; secret-list proof reads names and types only. Each newly bootstrapped secret is streamed directly to the secret store and its staged Worker version receives a unique operation-and-secret tag. If the command response is lost after Cloudflare commits, recovery accepts exactly one matching UUID from provider history, deploys and attests it at 100% traffic, and rejects missing, duplicate, or differently tagged candidates. Stop or resume: no separate WFP deployment credential is requested; Workers Scripts Write is account-level within a selected account, not namespace-scoped. Key rotation is not supported by this Wizard. It never replaces an existing key or cryptographic root. Missing keys with sensitive state fail closed, and a two-key first bootstrap additionally requires the bound database and Worker to belong to this exact operation.

Stage 5: Register the public PKCE client

Prerequisite: exact callback origin. Recovery boundary: before mutation, the Wizard persists durable recovery state for the affected support Worker. Recovery runs in reverse order: an existing Worker returns to its exact prior version and verifies 100% traffic; a first-deploy delete is armed only after machine-verified provider absence and can remove only this operation's exact tag or captured intermediate UUID. The ledger counts every changed first-deploy target and reports recovered only after the same count is machine-verified absent. Mutation: confirmed public-client creation and, when needed, a control-plane Worker redeploy with that exact public client contract; registration creates no customer grant. Evidence: S256, token authentication none, exact redirect and scopes. Stop or resume: mismatch stops before deployment; only when an owner connects does OAuth request account-level Workers Scripts Write for one selected customer account. Readiness defaults to disabled; after public proof, operator_smoke exposes Connect only to the exact operator until authorized provider smoke passes.

Stage 6: Verify domain and promote OAuth

Prerequisite: Stage 5 contract. Mutation: human-controlled DNS verification and irreversible promotion. Evidence: public and verified status. Stop or resume: customer connection stays unavailable otherwise.

Stage 7: Prove main-Worker bindings

Prerequisite: support Workers and trusted origin. Mutation: none. Evidence: verify one version receives 100% of each service's traffic, capture immutable Worker version IDs for all three support services, require the exact trusted-release tag, then pin the control-plane and runtime-gateway versions in a five-entrypoint dry run with runtime-consumed CLOUDFLARE_OAUTH_READINESS, intentionally without managed WFP invocation. Stop or resume: Stage 7 is compile-only; production is unchanged and live RPC execution is not yet proved.

Stage 8: Verify temporary preview and claim

Prerequisite: Cloudflare Temporary Accounts service availability; each preview creates a new temporary account rather than using the selected permanent account. Mutation: none during setup. Evidence: availability, one-time claim contract, and explicit CLOUDFLARE_TEMPORARY_ACCOUNTS_READINESS; both returned account and claim expirations must be present, future, and no more than 60 minutes away. Availability is not production readiness. Stop or resume: Stage 8 always leaves readiness disabled, so a broker binding cannot make the API or ownership UI appear ready; every real preview needs current policy consent. Cloudflare's documented create request has no documented idempotency field. A lost provisioning response remains a degraded unknown provider effect until expiry and is never described as reconciled cleanup.

Stage 9: Prove runtime isolation and egress

Prerequisite: deployed support services. Mutation: none. Evidence: fresh deployment status must match the three captured immutable Worker version IDs before isolation checks run. Stop or resume: missing Dynamic Workers yields runtime_unavailable; managed arbitrary execution remains managed_dynamic_unavailable.

Stage 10: Prove custom MCP, deploy, and smoke production

Stage 10A — conditional custom MCP proof: managed arbitrary application execution remains unavailable, but custom MCP uses the separate Dynamic Workers CUSTOM_MCP_LOADER contract. With the Worker Loader available, one harmless revision-scoped live invocation must run through the exact support release with denied egress while kernel tools remain intact. Without it, the same call must return runtime_unavailable while kernel tools remain available. Stage 10B — production deploy: green gates plus a validated previous UUID for an existing Worker. A failed lookup requires confirmation that the selected account has no Worker named shiplet before first deploy is armed. Mutation: Stage 10A is read-only. Stage 10B performs one confirmed provider-disabled baseline, isolated smoke data, independent exact-user OAuth and temporary-account operator_smoke proofs, and separately confirmed enabled deploys only after provider checks pass. Evidence: the conditional custom-MCP result and kernel continuity, then the authenticated /api/platform/support-contract check returning five exact live named entrypoint contracts at the captured support versions and release tag before operated product smoke. The same non-secret response must show credential continuity verified, scheduled reconciliation successful and fresh, and bounded cleanup, revocation, and temporary ambiguity backlogs at zero; otherwise health is degraded and production success is blocked. The revision ceremony must validate a draft, open the returned authenticated sealed preview, prove that the active tenant and active revision remain unchanged, and only then promote, verify activation, and roll back. Stop or resume: every deploy is persisted as ambiguous first. Authentication breakage, sibling access, data corruption, missing routes, contract mismatch, critical widget/MCP failure, or an ambiguous response automatically rolls back—or removes only a new first-deploy Worker. A recovered failure exits non-zero as Setup failed — recovery completed; an untouched decline is Setup incomplete — safe stop. Neither prints verified success.

Resume and secret boundary

The ignored .env.external-setup contains public identifiers and completion flags only. Never source or commit it. The Wizard rejects symbolic links, non-regular files, unknown keys, malformed records, oversized input, and control characters; reads use a no-follow descriptor and writes use an owner-only atomic replacement. Completion flags from a previous release commit are invalidated. The Wizard does not source or print .env, .env.local, .dev.vars, Wrangler credential files, or process-environment listings. Ambient API tokens and global API keys are removed and refused, and an explicit empty Wrangler environment file means .env and .env.local cannot supply or restore provider credentials. The dedicated local operator profile persists in Wrangler's OS-protected encrypted credential store, never in the repository or ledger; it is separate from customer-owned deployment access. Vite environment-file discovery is disabled for build and test checks. Generated keys stream to Cloudflare's secret store. The current release asks for no separate WFP deployment credential; the account-level customer OAuth grant is requested only when an owner connects one selected account. Credentials, OAuth codes, claim destinations, and authorization headers never belong in commands, logs, screenshots, public payloads, package code, or setup state.

Production evidence boundary

A green build, dry run, or Wizard stage is not production evidence. Keep a capability unavailable until its named services and bindings are deployed, the provider entitlement exists, the live five-entrypoint contract matches the captured immutable Worker version IDs and trusted-release tag, the production UI reports the expected state, and operated smoke passes. An OAuth or temporary binding alone never enables its surface: readiness is disabled, exact-user operator_smoke, or enabled only after separate proof and confirmation. Declining or failing a temporary check clears its operator and restores disabled.

Next: confirm the needed path in Deployment and ownership and review Security and isolation before running the Wizard.