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 leverages Cloudflare's global edge network, KV namespaces, Workers, and Pages 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 Basic Info, then continue to DNS configuration.

    Configure Your DNS Record

    • Return to your domain’s home page (the Overview page should still be open) and click on DNS on the left sidebar.
    • Click Add record on the Records page and enter the following details:

    dns

    Click to view DNS record details
    TypeNameContentProxy StatusTTL
    CNAME*ze.zephyrcloud.appProxiedAuto

    This customer-configured proxied wildcard CNAME supplies DNS coverage for Zephyr-generated hostnames and the base upload endpoint. Zephyr does not create this wildcard record. Its target is Zephyr's documented setup convention, not a Cloudflare requirement; Worker Routes still require proxied DNS coverage.

    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.

    Cloudflare integration form with Connect with Cloudflare selected

    After completing Basic Info and confirming the DNS record:

    • In Configure Cloudflare, choose Connect with Cloudflare.
    • Click Connect with Cloudflare.
    • In Cloudflare, select the Cloudflare account that owns the zone you want Zephyr to use.
    • Review the requested permissions, then select Authorize.
    • After Cloudflare redirects back to Zephyr, wait for Zephyr to load your Cloudflare zones.
    • Select the Cloudflare Zone for this integration.
    • Choose the delimiter for generated deployment URLs.
    • Click Finish.

    Cloudflare zone selection after authorizing Zephyr

    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.

    Cloudflare integration form with Manual setup selected

    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 Connect with Cloudflare for OAuth setup, or Manual setup to paste a Cloudflare API token and Zone ID.

    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

    Choose the delimiter for application subdomains: - (your deploy URL will be *-ze.your.domain) or . (your deploy URL will be *.ze.your.domain)

    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

    Worker and KV namespace names are configurable. The defaults are ze-worker-for-static-upload, ze_envs, ze_snapshots, and ze_files. 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

    After you finish the connection, Zephyr creates or updates the configured public/static Worker, its KV namespaces, and the two base Worker Routes. For a zone named example.com:

    ConnectionCloudflare objectValue
    Base upload/control endpointWorker Routeze.example.com/*
    Generated version, tag, and environment URLs (- delimiter)Worker Route*-ze.example.com/*
    Generated URLs with the existing . delimiterWorker Route (instead of the - pattern)*.ze.example.com/*
    Optional environment aliasWorker Custom Domainapp.example.com

    Both base Routes include /* so all paths and query strings reach the Worker. The dot-delimiter alternative requires DNS coverage and a wildcard certificate for *.ze.example.com; the zone's usual *.example.com certificate does not cover these deeper hostnames.

    Environment aliases are separate from those base Routes. In the environment's settings, enter an exact hostname from the selected integration's zone, without a URL, wildcard, or /*. Cloudflare manages DNS and TLS for the attached Custom Domain and sends all paths to the Worker. Zephyr enables normal hostname routing (enabled: true) and disables native Cloudflare Worker-version previews (previews_enabled: false). This is production 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. Existing Route-based aliases migrate when reconnected, not through an automatic bulk migration. Keep the base Routes and wildcard DNS coverage intact.



    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.

    Cloudflare OAuth setup showing no zones found

    Zones keep loading or OAuth is temporarily unavailable

    Reconnect with Cloudflare and try again. If OAuth remains unavailable, you can use Manual setup as a fallback or contact us on Discord.

    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 Routes

    • ze.<zone>/* on the configured public/static Worker.
    • *-ze.<zone>/* on the same Worker, or *.ze.<zone>/* for the existing dot delimiter.

    4. DNS and Environment Custom Domains

    The proxied wildcard CNAME described above is configured by you, not provisioned by Zephyr. Optional exact environment aliases are attached separately as Worker Custom Domains, for which Cloudflare creates DNS records and certificates automatically. 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 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 remaining connections.
    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.

    Delete Worker Routes

    1. On the dashboard, select the domain used for the integration.

    2. In Workers Routes, review ze.<zone>/* and *-ze.<zone>/* (or *.ze.<zone>/* for the dot delimiter). Remove them only if they are no longer used; review customer-configured wildcard DNS separately.

    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.