sincecutoff.com
/v1/json /v1/md llms.txt
← all changes

wrangler top-level containers supports Durable Object-managed applications

Introduced 2026-09-10 · score 0.92

HOW TO USE IT

When a Worker uses Durable Object-managed Containers, configure `scheduling_policy: "durable_object"`, its class, and named image sources; deploy with Wrangler and select prepared images through `ctx.container.images`. Retry the same deploy command if Cloudflare reports partial completion after application creation fails.

{"containers":[{"class_name":"<Class>","scheduling_policy":"durable_object","images":{"<image-name>":{"dockerfile":"<path/to/Dockerfile>"}}}]}
npx wrangler deploy --containers-rollout=none
npx wrangler versions deploy <VERSION-ID>@100%

WHY THIS HELPS

Configure a Worker to use managed Containers backed by a Durable Object class and deploy its images.

REQUIREMENTS AND LIMITATIONS

  • Version: 4.131.0
  • containers[].scheduling_policy (required): Set to `"durable_object"` for Durable Object-managed scheduling.
  • containers[].class_name (required): Names the corresponding Durable Object class for this release-note configuration.
  • containers[].name: Optional Container application name in the release note.
  • containers[].images: Map of named images accessible through `ctx.container.images`; each image must specify exactly one of `dockerfile` or `image`.
  • containers[].images.<name>.dockerfile: Local Dockerfile path; Wrangler builds and pushes the image. Mutually exclusive with `image` for each named image.
  • containers[].images.<name>.image: Digest-pinned image reference in the Cloudflare Registry. Mutually exclusive with `dockerfile` for each named image.
  • containers[].images.<name>.build_context: Build context relative to the Wrangler config; only valid with `dockerfile`.
  • containers[].images.<name>.build_vars: Build-time variables; only valid with `dockerfile`.
  • --containers-rollout: For `wrangler deploy`, `none` skips Container image and instance updates.
  • EXPERIMENTAL_CLOUDFLARE_CONTAINER_IMAGES: Temporary reserved Wrangler binding for Container image references; user configuration cannot declare it.
  • ctx.container.images: Runtime object exposing configured named image references to Durable Object code.
  • Prerequisite: The Durable Object linked to the Container must use SQLite storage.
  • Prerequisite: A local Dockerfile build requires Docker or a Docker-compatible CLI to be running.
  • Prerequisite: Wrangler deploy of an existing Worker requires Editor access; creating a new Worker requires product-level Admin.
  • Prerequisite: The `durable_object` scheduling policy is in public beta.
  • Durable Object-managed entries also accept an optional `name` and optional named `images` map; scheduler-only fields are rejected.
  • Wrangler builds or resolves each image and waits while Cloudflare prepares it for the Containers runtime.
  • Local development support for these entries is deferred to a follow-up.
  • With `--containers-rollout=none`, existing Workers retain deployed Container metadata and image binding even when local `containers` is omitted or empty; local scheduler edits are ignored, and upload stops if deployed versions cannot be recovered.
  • Existing Workers for Platforms dispatch scripts reject `--containers-rollout=none` before upload because their API does not expose enough metadata to preserve Container associations safely.
  • Without `--containers-rollout=none`, removing managed Containers, including by omitting `containers`, clears the experimental image binding even with `keep_vars`.
  • `versions deploy` validates selected versions before changing traffic and creates Durable Object-managed applications only after deployment succeeds.
  • Both `deploy` and `versions deploy` report partial completion if application creation fails afterward, with instructions to retry the same command.
  • `EXPERIMENTAL_CLOUDFLARE_CONTAINER_IMAGES` is a temporary, reserved Wrangler binding; user configuration cannot declare it, and existing versions that already use it are treated as Container configuration.
  • The binding's class keys identify managed applications during `versions deploy`, including classes with empty image maps.
  • Existing scheduler-backed entries and Durable Object migrations continue to work unchanged.
  • Docs conflict: The current Wrangler configuration docs additionally allow omitting `class_name` when linking a Container by `name` from `exports.<Class>.container`; the Wrangler 4.131.0 release note describes `class_name` entries and does not document that alternative. Current docs may describe later behavior.

FIRST-PARTY EVIDENCE

Check the installed version and the source before using it. Entry JSON

Report a problem with this card