Cloudflare Releases Worker Previews: Allowing Every AI-Authored Change to Run and Be Verified Directly in the Cloud

AI helps developers commit more code, but once code is generated, it still needs to be confirmed whether it behaves as expected in actual runtime. The more changes introduced, the more areas require verification.

The most frustrating scenario is when everything runs smoothly locally or in staging, only to behave differently once deployed to production; or when multiple Agent instances and team members share the same staging environment, leaving databases scrambled and workflows colliding.

To solve this problem, Cloudflare introduced Worker Previews. A Worker is a lightweight application running on Cloudflare's edge network, freeing developers from managing underlying servers; a Git branch is an independent development copy branched off the main line, allowing team members or Agent instances to modify code separately without interfering with one another. Worker Previews extends Git's concept of "branch isolation" to the runtime environment layer: each Git branch can spin up a cloud-hosted candidate version for verification (a preview environment), complete with an independent URL, dedicated configuration, Durable Objects and container states isolated per preview, and standalone observability. Both humans and Agent instances can send requests, inspect pages, observe errors, and refine code here.

Why Environment Branches Are Needed Alongside Code Branches

In traditional software development lifecycles, teams are accustomed to running unit tests locally first, pushing to a shared staging environment, and finally deploying to production. However, in the era of AI coding, this workflow encounters two fundamental challenges:

1. Shared staging environments become congested single-lane bottlenecks: When multiple developers or Agent instances submit changes simultaneously, sharing a single staging environment means schema migrations and configuration updates across branches can easily collide.
2. Testing components in isolation fails to reflect full system behavior: Many complex modern applications rely heavily on edge runtimes (such as Cloudflare Workers), distributed storage, OAuth authentication, and asynchronous queues. Local mock testing (replacing real services with simulated dependencies) cannot fully mirror true cloud environment discrepancies, leading to scenarios where tests pass locally but fail in production.

Cloudflare terms this workflow the Agent Development Lifecycle (ADLC): turning every change into an independently deployable, observable, and revisable unit.

As shown above, with isolated preview environments and Workers Builds configured, pushing a branch immediately runs changes in the cloud. If tests fail, feedback loops directly back into the development stage for remediation; the team can then decide whether to merge into the production mainline based on test results.

Each Branch Gets Its Own Runtime Under the Same Worker

Previously, to conduct multi-environment testing on Cloudflare, developers had to either use legacy "Wrangler environments" (deploying and managing an independent Worker per environment) or rely on old preview URLs—now designated Version URLs (which point to an uploaded Worker version but may still touch production resources).

Worker Previews consolidates these environments under a single Worker: hundreds of preview environments can run concurrently under the exact same Worker.

As illustrated above, within the same my-worker project:

