1## Wrangler Configuration
2 
3### Basic Container Config
4 
5```jsonc
6{
7  "name": "my-worker",
8  "main": "src/index.ts",
9  "compatibility_date": "2026-01-10",
10  "containers": [
11    {
12      "class_name": "MyContainer",
13      "image": "./Dockerfile",  // Path to Dockerfile or directory with Dockerfile
14      "instance_type": "standard-1",  // Predefined or custom (see below)
15      "max_instances": 10
16    }
17  ],
18  "durable_objects": {
19    "bindings": [
20      {
21        "name": "MY_CONTAINER",
22        "class_name": "MyContainer"
23      }
24    ]
25  },
26  "migrations": [
27    {
28      "tag": "v1",
29      "new_sqlite_classes": ["MyContainer"]  // Must use new_sqlite_classes
30    }
31  ]
32}
33```
34 
35Key config requirements:
36- `image` - Path to Dockerfile or directory containing Dockerfile
37- `class_name` - Must match Container class export name
38- `max_instances` - Max concurrent container instances
39- Must configure Durable Objects binding AND migrations
40 
41### Instance Types
42 
43#### Predefined Types
44 
45| Type | vCPU | Memory | Disk |
46|------|------|--------|------|
47| lite | 1/16 | 256 MiB | 2 GB |
48| basic | 1/4 | 1 GiB | 4 GB |
49| standard-1 | 1/2 | 4 GiB | 8 GB |
50| standard-2 | 1 | 6 GiB | 12 GB |
51| standard-3 | 2 | 8 GiB | 16 GB |
52| standard-4 | 4 | 12 GiB | 20 GB |
53 
54```jsonc
55{
56  "containers": [
57    {
58      "class_name": "MyContainer",
59      "image": "./Dockerfile",
60      "instance_type": "standard-2"  // Use predefined type
61    }
62  ]
63}
64```
65 
66#### Custom Types (Jan 2026 Feature)
67 
68```jsonc
69{
70  "containers": [
71    {
72      "class_name": "MyContainer",
73      "image": "./Dockerfile",
74      "instance_type_custom": {
75        "vcpu": 2,              // 1-4 vCPU
76        "memory_mib": 8192,     // 512-12288 MiB (up to 12 GiB)
77        "disk_mib": 16384       // 2048-20480 MiB (up to 20 GB)
78      }
79    }
80  ]
81}
82```
83 
84**Custom type constraints:**
85- Minimum 3 GiB memory per vCPU
86- Maximum 2 GB disk per 1 GiB memory
87- Max 4 vCPU, 12 GiB memory, 20 GB disk per container
88 
89### Account Limits
90 
91| Resource | Limit | Notes |
92|----------|-------|-------|
93| Total memory (all containers) | 400 GiB | Across all running containers |
94| Total vCPU (all containers) | 100 | Across all running containers |
95| Total disk (all containers) | 2 TB | Across all running containers |
96| Image storage per account | 50 GB | Stored container images |
97 
98### Container Class Properties
99 
100```typescript
101import { Container } from "@cloudflare/containers";
102 
103export class MyContainer extends Container {
104  // Port Configuration
105  defaultPort = 8080;             // Default port for fetch() calls
106  requiredPorts = [8080, 9090];   // Ports to wait for in startAndWaitForPorts()
107 
108  // Lifecycle
109  sleepAfter = "30m";             // Inactivity timeout (5m, 30m, 2h, etc.)
110 
111  // Network
112  enableInternet = true;          // Allow outbound internet access
113 
114  // Health Check
115  pingEndpoint = "/health";       // Health check endpoint path
116 
117  // Environment
118  envVars = {                     // Environment variables passed to container
119    NODE_ENV: "production",
120    LOG_LEVEL: "info"
121  };
122 
123  // Startup
124  entrypoint = ["/bin/start.sh"]; // Override image entrypoint (optional)
125}
126```
127 
128**Property details:**
129 
130- **`defaultPort`**: Port used when calling `container.fetch()` without explicit port. Falls back to port 33 if not set.
131 
132- **`requiredPorts`**: Array of ports that must be listening before `startAndWaitForPorts()` returns. First port becomes default if `defaultPort` not set.
133 
134- **`sleepAfter`**: Duration string (e.g., "5m", "30m", "2h"). Container stops after this period of inactivity. Timer resets on each request.
135 
136- **`enableInternet`**: Boolean. If `true`, container can make outbound HTTP/TCP requests.
137 
138- **`pingEndpoint`**: Path used for health checks. Should respond with 2xx status.
139 
140- **`envVars`**: Object of environment variables. Merged with runtime-provided vars (see below).
141 
142- **`entrypoint`**: Array of strings. Overrides container image's CMD/ENTRYPOINT.
143 
144### Runtime Environment Variables
145 
146Cloudflare automatically provides these environment variables to containers:
147 
148| Variable | Description |
149|----------|-------------|
150| `CLOUDFLARE_APPLICATION_ID` | Worker application ID |
151| `CLOUDFLARE_COUNTRY_A2` | Two-letter country code of request origin |
152| `CLOUDFLARE_LOCATION` | Cloudflare data center location |
153| `CLOUDFLARE_REGION` | Region identifier |
154| `CLOUDFLARE_DURABLE_OBJECT_ID` | Container's Durable Object ID |
155 
156Custom `envVars` from Container class are merged with these. Custom vars override runtime vars if names conflict.
157 
158### Image Management
159 
160**Distribution model:** Images pre-fetched to all global locations before deployment. Ensures fast cold starts (2-3s typical).
161 
162**Rolling deploys:** Unlike Workers (instant), container deployments roll out gradually. Old versions continue running during rollout.
163 
164**Ephemeral disk:** Container disk is ephemeral and resets on each stop. Use Durable Object storage (`this.ctx.storage`) for persistence.
165 
166## wrangler.toml Format
167 
168```toml
169name = "my-worker"
170main = "src/index.ts"
171compatibility_date = "2026-01-10"
172 
173[[containers]]
174class_name = "MyContainer"
175image = "./Dockerfile"
176instance_type = "standard-2"
177max_instances = 10
178 
179[[durable_objects.bindings]]
180name = "MY_CONTAINER"
181class_name = "MyContainer"
182 
183[[migrations]]
184tag = "v1"
185new_sqlite_classes = ["MyContainer"]
186```
187 
188Both `wrangler.jsonc` and `wrangler.toml` are supported. Use `wrangler.jsonc` for comments and better IDE support.
189