skip to content

In Cloudflare Containers, how does a request from a Worker reach a container instance, and what must the Wrangler file declare?

level: juniorimportance: should knowfreq 32%

answer

  1. no direct door into the container
  2. one Durable Object per instance
  3. a name picks the instance
  4. containers entry plus a binding

basics

~20 s

A Worker reaches a container only through a Durable Object: it gets a stub by name, and that object starts its container and forwards traffic. Wrangler declares a containers entry (class and image), the binding and the class.

solid answer

~40 s

Each container instance belongs to one Durable Object. The Worker gets a stub with `env.CONVERTER.getByName("doc-42")` (or `getContainer()` from `@cloudflare/containers`), and the object controls its container through `this.ctx.container`: `start()`, then `getTcpPort(8080).fetch()`. The same name always reaches the same object and, while it runs, the same container. The Wrangler file needs a `containers` entry with `class_name` and `image`; a Dockerfile path makes `wrangler deploy` build the image with Docker and push it to Cloudflare's registry. It also needs a `durable_objects` binding and the class declared as a Durable Object in `exports` (or a legacy `migrations` entry). End users cannot open TCP or UDP connections to an instance: all traffic enters through the Worker. For new code Cloudflare recommends `ctx.container`; the `Container` class with `defaultPort` remains documented for existing applications.

code

json · 18 lines
json
{
  "name": "doc-convert",
  "main": "src/index.js",
  "compatibility_date": "2026-10-01",
  "containers": [
    {
      "class_name": "Converter",
      "image": "./container/Dockerfile",
      "max_instances": 10
    }
  ],
  "durable_objects": {
    "bindings": [{ "name": "CONVERTER", "class_name": "Converter" }]
  },
  "exports": {
    "Converter": { "type": "durable-object", "storage": "sqlite" }
  }
}

go deeper

for a junior

Recall the three hops: Worker, Durable Object, container. Name the containers entry, the Durable Object binding and the class declaration in the Wrangler file.

for a middle

Explain how a name maps to one Durable Object and one running instance, and what wrangler deploy does with a Dockerfile path versus a prebuilt image.

for a senior

Show where authentication and validation belong (the Worker), why the object outlives its container, and how placement depends on where the image is ready, not only on the caller.

for a principal

Weigh the direct ctx.container API against the Container class for a team's codebase: control and fewer abstractions versus helpers that hide readiness and routing.

## The request path Cloudflare Containers run a Linux image you supply, but nothing on the Internet talks to an instance directly. Every request takes the same three hops: 1. A client's HTTP request reaches your **Worker**, the ordinary `export default { fetch }` handler, at a Cloudflare location near the client. 2. The Worker picks a **Durable Object** by name, for example `env.CONVERTER.getByName("doc-42")`, and calls `fetch()` or an RPC method on that stub. 3. The Durable Object owns one container instance and reaches it through `this.ctx.container`: `start()` boots it and `getTcpPort(8080).fetch()` sends HTTP to the port the process listens on. Because the Worker is the only way in, end users cannot open raw TCP or UDP connections to an instance. The Worker is also the natural place to authenticate the caller, validate an upload and decide which instance should do the work. ## What the Wrangler file declares A container-enabled Worker needs configuration that points at one class name from several places: | Key | What it does | | --- | --- | | `containers[].class_name` | Links the Container application to a Durable Object class in this Worker | | `containers[].image` | A path to a Dockerfile, or a reference to an image in a supported registry | | `durable_objects.bindings` | Puts a namespace on `env` (here `env.CONVERTER`) so the Worker can get stubs | | `exports.<Class>` | Declares the class as a SQLite-backed Durable Object (`"storage": "sqlite"`); older Workers do this with a `migrations` entry instead | Optional keys such as `instance_type` and `max_instances` size the application, and `scheduling_policy` (default `"default"`) decides whether that sizing lives in the Wrangler file or in Durable Object code. The class itself must be exported from the Worker's main module. ## What `wrangler deploy` does with the image When `image` is a Dockerfile path, `wrangler deploy`: - builds the image locally, so Docker or a Docker-compatible engine must be running; - pushes it to Cloudflare's managed registry, which is integrated with your account, and on later deploys pushes only the layers that changed; - activates the new Worker version first and then creates or updates the Container application, which on the very first deploy can take several minutes to provision. If `image` names a prebuilt image instead, no local Docker is needed at deploy time. Images should target `linux/amd64`, and an image may be no larger than the disk of its instance type. ## Two APIs for the same container | | Durable Object Container API | `Container` class | | --- | --- | --- | | Base class | `DurableObject` from `cloudflare:workers` | `Container` from `@cloudflare/containers`, itself a Durable Object | | Start and route | `ctx.container.start()`, then `getTcpPort(port).fetch()` | `defaultPort`; the inherited `fetch()` starts the container and forwards | | Idle shutdown | `setInactivityTimeout()` | `sleepAfter` | | Status | Recommended for new applications | Documented for existing applications, `default` scheduling policy only | The class version is shorter to write: ```ts import { Container, getContainer } from "@cloudflare/containers"; export class Converter extends Container { defaultPort = 8080; } export default { async fetch(request, env) { return getContainer(env.CONVERTER, "doc-42").fetch(request); }, }; ``` `getContainer()` is a helper over the same namespace: it returns the stub for a stable name, and without a name it uses `cf-singleton-container`. With the direct API you write readiness checks and routing yourself, which is the price of controlling them. ## How a name picks an instance The name is the routing key. The same name always reaches the same Durable Object and, while its container runs, the same container, wherever the request comes from. A new name gets a new object and, on first use, a new instance that runs the image's entrypoint from scratch. The container starts in a location that already has the image, which is not necessarily where its Durable Object runs, and it stays there until it stops; after a restart it may come up somewhere else. For a document-conversion service, one name per document or per tenant keeps related work on one instance, while a small fixed set of names spreads stateless work across a few. ## Mistakes interviewers listen for - Expecting a public IP address or port on the container; traffic enters only through the Worker. - Pointing `image` at a directory instead of at the Dockerfile itself. - Declaring the `containers` entry without a Durable Object binding, which leaves the Worker nothing to call. - Treating the container's disk as the object's storage: the disk is ephemeral, while `ctx.storage` persists across container restarts.

  • Why is a Durable Object in front of every container instead of the Worker calling it directly?
    The Durable Object is a globally addressable, single instance per name, so it gives each container a stable identity to route to, a place to keep state that outlives the container in `ctx.storage`, and code that runs when the container stops. The Worker stays stateless and can run anywhere; the object pins one name to one running instance.
  • What does a Worker need locally to deploy when image points at a Dockerfile, and how do you avoid that?
    `wrangler deploy` builds the Dockerfile with a local Docker or Docker-compatible engine, so the machine or CI runner needs one running. If `image` is a prebuilt reference in a supported registry, Wrangler resolves it and no local build happens.
  • Which API would you choose for a new container-backed Worker today, and why?
    The Durable Object Container API, `this.ctx.container`, which the docs recommend for new applications: it gives direct control of start, readiness, routing and shutdown alongside Durable Object storage and alarms. The `Container` class remains documented for existing applications and works only with the `default` scheduling policy.

  • Says end users can open raw TCP connections to a container's port.
  • Thinks the Worker calls the container directly without a Durable Object.
  • Believes image must be a directory containing a Dockerfile.
  • Expects Cloudflare to build the Dockerfile on the first request instead of at deploy.
  • Treats files on the container's disk as durable state.

Assumes Cloudflare's platform as of 2026-10-10: the docs recommend ctx.container for new applications, keep the Container class for existing ones, and declare Durable Object classes with the exports field.