• Production environment: Runs mainline code bound to the production database (e.g., D1:prod, where D1 is Cloudflare's database offering).
• Routine feature branches (e.g., fix-button, new-feature): Automatically inherit preview configurations, pointing uniformly to a shared staging database (D1:staging), and can attach branch-specific object storage (R2:feature-assets) as needed.
• Breaking change branches (e.g., d1-migration): To test breaking schema migrations, configuration can be individually overridden to redirect to a dedicated scratch database (D1:migration-test), confining the impact of the migration to the chosen test database.

A configuration copy does not equal a database copy: As seen in the diagram, fix-button and new-feature both point to the shared D1:staging test database in their configuration, while only the breaking change branch points independently to D1:migration-test. This means branches connecting to the same test database can still impact one another through concurrent writes. Such storage bindings are chosen and configured entirely by the developer on demand; these bindings do not automatically duplicate into dedicated branch-level clones of D1 databases, R2 buckets, or KV stores.

In the Cloudflare Dashboard, switching between these environments is designed to be as intuitive as switching Git branches:

Developers or reviewers simply select the target branch from the top dropdown (such as new-feature, d1-migration, or fix-button) to immediately inspect that branch's dedicated monitoring, bound resources, and runtime state. This aligns the active version, configuration, and logs during review.

Why Isolate Durable Objects and Container State

For static sites or stateless APIs, branch previews are straightforward; but modern applications frequently preserve sessions, counters, or event histories—representing state. Within the Cloudflare ecosystem, the stateful primitives highlighted for preview isolation are Durable Objects (DO) and edge-based Containers.

Identical Object IDs Risk Colliding with Live Data

Durable Objects follow a global singleton model. Simply put: within a given namespace, a specific object ID maps directly to the active instance managing that object and its attached storage. If preview branches shared the production DO namespace without isolation, a speculative write executed within a preview branch could alter the in-memory singleton actively serving live traffic, affecting production data.

Cloudflare's Approach: Dynamically Derived Namespaces

Now, running npx wrangler preview instructs Cloudflare's underlying platform to automatically provision an on-demand, independent Durable Object namespace and Container application for that branch.

Developers do not need to author custom environment-branching logic in code; they simply export the class, add its migration configuration, and access it via ctx.exports. Below is a representative snippet illustrating this mechanism; real-world usage also requires explicitly importing the DurableObject base class from cloudflare:workers, implementing business logic within the class, and defining migrations in the configuration file:

export class Counter extends DurableObject {}

export default {
  async fetch(request, env, ctx) {
    // Key point: reference Counter via ctx.exports
    const id = ctx.exports.Counter.idFromName("demo");
    const counter = ctx.exports.Counter.get(id);
    return counter.fetch(request);
  },
};

How identical code reaches distinct states:

• When executing in Production, ctx.exports.Counter automatically resolves to the production Durable Object namespace.
• When executing in a Preview branch, the runtime transparently redirects resolution to that branch's dedicated preview namespace.

This allows engineers working on sandbox cold-start optimizations to compare initial startup and subsequent response behavior across branches in parallel.

Base Configuration Governs Defaults, Branches Can Override

Another pain point during development is: re-declaring environment variables, secrets, and resource bindings for every newly created branch creates repetitive overhead.

Worker Previews introduces the concept of a Base Configuration. You define a previews block once inside your Wrangler configuration (wrangler.json or wrangler.toml):

{
  "vars": {
    "ENVIRONMENT": "production"
  },
  "r2_buckets": [
    {
      "binding": "UPLOADS",
      "bucket_name": "prod-uploads"
    }
  ],
  "previews": {
    "vars": {
      "ENVIRONMENT": "preview"
    },
    "r2_buckets": [
      {
        "binding": "UPLOADS",
        "bucket_name": "r2-staging"
      }
    ]
  }
}

In this configuration:

• Top-level declarations apply to production, targeting the prod-uploads bucket;
• Declarations nested under previews serve as the shared foundation for all preview branches, setting ENVIRONMENT to preview and routing uploads to the staging bucket r2-staging by default.

In the Dashboard's Settings tab, production settings and preview baseline configurations are displayed side-by-side:

If a particular branch requires custom provisioning—for instance, an add-new-websiter-counter branch needing a scratch KV namespace—you can apply an Override exclusively for that single branch:

This inheritance model delivers an out-of-the-box experience for standard workflows while preserving granular flexibility for complex architecture tests.

How an Agent Traces Frontend Issues to Backend Requests

With an accessible URL and synchronized execution logs, an Agent can connect testing, root-cause analysis, code patching, and re-verification into an end-to-end loop.

Previously, when deploying an AI Agent to test a web app, a common issue arose: the UI displayed an error, but lacking visibility into underlying server logs, the Agent struggled to determine whether the failure stemmed from frontend code or backend handling.

Under Worker Previews, every branch is accompanied by standalone Workers Observability (a suite for inspecting logs, errors, metrics, and distributed traces):

Through the Model Context Protocol (MCP, which connects an Agent to external tooling such as browsers and log query interfaces), the following workflow becomes possible:

1. Automated deployment and browser orchestration: Connecting Workers Builds allows branches to build and deploy automatically on git push; developers can also run npx wrangler preview. Successive pushes to the same branch update the same stable URL. The Agent then uses Playwright MCP to control Cloudflare Browser Run (a cloud-hosted headless browser), loading the URL, navigating signup or login flows, triggering UI interactions, and recording DOM events or taking screenshots in real time.
2. End-to-end fault triage: If an action fails (e.g., an unresponsive button), the Agent directly invokes the Workers Observability MCP Server to query event logs and traces, inspecting sub-requests (fetch), binding calls, and handler execution.

In the official demonstration above, while the frontend rendered successfully (Region: Earth), runtime telemetry identified an upstream issue: the endpoint returned 500 (GET /api/observability/scenario?case=6), accompanied by a capacity rule failure event (preview_capacity_rule_failed). The diagnostic panel highlighted user impact—users in that region might be unable to open the Dashboard entry button—while providing the correlation tag pr-5-wobs-15min-1788388576 (queried alongside $metadata.error Exists). Armed with these diagnostics, an Agent or a developer can investigate the failure and re-validate routing prior to merge.

Whenever human oversight is desired, reviewers can observe live browser actions via Live View or step in using Human in the Loop controls.

Testing Auth and Permissions Within the Full End-to-End Flow

To faithfully replicate production conditions, environments must address two critical hurdles: cross-origin boundaries and identity authentication.

Modern web architectures rely heavily on third-party identity providers (such as Google or GitHub OAuth) along with strict Cookie and CORS policies. If preview instances only operate under arbitrary subdomains like *.workers.dev, OAuth redirect URIs must be individually registered, introducing friction to auth testing.

To address this, Worker Previews supports mapping branches to Custom Domains:

For example, if your production site is hosted on example.com, preview branches can resolve under feature-login.previews.example.com. While custom domains mirror production more closely, full validation still requires teams to properly register OAuth callback URLs (Redirect URIs) with identity providers and ensure Cookie scopes and Cross-Origin Resource Sharing (CORS) policies are aligned. Additionally, to keep pre-release builds secure from unauthorized public access, Cloudflare Access can be enforced to require identity verification upfront.

Why CloudflareOS Tested Permissions End-to-End

Before launching Worker Previews, Cloudflare utilized it internally to build and test CloudflareOS, an open-source initiative. CloudflareOS securely bridges AI Agent instances to internal enterprise systems like Google, GitHub, and Slack. Its most critical subsystem is Gatekeepers, an authorization layer designed to constrain the operational scope accessible to an Agent.

Gatekeeper code is exceptionally sensitive: a minor logic flaw could grant an Agent unauthorized access to core confidential data. Furthermore, complex logic spanning multi-party OAuth redirects, approval flows, and real-time state cannot reveal full system behavior when individual components are tested in isolation. Cloudflare's engineering approach was straightforward: every modification proposed for Gatekeepers spun up an isolated Worker Preview to execute the authorization flow end-to-end, resolve failures, re-test, and only then merge.

Early adopters highlighted similar benefits in the official release:

• Dhravya Shah, Founder of Supermemory, noted they rely on Worker Previews to test HTTP flows involving Durable Objects, intercepting issues earlier without slowing release velocity.
• Dylan Garcia, Senior Engineer at Ramp, shared that because previews remain persistently available online, he can review and validate PR previews generated by his Agent (Inspect) directly from his mobile device.

Calls Not Yet Automatically Confined to Preview Environments

Worker Previews does not yet automatically isolate all external calls and infrastructure resources. Current documented limitations and roadmap targets include:

1. Cross-Worker invocations (Service Bindings) are not fully isolated:
   • Current status: If a Worker inside a preview branch calls another associated Worker via Service Bindings, that invocation will route to the target Worker's production deployment by default.
   • Roadmap: Cloudflare is developing routing mechanisms to match previews across callers and targets, keeping the full call chain within matched preview environments.
2. Consumption isolation for asynchronous Queues and Workflows:
   • Current status: Previews can publish messages to Queues, but cannot consume them; isolating Workflows execution requires separate manual setup.
   • Roadmap: Engineering efforts are underway to confine entire asynchronous pipelines—including queues and background workflows—cleanly within branch scopes.
3. Support for Long-lived Previews:
   • For persistent staging or QA environments that span multiple release cycles and require prolonged lifecycles, Cloudflare is designing dedicated long-lived preview capabilities.