← All products

Workers

Cloudflare Workers executes customer code in V8 isolates on the Cloudflare network, with bindings to storage, database, queue and inference services. This page documents the execution model, the binding model, the platform limits that constrain design, and pricing as published.

Document control

Dana
Technical writer, Integrity Czech Republic s.r.o.

Overview

Workers is Cloudflare's serverless compute platform. Code is deployed to the network rather than to a region, and an invocation is handled at the data centre that received the request. There are no instances to size and no runtime to patch, but the platform imposes explicit CPU, memory, subrequest and script size limits that shape what can be built on it. Those limits are documented in the Limits and constraints section and should be read before design, not after.

Two usage patterns are common. The first places a Worker in front of an existing origin to handle routing, header manipulation, authentication, personalisation or caching logic, leaving the application where it is. The second builds an application entirely on the platform, using its storage and database services with no conventional origin server.

Scaling is handled by the platform in the sense that no capacity is provisioned per deployment. It is not unbounded: per-invocation CPU time, memory, subrequest counts and per-service quotas apply, and account-level concurrency controls exist. Design against the documented limits rather than against an assumption of unlimited scale.

Architecture

A Worker runs in a V8 isolate rather than in a container or virtual machine. An isolate is a sandboxed JavaScript execution context; many isolates are hosted per process, and starting one is substantially cheaper than starting a container image. This is the basis for the platform's start-up characteristics and for the economics of deploying the same code to every location.

Start-up is not free in all cases. Cold start time depends on script size, on the amount of work performed at module scope, and on whether a WebAssembly module must be instantiated. Large bundles and heavy initialisation produce measurable cold starts.

The execution environment implements web platform APIs: fetch, Request and Response, URL, Web Crypto, streams, WebSocket and a subset of Node.js APIs enabled through the nodejs_compat compatibility flag. Runtime behaviour is pinned by a compatibility date and by compatibility flags declared in the Worker configuration, which is how the platform introduces behavioural changes without breaking deployed code.

Bindings connect a Worker to platform resources. A binding is declared in configuration and injected into the environment object at runtime, so a KV namespace, an R2 bucket, a D1 database, a queue, a Durable Object namespace, an AI model or another Worker is addressed as a capability rather than through a connection string or an embedded credential.

Deployment through the Wrangler CLI publishes a new version. Gradual deployments route a configured percentage of traffic to a new version, which means that during a gradual deployment two versions serve concurrently. Deployment is therefore not atomic in that mode, and code must tolerate both versions running against the same data.

In the Cloudflare request pipeline, security phases execute before a Worker is invoked, so a request blocked by the WAF or by a DDoS rule does not reach Worker code.

Capabilities

Configuration model

A Worker is defined by its code and its configuration file, wrangler.jsonc or wrangler.toml. The configuration declares:

• Entry point and build settings. The module entry point and any build step.
• Compatibility date and flags. The runtime behaviour the code was written against. Changing the compatibility date is a deliberate act with observable effects and should be reviewed as a code change.
• Bindings. KV namespaces, R2 buckets, D1 databases, Durable Object namespaces, queues, service bindings to other Workers, AI bindings and plain environment variables.
• Secrets. Held outside the configuration file, set through Wrangler or the dashboard, and exposed on the environment object at runtime.
• Triggers. Routes and custom domains for HTTP invocation, cron expressions for scheduled invocation, and queue consumer declarations.
• Environments. Named variants of the configuration for staging and production, each with its own bindings and secrets.
• Limits. Where supported, an explicit CPU limit for the Worker.

Storage choice is the main architectural decision and follows the consistency and access pattern required: KV for high-volume reads of data that tolerates eventual consistency, D1 for relational queries, R2 for objects, Durable Objects where strong consistency or per-entity coordination is required, and Queues where work should be decoupled from the request.

Hold the configuration in version control alongside the code, since bindings and compatibility settings determine runtime behaviour as much as the source does.

Limits and constraints

Values below are from Cloudflare's platform limits documentation, verified 2026-08-31 (https://developers.cloudflare.com/workers/platform/limits/). They change without notice and should be re-checked before a design depends on them.

A subrequest is any request the Worker makes with the Fetch API or to a Cloudflare service through a binding, so fetch calls and binding calls consume the same per-invocation budget.

Storage service constraints, retrieved 2026-08-28:

