Wrangler Configuration

Wrangler Configuration

Basic Container Config

{
  "name": "my-worker",
  "main": "src/index.ts",
  "compatibility_date": "2026-01-10",
  "containers": [
    {
      "class_name": "MyContainer",
      "image": "./Dockerfile", // Path to Dockerfile or directory with Dockerfile
      "instance_type": "standard-1", // Predefined or custom (see below)
      "max_instances": 10,
    },
  ],
  "durable_objects": {
    "bindings": [
      {
        "name": "MY_CONTAINER",
        "class_name": "MyContainer",
      },
    ],
  },
  "migrations": [
    {
      "tag": "v1",
      "new_sqlite_classes": ["MyContainer"], // Must use new_sqlite_classes
    },
  ],
}

Key config requirements:

• image - Path to Dockerfile or directory containing Dockerfile
• class_name - Must match Container class export name
• max_instances - Max concurrent container instances
• Must configure Durable Objects binding AND migrations

Instance Types

Predefined Types

{
  "containers": [
    {
      "class_name": "MyContainer",
      "image": "./Dockerfile",
      "instance_type": "standard-2", // Use predefined type
    },
  ],
}

Custom Types (Jan 2026 Feature)

{
  "containers": [
    {
      "class_name": "MyContainer",
      "image": "./Dockerfile",
      "instance_type_custom": {
        "vcpu": 2, // 1-4 vCPU
        "memory_mib": 8192, // 512-12288 MiB (up to 12 GiB)
        "disk_mib": 16384, // 2048-20480 MiB (up to 20 GB)
      },
    },
  ],
}

Custom type constraints:

• Minimum 3 GiB memory per vCPU
• Maximum 2 GB disk per 1 GiB memory
• Max 4 vCPU, 12 GiB memory, 20 GB disk per container

Account Limits

Container Class Properties

import { Container } from '@cloudflare/containers'

export class MyContainer extends Container {
  // Port Configuration
  defaultPort = 8080 // Default port for fetch() calls
  requiredPorts = [8080, 9090] // Ports to wait for in startAndWaitForPorts()

  // Lifecycle
  sleepAfter = '30m' // Inactivity timeout (5m, 30m, 2h, etc.)

  // Network
  enableInternet = true // Allow outbound internet access

  // Health Check
  pingEndpoint = '/health' // Health check endpoint path

  // Environment
  envVars = {
    // Environment variables passed to container
    NODE_ENV: 'production',
    LOG_LEVEL: 'info',
  }

  // Startup
  entrypoint = ['/bin/start.sh'] // Override image entrypoint (optional)
}

Property details:

• defaultPort: Port used when calling container.fetch() without explicit port. Falls back to port 33 if not set.

• requiredPorts: Array of ports that must be listening before startAndWaitForPorts() returns. First port becomes default if defaultPort not set.

• sleepAfter: Duration string (e.g., "5m", "30m", "2h"). Container stops after this period of inactivity. Timer resets on each request.

• enableInternet: Boolean. If true, container can make outbound HTTP/TCP requests.

• pingEndpoint: Path used for health checks. Should respond with 2xx status.

• envVars: Object of environment variables. Merged with runtime-provided vars (see below).

• entrypoint: Array of strings. Overrides container image's CMD/ENTRYPOINT.

Runtime Environment Variables

Cloudflare automatically provides these environment variables to containers:

Custom envVars from Container class are merged with these. Custom vars override runtime vars if names conflict.

Image Management

Distribution model: Images pre-fetched to all global locations before deployment. Ensures fast cold starts (2-3s typical).

Rolling deploys: Unlike Workers (instant), container deployments roll out gradually. Old versions continue running during rollout.

Ephemeral disk: Container disk is ephemeral and resets on each stop. Use Durable Object storage (this.ctx.storage) for persistence.

wrangler.toml Format

name = "my-worker"
main = "src/index.ts"
compatibility_date = "2026-01-10"

[[containers]]
class_name = "MyContainer"
image = "./Dockerfile"
instance_type = "standard-2"
max_instances = 10

[[durable_objects.bindings]]
name = "MY_CONTAINER"
class_name = "MyContainer"

[[migrations]]
tag = "v1"
new_sqlite_classes = ["MyContainer"]

Both wrangler.jsonc and wrangler.toml are supported. Use wrangler.jsonc for comments and better IDE support.