1# Cloudflare Containers Skill Reference
2 
3**APPLIES TO: Cloudflare Containers ONLY - NOT general Cloudflare Workers**
4 
5Use 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.
6 
7## Beta Status
8 
9⚠️ Containers is currently in **beta**. API may change without notice. No SLA guarantees. Custom instance types added Jan 2026.
10 
11## Core Concepts
12 
13**Container as Durable Object:** Each container is a Durable Object with persistent identity. Accessed via `getByName(id)` or `getRandom()`.
14 
15**Image deployment:** Images pre-fetched globally. Deployments use rolling strategy (not instant like Workers).
16 
17**Lifecycle:** cold start (2-3s) → running → `sleepAfter` timeout → stopped. No autoscaling - manual load balancing via `getRandom()`.
18 
19**Persistent identity, ephemeral disk:** Container ID persists, but disk resets on stop. Use Durable Object storage for persistence.
20 
21## Quick Start
22 
23```typescript
24import { Container } from "@cloudflare/containers";
25 
26export class MyContainer extends Container {
27  defaultPort = 8080;
28  sleepAfter = "30m";
29}
30 
31export default {
32  async fetch(request: Request, env: Env) {
33    const container = env.MY_CONTAINER.getByName("instance-1");
34    await container.startAndWaitForPorts();
35    return container.fetch(request);
36  }
37};
38```
39 
40## Reading Order
41 
42| Task | Files |
43|------|-------|
44| Setup new container project | README → configuration.md |
45| Implement container logic | README → api.md → patterns.md |
46| Choose routing pattern | patterns.md (routing section) |
47| Debug issues | gotchas.md |
48| Production hardening | gotchas.md → patterns.md (lifecycle) |
49 
50## Routing Decision Tree
51 
52**How should requests reach containers?**
53 
54- **Same user/session → same container:** Use `getByName(sessionId)` for session affinity
55- **Stateless, spread load:** Use `getRandom()` for load balancing
56- **Job per container:** Use `getByName(jobId)` + explicit lifecycle management
57- **Single global instance:** Use `getByName("singleton")`
58 
59## When to Use Containers vs Workers
60 
61**Use Containers when:**
62- Need stateful, long-lived processes (sessions, WebSockets, games)
63- Running existing containerized apps (Node.js, Python, custom binaries)
64- Need filesystem access or specific system dependencies
65- Per-user/session isolation with dedicated compute
66 
67**Use Workers when:**
68- Stateless HTTP handlers
69- Sub-millisecond cold starts required
70- Auto-scaling to zero critical
71- Simple request/response patterns
72 
73## In This Reference
74 
75- **[configuration.md](configuration.md)** - Wrangler config, instance types, Container class properties, environment variables, account limits
76- **[api.md](api.md)** - Container class API, startup methods, communication (HTTP/TCP/WebSocket), routing helpers, lifecycle hooks, scheduling, state inspection
77- **[patterns.md](patterns.md)** - Routing patterns (session affinity, load balancing, singleton), WebSocket forwarding, graceful shutdown, Workflow/Queue integration
78- **[gotchas.md](gotchas.md)** - Critical gotchas (WebSocket, startup methods), common errors with solutions, specific limits, beta caveats
79 
80## See Also
81 
82- [Durable Objects](../durable-objects/) - Containers extend Durable Objects
83- [Workflows](../workflows/) - Orchestrate container operations
84- [Queues](../queues/) - Trigger containers from queue messages
85- [Cloudflare Docs](https://developers.cloudflare.com/containers/)
86