• Workers KV. Key size 512 bytes, value size 25 MiB, and a documented limit of approximately one write per second to the same key. KV is eventually consistent: a write is not guaranteed to be visible to a read in another location immediately.
• R2. Multipart upload is required above the single-request object size limit, and part size constraints apply. No egress charge to the internet; operations are billed by class.
• D1. A maximum database size and per-query constraints apply. A D1 database is not a substitute for a horizontally scaled relational cluster; confirm the current maximum before planning data volume.
• Durable Objects. An object is single threaded, so throughput per object is bounded and hot-key patterns must be avoided at design time. Per-object storage limits apply and differ between the key-value and SQLite backends.

Further constraints:

• Python Workers are in open beta and require the python_workers compatibility flag. Planning a production workload on them means accepting beta status and the possibility of behavioural change.
• CPU time measures time spent executing, not wall-clock time. Time awaiting a subrequest does not consume CPU time, but total request duration remains subject to HTTP timeouts and client behaviour.
• Cold starts are not eliminated. Large bundles, extensive module-scope initialisation and WebAssembly instantiation add measurable start-up time.
• Gradual deployments run two versions concurrently, so schema and data format changes must be backward compatible for the duration of the rollout.
• Node.js compatibility is partial and depends on the nodejs_compat flag and the compatibility date. Libraries requiring unsupported Node.js APIs, native modules or long-lived raw TCP connections may not run.
• Account-level concurrency and rate controls exist. A workload expecting extreme burst concurrency should be confirmed against the contract rather than assumed.

Plan availability

Deployment

Prerequisites.

• Identify the candidate workload and classify it: edge logic in front of an existing origin, an API, a scheduled job, or a full application.
• Map the workload to platform primitives and record the consistency requirement for each piece of state, since that determines the storage choice.
• Check the workload against the documented limits before writing code: peak CPU per request, peak memory, number of outbound calls per request, bundle size and any dependency requiring an unsupported Node.js API.
• Confirm the runtime. If Python is proposed, record that Python Workers are in open beta and obtain a decision on accepting that status.
• Record where secrets currently live and how they will be supplied as Worker secrets.
• Record the current traffic path and the rollback route to it.

Staged validation. Implement the workload against a staging environment with its own bindings and its own data, and exercise it with representative traffic. Measure CPU time per invocation, memory use and subrequest count against the tier limits, and measure cold start behaviour with the production bundle size rather than a trimmed one. Confirm that observability output reaches the intended destination before any production traffic is routed.

Configuration.

1. Declare bindings and set the compatibility date explicitly; do not rely on a default.
2. Move all credentials to Worker secrets, and confirm none remain in the repository or the configuration file.
3. Configure separate staging and production environments with distinct storage resources, so a deployment error cannot write to production data.
4. Set up CI so that deployment is performed by the pipeline with a scoped API token, not from a developer workstation.
5. Add rate limiting in front of publicly reachable Worker routes, and add caching where the response permits it, so that request volume and therefore cost are bounded.
6. Model cost against expected traffic using the per-service pricing pages, including storage operation classes, and set billing alerts.

Cutover. Route production traffic progressively using gradual deployments or a route covering a subset of paths. Because two versions serve concurrently during a gradual deployment, verify that the new version is compatible with data written by the previous one, and with data the previous one will continue to write during the rollout.

Verification.

• Confirm error rate and latency at each traffic percentage against the recorded baseline before increasing it.
• Confirm that CPU time per invocation stays within the configured limit at production traffic mix, since a limit exceeded under load presents as intermittent failures.
• Confirm that logs and metrics are being produced and retained as intended.
• Confirm that storage operations are within the expected volume, because operation counts drive cost more than request counts in many designs.
• Confirm that the previous path still works, so that rollback is available.

Rollback. Revert traffic to the previous version through the deployment interface, or remove the route so requests reach the origin directly. Keep the previous version deployed rather than deleted until the new version has run through a full traffic cycle. Where a schema or data format changed, verify that the previous version can still read data written by the new one before rolling back.

Operational considerations

Instrument CPU time, error rate and subrequest counts per route, not only request volume. Limit-related failures appear under load and are invisible in a low-traffic staging environment.

Keep the compatibility date under review. Leaving it fixed indefinitely means the Worker runs against increasingly old runtime behaviour; advancing it without testing changes behaviour. Treat an advance as a change with its own validation.

