Containers Overview

Cloudflare Containers (beta) let you run full Docker containers on Cloudflare’s network alongside Workers. They fill the gap for workloads that don’t fit the Worker execution model: legacy Node.js/Python apps, long-running processes, or anything that needs a persistent process.

Prerequisites: Platform Model, Workers

What Containers Are

Workers run on V8 isolates with strict limits: 128MB memory, 30s CPU time (paid), no persistent processes. Containers remove these limits by running actual Docker containers on Cloudflare infrastructure.

When to Use Containers vs Workers

Use Workers when:

• Your code fits the request-response model
• You need global distribution and zero cold starts
• Memory and CPU limits are acceptable
• You can use JavaScript, TypeScript, or WASM

Use Containers when:

• You have existing apps that can’t easily port to Workers (Express, Django, Flask)
• You need long-running processes (background jobs, stream processing)
• You need more than 128MB of memory
• You need full TCP/UDP networking (not just HTTP)
• You’re running ML inference that needs GPU access
• You need language runtimes not supported by Workers (Python with native extensions, Java, Go with CGO)

How They Work

A Worker acts as the entry point and routes requests to a container:

// Worker routes traffic to a container
export default {
  async fetch(request: Request, env: Env): Promise<Response> {
    // For API routes, use the Worker directly
    if (new URL(request.url).pathname.startsWith("/api/")) {
      return handleApi(request, env);
    }

    // For heavy processing, forward to the container
    const container = env.MY_CONTAINER;
    return container.fetch(request);
  },
};

The Worker handles the edge logic (routing, auth, caching) while the container handles compute-heavy work.

Current Limitations (Beta)

As of the beta:

• Regional, not global: containers run in specific regions, not at every edge location. You choose the region at deployment.
• Cold starts: pulling and booting a container takes seconds, unlike Workers’ instant startup.
• Pricing not finalized: expect per-container-hour billing similar to other container platforms. Check the Cloudflare blog for announcements.
• No GPU yet: GPU access is planned but not available in the initial beta.
• Limited orchestration: no built-in service mesh, auto-scaling is basic compared to Kubernetes.
• No persistent storage: container filesystem is ephemeral. Use R2, D1, or external databases for persistent data.

Gotcha: Containers are NOT globally distributed like Workers. A Worker runs at whichever edge location is closest to the user. A container runs in a specific region you configure. If your container is in us-east and your user is in Tokyo, the request travels from the edge to us-east and back. Use Workers for latency-sensitive work and containers for compute-intensive work where a few hundred ms of added latency is acceptable.

Architecture Pattern

The recommended pattern is a Worker + Container hybrid:

1. Worker at the edge: handles routing, authentication, caching, and simple logic
2. Container in a region: handles heavy computation, legacy code, or long-running processes
3. Shared storage: both use D1/R2/KV for data

This gives you the best of both worlds: global edge performance for most requests, with container compute available when you need it.

When This Goes GA

Containers are worth watching for teams that want to consolidate on Cloudflare but have workloads that don’t fit Workers. Once GA, expect:

• Finalized pricing
• More regions
• GPU support
• Better auto-scaling
• Deeper integration with Workers AI

For now, build on Workers where possible and evaluate containers for the specific workloads listed above. The API surface will stabilize, but the Worker-as-entry-point pattern is unlikely to change.

Related

• First Worker - the Worker entry point that routes to containers
• Platform Model - how Workers and containers fit into the platform architecture