Zephyr Cloud Docs

    Configure Cloudflare on Zephyr

    Originally launched as an email spam tracker, Cloudflare today offers extensive capabilities for users to register, manage domains as a registrar, and monitor, secure, and configure an entire IT infrastructure.

    In this guide, we'll walk you through configuring Cloudflare as your default cloud provider for deploying and versioning applications with Zephyr Cloud. This setup uses Cloudflare Workers, KV namespaces, exact Worker Custom Domains, and generated-host Worker Routes to deliver your content at the edge.

    Prerequisites

    Info
    • A registered Cloudflare account
    • A domain registered on Cloudflare, or a domain whose DNS can be managed by Cloudflare
    • A registered Zephyr Account

    SSR Worker (beta)

    Availability

    Zephyr’s SSR Worker runtime is currently beta and only available on Cloudflare using Zephyr’s default (managed) Cloudflare integration.

    It is not available on Bring Your Own Cloud (BYOC) deployments (including custom/non-default integrations).

    If you need SSR support on another integration or deployment target, send us a DM on Discord.

    Learn more: SSR Worker (beta).
    Using TanStack Start? See: TanStack Start.

    Configure and Enable Cloudflare

    Log in to the Zephyr Dashboard

    After signing in, select your organization.


    Locate Cloudflare under Deployment Integration

    • Select Settings from the top navigation tabs.
    • On the left sidebar, select Deployment Integration.
    • Choose Available to find Cloudflare, then click on Add integration.

    Complete Basic Info

    Enter the integration name and display name in 1. Basic Info, then click Continue to open 2. Configure Cloudflare. There is no DNS acknowledgment step.

    Zephyr Cloud now supports Cloudflare OAuth for deployment integrations. This is the recommended setup path because you authorize Zephyr in Cloudflare instead of manually copying a Cloudflare API token and Zone ID into Zephyr.

    After completing Basic Info:

    1. In 2. Configure Cloudflare, choose Automatic Setup and click Connect with Cloudflare.
    2. In Cloudflare, select the account that owns the zone you want Zephyr to use, review the requested permissions, and select Authorize.
    3. Return to Configure Cloudflare in Zephyr and wait for the authorized zones to load.
    4. Select the Cloudflare Zone, then click Continue. Loading, empty, expired, or unselected zones cannot continue.
    5. In 3. Configure Worker, choose the Worker name, delimiter, and three KV namespace names.
    6. Click Finish to provision and activate the integration using the selected zone and your latest configuration.

    Authorization connects your Cloudflare account; it does not provision the integration. Worker and KV configuration is entered after authorization and zone selection.

    Info

    Cloudflare shows the application name, publisher domain, account selection, and requested permissions before you authorize. Zephyr completes the OAuth exchange server-side, so Cloudflare access and refresh tokens are not exposed in your browser.

    You can review or revoke authorized OAuth applications from your Cloudflare profile. Cloudflare account administrators can also restrict public OAuth application access for their account. See Cloudflare's Authorizing an application guide for details.

    Manual API token setup

    Manual setup remains available if OAuth is unavailable for your account, blocked by your Cloudflare account settings, or your organization requires manually managed Cloudflare API tokens.

    For manual setup, you will need your Cloudflare Zone ID and an API Token:

    1. Complete 1. Basic Info and click Continue.
    2. In 2. Configure Cloudflare, choose Manual setup and enter the API token and Zone ID.
    3. Click Continue to open 3. Configure Worker.
    4. Choose the Worker name, delimiter, and three KV namespace names, then click Finish to provision the integration. Entering credentials or continuing does not provision resources.

    1. Zone ID

    • On your domain’s Overview tab, scroll down to the API section on the right sidebar.
    • Find the Zone ID in this section.

    2. API Token

    • Near Zone ID and Account ID, right-click on Get your API token to open it in a new tab.
    • Scroll to the bottom and select Create Custom Token by clicking on "Get started."
    • Give your API token a meaningful name (e.g., the purpose or creator).
    • Configure the required Permissions:
    ResourceResource TypePermission / role
    ZoneZoneRead
    AccountWorkersAdmin at the Workers product scope (creation and deployment)
    AccountWorkers KV StorageWrite (called Edit in legacy token screens)
    ZoneWorkers RoutesWrite (called Edit in legacy token screens)

    Cloudflare's current Workers roles and permissions require product-level Workers Admin to create a Worker; Editor can deploy an existing Worker. Still-supported legacy Workers Scripts Edit permissions may appear in older token screens and API references. They remain supported, but are not the only current permission model. KV write access is needed because Zephyr directly lists and creates namespaces, not merely because the Worker has KV bindings.

    Routes and Custom Domains require zone Workers Routes Write. Custom Domains do not currently support per-Worker roles. Scope access to the integration's account and zone; no Pages or DNS-write permission is required by this deployment flow.

    3. Zone Resources: When prompted, include a Specific zone under your domain

    • Leave other configurations (e.g., Account resources, Client IP Address Filtering) as defaults.
    • Scroll to the bottom and select Continue to summary to review your configurations, then Create Token. The token will display on the next page.

    4. Configure advanced certificate (optional: required if you want to use domains like *.ze.your.domain)

    • Go to SSL/TLS page and view Edge Certificates
    • Click on Purchase ACM and complete buying
    • Order/configure advanced certificate and add *.ze.your.domain into Certificate Hostnames, so complete list should look like your.domain *.your.domain *.ze.your.domain

    Configuration Inputs

    Details for each input after clicking Add Integration under Cloudflare:

    Setup Method

    Choose Automatic Setup to authorize with Cloudflare, or Manual setup to paste a Cloudflare API token and Zone ID in Configure Cloudflare.

    Integration Name
    A unique name within your organization, used as a slug.
    Integration Display Name
    The name of the integration shown on the dashboard.
    Delimiter

    In Configure Worker, choose - for *-ze.your.domain or . for *.ze.your.domain. The dot delimiter requires TLS coverage for the deeper generated hostnames.

    API Token

    Required only for Manual setup. Obtainable from Cloudflare. See instructions for creating your API token.

    Zone ID

    Required only for Manual setup. In OAuth setup, Zephyr lists the zones available to the Cloudflare account you authorized.

    Worker and KV Names

    In Configure Worker, configure the Worker and three KV namespace names. Defaults: ze-worker-for-static-upload, ze_envs, ze_snapshots, and ze_files. Worker names are saved with the ze- prefix. Use your configured names when inspecting or removing resources.

    Set Integration as Default

    When set as default, all Zephyr deployments will use this integration until a new one (default integration) is set.

    Worker Setup and Domains

    Only Finish provisions the configured public/static Worker, its KV namespaces, the exact base production Custom Domain, the base Worker Route, and the selected delimiter's generated-host Route. For a zone named example.com, all connections target that same Worker:

    ConnectionCloudflare objectValue
    Base upload/control endpointWorker Custom Domainze.example.com, enabled: true, previews_enabled: false
    Base upload/control endpoint RouteWorker Routeze.example.com/*
    Generated version, tag, and environment URLs (- delimiter)Worker Route*-ze.example.com/*
    Generated URLs with the . delimiterWorker Route (instead of the - pattern)*.ze.example.com/*
    Optional exact environment aliasWorker Custom Domainapp.example.com, enabled: true, previews_enabled: false

    Both Routes end in /*, which covers the root path, asset paths, and query strings. Setup does not create additional pathless generated-host Routes.

    Generated hosts need suitable existing proxied DNS coverage, as required by Cloudflare's Routes contract. Routes do not create DNS, and the exact base Custom Domain does not supply wildcard coverage. No prescribed DNS record target or DNS-write permission is required by this setup flow. The dot delimiter also requires a wildcard certificate for *.ze.example.com; the zone's usual *.example.com certificate does not cover those deeper hostnames.

    Cloudflare manages DNS and TLS for the exact base and environment Custom Domains and sends all paths to the Worker. In the environment's settings, enter an exact alias from the selected integration's zone, without a URL, wildcard, or /*. Normal hostname routing is enabled and native Cloudflare Worker-version previews are disabled. “Production” describes hostname traffic, not a requirement to name the Zephyr environment “production.”

    Zephyr publishes the hostname's environment-to-snapshot mapping through the normal deployment flow. An environment with no deployed version will not serve an application until its first deployment. DNS, TLS, and deployment changes may take time to propagate.

    Inspect these connections in the Cloudflare dashboard's Workers & Pages: choose your Worker, then Domains. Cloudflare also documents the alternate Settings → Domains & Routes navigation. See Routes and Custom Domains for the provider's routing details.

    An existing exact CNAME can prevent Custom Domain attachment. Explicitly resolve or migrate the conflicting record before retrying; Zephyr does not automatically remove customer DNS. Normal retry, redeployment, or Worker update creates or updates the base Custom Domain, base Route, and selected delimiter's generated-host Route. Existing Route-based environment aliases migrate when reconnected, not through an automatic bulk migration. Preserve suitable generated-host DNS coverage.



    Testing Cloudflare Integration

    Visit our recipes to test an application. Your next deployment should use your designated domain! (If not, talk to us on Discord).

    When using our managed cloud (Cloudflare) or custom Cloudflare integration, avoid including capital letters in names for package.json, module federation configuration, or assets to prevent issues with Cloudflare queries.

    Troubleshooting

    Cloudflare OAuth setup

    Cloudflare authorization was not completed

    If Zephyr says Cloudflare authorization was not completed, reconnect and try again. Confirm the browser completed the Cloudflare authorization flow and was not blocked by a popup, extension, or account access restriction.

    No Cloudflare zones found

    If Zephyr cannot find any Cloudflare zones after authorization, the Cloudflare account you selected may not have access to a zone. Add a zone in Cloudflare, ask an account administrator for access, or reconnect with a different Cloudflare account.

    Zones keep loading or OAuth is temporarily unavailable

    Reconnect with Cloudflare and try again; authorization returns to Configure Cloudflare, where you must select a zone again before continuing. Your entered basic and Worker settings remain editable for retry. To use Manual setup while an authorized setup session exists, reconnect first to clear that session. Contact us on Discord if OAuth remains unavailable.

    Revoke Zephyr access in Cloudflare

    You can revoke Zephyr's Cloudflare OAuth authorization from your Cloudflare profile's OAuth authorization management page. After revoking access, remove the affected deployment integration in Zephyr or reconnect it with Cloudflare.

    What Will Be Created on Your Cloudflare Account?

    When Cloudflare is added as your provider on Zephyr, these resources are created or reused with the configured names:

    1. KV Namespaces

    The default namespace names are:

    • ze_snapshots
    • ze_files
    • ze_envs

    2. Workers

    • The configured public/static Worker, defaulting to ze-worker-for-static-upload, uploads and serves assets.

    3. Worker Custom Domains and Generated Routes

    The exact base production Custom Domain, base Route, and selected delimiter's generated-host Route are listed in Worker Setup and Domains. Optional exact environment aliases are attached separately to the same Worker. Cloudflare creates DNS and TLS for exact Custom Domains; generated Routes rely on existing proxied DNS coverage. No Cloudflare Pages project is provisioned.

    Deployment and Inspecting Assets

    Once your first Cloudflare deployment is complete, you can inspect assets.

    In your Cloudflare dashboard, navigate to Workers & Pages and then KV to view assets under ze_files.

    Info
    • ze_files stores assets.
    • ze_envs stores hostname/environment pointers to the active snapshot.
    • ze_snapshots stores immutable snapshot metadata.
    • If deploying an application previously on our managed cloud, run rm -rf ~/.zephyr before deployment.
    • If you encounter issues deploying Micro-frontend applications, see our Micro-frontend deployment guide.

    Clean Uninstall and Reset

    Warning
    • Zephyr Cloud does not manage deletion of API tokens or any Cloudflare account properties.
    • For OAuth-created integrations, revoke Zephyr from Cloudflare if you also want to remove the Cloudflare-side authorization.
    • Assets and information on your Cloudflare account are immutable by default. During a clean uninstall, previously deployed assets and information are unrecoverable.

    To delete an existing Cloudflare integration, follow these steps:

    Delete the Worker and Environment Connections

    1. Disconnect environment custom domains in Zephyr before deleting the integration. This detaches their owned Custom Domains without removing the base production Custom Domain or generated Routes.
    2. In Cloudflare, open Workers & Pages, select the configured public/static Worker (default ze-worker-for-static-upload), and review Domains (or Settings → Domains & Routes) for the exact base and environment Custom Domains, base Route, and selected delimiter's generated-host Route.
    3. Delete the Worker using its settings. Do not delete a shared Worker still used by another integration.

    There is no Cloudflare Pages project to delete. Review unused DNS records and certificates separately; detaching a Custom Domain does not automatically delete its certificate.

    Delete KV Namespace

    1. In Workers & Pages, select KV.

    2. Locate the configured namespaces (defaults: ze_envs, ze_snapshots, ze_files) and delete them only if they are no longer shared by other integrations.

    Review Worker Domains and Routes

    1. On the configured Worker's Domains page, review the exact ze.<zone> base production Custom Domain and any remaining exact environment aliases.
    2. In the zone's Workers Routes, review ze.<zone>/* and *-ze.<zone>/* (or *.ze.<zone>/* for the dot delimiter).
    3. Remove only connections owned by the integration that are no longer used. Review customer DNS and certificates separately; do not blindly delete shared resources or DNS records.

    Delete Deployment Integration

    1. Log into Zephyr, select the organization with the integration to delete.

    2. Go to Settings in the organization dashboard, choose Deployment Integration.

    3. Select the integration name and click Remove.

    What’s Next?

  • Add Environments

    Configure custom domain for your application with your deployment integration platform.

    • © 2026 Zephyr CloudDiscordSystem statusBlog