1## Container Class API
2 
3```typescript
4import { Container } from "@cloudflare/containers";
5 
6export class MyContainer extends Container {
7  defaultPort = 8080;
8  requiredPorts = [8080];
9  sleepAfter = "30m";
10  enableInternet = true;
11  pingEndpoint = "/health";
12  envVars = {};
13  entrypoint = [];
14 
15  onStart() { /* container started */ }
16  onStop() { /* container stopping */ }
17  onError(error: Error) { /* container error */ }
18  onActivityExpired(): boolean { /* timeout, return true to stay alive */ }
19  async alarm() { /* scheduled task */ }
20}
21```
22 
23## Routing
24 
25**getByName(id)** - Named instance for session affinity, per-user state
26**getRandom()** - Random instance for load balancing stateless services
27 
28```typescript
29const container = env.MY_CONTAINER.getByName("user-123");
30const container = env.MY_CONTAINER.getRandom();
31```
32 
33## Startup Methods
34 
35### start() - Basic start (8s timeout)
36 
37```typescript
38await container.start();
39await container.start({ envVars: { KEY: "value" } });
40```
41 
42Returns when **process starts**, NOT when ports ready. Use for fire-and-forget.
43 
44### startAndWaitForPorts() - Recommended (20s timeout)
45 
46```typescript
47await container.startAndWaitForPorts();  // Uses requiredPorts
48await container.startAndWaitForPorts({ ports: [8080, 9090] });
49await container.startAndWaitForPorts({ 
50  ports: [8080],
51  startOptions: { envVars: { KEY: "value" } }
52});
53```
54 
55Returns when **ports listening**. Use before HTTP/TCP requests.
56 
57**Port resolution:** explicit ports → requiredPorts → defaultPort → port 33
58 
59### waitForPort() - Wait for specific port
60 
61```typescript
62await container.waitForPort(8080);
63await container.waitForPort(8080, { timeout: 30000 });
64```
65 
66## Communication
67 
68### fetch() - HTTP with WebSocket support
69 
70```typescript
71// ✅ Supports WebSocket upgrades
72const response = await container.fetch(request);
73const response = await container.fetch("http://container/api", {
74  method: "POST",
75  body: JSON.stringify({ data: "value" })
76});
77```
78 
79**Use for:** All HTTP, especially WebSocket.
80 
81### containerFetch() - HTTP only (no WebSocket)
82 
83```typescript
84// ❌ No WebSocket support
85const response = await container.containerFetch(request);
86```
87 
88**⚠️ Critical:** Use `fetch()` for WebSocket, not `containerFetch()`.
89 
90### TCP Connections
91 
92```typescript
93const port = this.ctx.container.getTcpPort(8080);
94const conn = port.connect();
95await conn.opened;
96 
97if (request.body) await request.body.pipeTo(conn.writable);
98return new Response(conn.readable);
99```
100 
101### switchPort() - Change default port
102 
103```typescript
104this.switchPort(8081);  // Subsequent fetch() uses this port
105```
106 
107## Lifecycle Hooks
108 
109### onStart()
110 
111Called when container process starts (ports may not be ready). Runs in `blockConcurrencyWhile` - no concurrent requests.
112 
113```typescript
114onStart() {
115  console.log("Container starting");
116}
117```
118 
119### onStop()
120 
121Called when SIGTERM received. 15 minutes until SIGKILL. Use for graceful shutdown.
122 
123```typescript
124onStop() {
125  // Save state, close connections, flush logs
126}
127```
128 
129### onError()
130 
131Called when container crashes or fails to start.
132 
133```typescript
134onError(error: Error) {
135  console.error("Container error:", error);
136}
137```
138 
139### onActivityExpired()
140 
141Called when `sleepAfter` timeout reached. Return `true` to stay alive, `false` to stop.
142 
143```typescript
144onActivityExpired(): boolean {
145  if (this.hasActiveConnections()) return true;  // Keep alive
146  return false;  // OK to stop
147}
148```
149 
150## Scheduling
151 
152```typescript
153export class ScheduledContainer extends Container {
154  async fetch(request: Request) {
155    await this.schedule(Date.now() + 60000);  // 1 minute
156    await this.schedule("2026-01-28T00:00:00Z");  // ISO string
157    return new Response("Scheduled");
158  }
159 
160  async alarm() {
161    // Called when schedule fires (SQLite-backed, survives restarts)
162  }
163}
164```
165 
166**⚠️ Don't override `alarm()` directly when using `schedule()` helper.**
167 
168## State Inspection
169 
170### External state check
171 
172```typescript
173const state = await container.getState();
174// state.status: "starting" | "running" | "stopping" | "stopped"
175```
176 
177### Internal state check
178 
179```typescript
180export class MyContainer extends Container {
181  async fetch(request: Request) {
182    if (this.ctx.container.running) { ... }
183  }
184}
185```
186 
187**⚠️ Use `getState()` for external checks, `ctx.container.running` for internal.**
188