Cloudflare Containers

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.