Cloudflare Containers Skill Reference

APPLIES TO: Cloudflare Containers ONLY - NOT general Cloudflare Workers

Use when working with Cloudflare Containers: deploying containerized apps on Workers platform, configuring container-enabled Durable Objects, managing container lifecycle, or implementing stateful/stateless container patterns.

Beta Status

⚠️ Containers is currently in beta. API may change without notice. No SLA guarantees. Custom instance types added Jan 2026.

Core Concepts

Container as Durable Object: Each container is a Durable Object with persistent identity. Accessed via getByName(id) or getRandom().

Image deployment: Images pre-fetched globally. Deployments use rolling strategy (not instant like Workers).

Lifecycle: cold start (2-3s) → running → sleepAfter timeout → stopped. No autoscaling - manual load balancing via getRandom().

Persistent identity, ephemeral disk: Container ID persists, but disk resets on stop. Use Durable Object storage for persistence.

Quick Start

import { Container } from "@cloudflare/containers";

export class MyContainer extends Container {
  defaultPort = 8080;
  sleepAfter = "30m";
}

export default {
  async fetch(request: Request, env: Env) {
    const container = env.MY_CONTAINER.getByName("instance-1");
    await container.startAndWaitForPorts();
    return container.fetch(request);
  }
};

Reading Order

Task	Files
Setup new container project	README → configuration.md
Implement container logic	README → api.md → patterns.md
Choose routing pattern	patterns.md (routing section)
Debug issues	gotchas.md
Production hardening	gotchas.md → patterns.md (lifecycle)

Routing Decision Tree

How should requests reach containers?

Same user/session → same container: Use getByName(sessionId) for session affinity
Stateless, spread load: Use getRandom() for load balancing
Job per container: Use getByName(jobId) + explicit lifecycle management
Single global instance: Use getByName("singleton")

When to Use Containers vs Workers

Use Containers when:

Need stateful, long-lived processes (sessions, WebSockets, games)
Running existing containerized apps (Node.js, Python, custom binaries)
Need filesystem access or specific system dependencies
Per-user/session isolation with dedicated compute

Use Workers when:

Stateless HTTP handlers
Sub-millisecond cold starts required
Auto-scaling to zero critical
Simple request/response patterns

In This Reference

configuration.md - Wrangler config, instance types, Container class properties, environment variables, account limits
api.md - Container class API, startup methods, communication (HTTP/TCP/WebSocket), routing helpers, lifecycle hooks, scheduling, state inspection
patterns.md - Routing patterns (session affinity, load balancing, singleton), WebSocket forwarding, graceful shutdown, Workflow/Queue integration
gotchas.md - Critical gotchas (WebSocket, startup methods), common errors with solutions, specific limits, beta caveats

README.md