Watch storage operation counts alongside request counts. A design that performs several KV or D1 operations per request has a cost profile driven by those operations, and a caching change can alter the bill substantially in either direction.

Rotate Worker secrets on a schedule and hold them only in the platform secret store. Because bindings replace connection strings, a leaked secret is usually an application credential rather than a platform one, but the rotation obligation is the same.

Design Durable Object keys so that load distributes across objects. A single object handling a disproportionate share of traffic becomes a throughput ceiling that no amount of platform scaling addresses.

Failure modes to plan for: a dependency upgrade pushing the bundle past the size limit, a code path that occasionally exceeds the CPU limit for large inputs, KV write contention on a single key, an upstream service that is slow enough to hold subrequests open, and a gradual deployment left partially rolled out.

Known caveats

• Python Workers are in open beta and require a compatibility flag. They are not appropriate for a workload that needs a stability commitment.
• The platform is not free of capacity constraints. CPU time, memory, bundle size, subrequests and per-service quotas all bound what a single invocation can do.
• Cold starts exist. They are small for compact JavaScript bundles and larger for big bundles and WebAssembly instantiation.
• Gradual deployment is not atomic. Two versions serve at once, so both must work with the same data.
• KV is eventually consistent and has a per-key write rate limit. Using it as a primary store for rapidly mutating state produces correctness problems that appear only under concurrency.
• A Durable Object is single threaded. Throughput per object is bounded by design, not by the account tier.
• Node.js compatibility is partial. A dependency tree that builds locally may still fail at runtime on an unsupported API.
• Portability is partial. Web standard APIs, the S3-compatible R2 API and D1's SQLite dialect keep much application logic portable, while Durable Objects and other platform-specific services would require re-architecture to move. Record which category each component falls into during design.

Interoperability

Workers execute after the security phases of the Cloudflare request pipeline, so WAF, DDoS and Bot Management decisions are applied before Worker code runs. A blocked request never reaches a Worker.

Workers interact with the CDN through the Cache API and through Cache Rules. Where both a Cache Rule and Worker cache logic act on the same request, the documented traffic sequence determines precedence.

R2 can serve as an origin for the CDN and backs Cache Reserve, so object storage, caching and compute compose without a conventional origin server.

Service bindings allow one Worker to invoke another without a network round trip, which supports splitting an application into separately deployed units while keeping call latency low.

Turnstile validation can be performed from a Worker, allowing challenge verification at the edge rather than in the application backend.

Access can be placed in front of a Worker route so that requests are authenticated and authorised before invocation, without the Worker implementing authentication itself.

FAQ

Is a full application migration required to adopt Workers? No. A common adoption path places a Worker on a route in front of an existing origin to handle redirects, caching logic, authentication or personalisation, while the application remains where it is. Migration of the application itself is a separate decision.

What does the CPU limit actually measure? Time spent executing code, not total request duration. Awaiting a subrequest does not consume CPU time, so a request may last longer than the CPU limit without exceeding it.

Which storage service should hold session or coordination state? Durable Objects, where strong consistency or per-entity coordination is required. KV is eventually consistent and rate limited per key, which makes it unsuitable for rapidly mutating single-key state.

Which parts of a Workers application are portable to another platform? Code written against web standard APIs, data in R2 through the S3-compatible API, and D1 schemas and queries in SQLite's dialect are largely portable. Durable Objects and other platform-specific services require re-architecture.

References

• https://developers.cloudflare.com/workers/, retrieved 2026-08-28.
• https://developers.cloudflare.com/workers/platform/limits/, retrieved 2026-08-28.
• https://developers.cloudflare.com/workers/platform/pricing/, retrieved 2026-08-28.
• https://developers.cloudflare.com/workers/languages/python/, retrieved 2026-08-28.
• https://developers.cloudflare.com/workers/configuration/compatibility-dates/, retrieved 2026-08-28.
• https://developers.cloudflare.com/workers/configuration/versions-and-deployments/gradual-deployments/, retrieved 2026-08-28.
• https://developers.cloudflare.com/kv/, retrieved 2026-08-28.
• https://developers.cloudflare.com/r2/, retrieved 2026-08-28.
• https://developers.cloudflare.com/d1/, retrieved 2026-08-28.
• https://developers.cloudflare.com/durable-objects/, retrieved 2026-08-28.

Content snapshot: 2026-08-28.

Changelog