Cloudflare Containers

Cloudflare Containers (Public Beta)

Status: Public Beta since June 2025. This skill will be updated when Cloudflare Containers reaches GA.

Available to all Workers Paid plan users ($5/month). Not yet generally available — global autoscaling and latency-aware routing are pending. Monitor the Cloudflare changelog for GA announcement.

Deploy and manage full Linux containers on Cloudflare's edge network. Unlike Workers (V8 isolates), Containers run arbitrary Docker images in Firecracker microVMs — any language, stateful filesystem, long-lived processes.

How Containers Differ from Workers

Containers are declared in wrangler.toml or wrangler.jsonc alongside Workers. A Worker acts as the entry point, routing requests to container instances. Containers are modeled as Durable Object classes.

Prerequisites

1. Cloudflare Workers Paid plan ($5/month)
2. wrangler CLI installed and authenticated:

   npm install -g wrangler
   wrangler login
   

3. Docker installed locally (for building images)
4. A Dockerfile in the project

Configuration

wrangler.jsonc — define containers alongside the Worker:

{
  "name": "my-container-app",
  "main": "src/index.js",
  "compatibility_date": "2025-06-01",
  "containers": [
    {
      "class_name": "MyContainer",
      "image": "./Dockerfile",
      "instance_type": "standard-1",
      "max_instances": 10,
      "sleep_after": "5m"
    }
  ],
  "durable_objects": {
    "bindings": [
      {
        "name": "MY_CONTAINER",
        "class_name": "MyContainer"
      }
    ]
  }
}

Scale-to-zero with sleep_after: the container instance hibernates after the configured idle duration. Billing stops during sleep. Startup latency on wake is 2-3 seconds.

Instance Types

Start with standard-1 for general workloads. Use lite or basic for tasks that do not need dedicated CPU.

Worker Entry Point

The Worker routes requests to the container via Durable Objects:

// src/index.js
export { MyContainer } from './container';

export default {
  async fetch(request, env) {
    const id = env.MY_CONTAINER.idFromName('instance-1');
    const stub = env.MY_CONTAINER.get(id);
    return stub.fetch(request);
  }
};

// src/container.js
import { Container } from 'cloudflare:containers';

export class MyContainer extends Container {
  defaultPort = 8080;
  sleepAfter = '5m';

  override async onStart() {
    console.log('Container started');
  }
}

Deploy

# Build and deploy (builds Docker image, uploads to CF, deploys Worker)
wrangler deploy

# Local development with container simulation
wrangler dev

# Stream logs from running containers
wrangler tail

# Check deployment status
wrangler deployments list

Managing Instances

# List container instances
wrangler containers list

# View instance details
wrangler containers describe <instance-id>

# Force restart an instance
wrangler containers restart <instance-id>

Rollback

# List versions
wrangler versions list

# Roll back to previous version
wrangler rollback

Pricing (included with Workers Paid $5/month)

Billing is for active CPU time only (since November 2025), not provisioned time. Scale-to-zero means idle containers do not incur ongoing cost.

Dockerfile Recommendations

Containers run as full Linux environments. Follow standard Docker best practices:

# Multi-stage build for smaller image
FROM golang:1.23-alpine AS builder
WORKDIR /src
COPY go.mod go.sum ./
RUN go mod download
COPY . .
RUN CGO_ENABLED=0 go build -o /app ./cmd/server

FROM alpine:3.20
RUN adduser -D appuser
USER appuser
COPY --from=builder /app /app
EXPOSE 8080
CMD ["/app"]

Keep images small — Cloudflare pulls them from the registry on deploy. Smaller images deploy faster.

Beta Limitations (as of March 2026)

These limitations apply during Public Beta and may be resolved at GA:

• Global autoscaling and latency-aware routing are not yet available. Instances run in a limited set of regions.
• Inter-container communication patterns are limited. Containers communicate via HTTP through the Worker routing layer.
• Some regions may have limited or no capacity. Deployments may fail with capacity errors in underserved regions.
• Custom domains for container endpoints require routing through a Worker.
• No direct UDP support — TCP only.

Key Updates Timeline

• June 2025: Public Beta launched. Available to all Paid plan users.
• November 2025: Switched to active CPU billing (not provisioned). Significant cost reduction.
• January 2026: Custom instance types available.
• February 2026: Limits increased to 6 TiB memory, 1,500 vCPU, 30 TB disk per account.

When to Use Containers vs Workers

Use Containers when:

• You need a language runtime other than JavaScript/TypeScript/WASM
• Your process is long-lived (database, persistent cache, background job)
• You need a stateful filesystem
• You are lifting-and-shifting an existing Docker-based service to the edge

Use Workers when:

• You are writing JavaScript/TypeScript
• You need sub-millisecond cold start
• Your logic is stateless and request-scoped
• You want the simplest possible deployment model

This skill will be updated when Cloudflare Containers reaches GA.