How to use Cloudflare Containers in Base

Workers are fast and small, but they are not a general computer. They run JavaScript on Cloudflare's runtime, not arbitrary binaries, not a long-running process you fully control, not a tool that only ships as a Linux executable. Cloudflare containers fill that gap: a real container, running next to your workers, that you can address and call into. Base wraps containers using the same pattern it uses for durable objects, because under the hood a container is reached the same way, through a provider that hands you a typed handle.

This post builds on the durable objects post. If that pattern is familiar, containers will feel familiar too.

A container is reached like a durable object

The shape you learned for durable objects carries straight over. You do not start a container by hand; you ask a provider for a handle to one. The provider is created for a namespace, the named container you declared, and it gives you a handle to an instance. The handle is typed against the container's RPC interface, so calling into the container is a typed method call rather than a hand-built request. From your worker's point of view, talking to a container and talking to a durable object look almost identical, because Base deliberately models them the same way.

Base re-exports Cloudflare's own container primitive directly, so you are working with the platform's container, with Base providing the typed provider and handle around it rather than a heavy abstraction of its own.

When a container earns its place

A container is heavier than a worker. It is a real isolated environment, slower to start, more to manage. So you reach for one only when a worker genuinely cannot do the job. The honest tests: you need to run a binary or a tool that is not JavaScript, you need a long-running process rather than a request-scoped one, you need a runtime or library that only exists as a native executable, or you need an environment you control more fully than the worker runtime allows. Image processing with a native tool, a headless browser, a language runtime that is not JavaScript, these are container work.

If a worker can do it, let a worker do it. The container is the escape hatch for the cases where the lightweight runtime is the wrong shape, not the default.

How it fits the rest of your worker

Because the container is reached through a typed handle, calling it from your Base worker is just another typed call, the same as calling another worker over RPC or calling into a durable object. Your worker stays the front door: it takes the request, decides the heavy work belongs in the container, calls the container, and shapes the result back into a response. The container does the part workers cannot, and your worker does everything else, with the boundary between them expressed as a typed interface rather than a raw protocol.

The mental model to keep

A container in Base is a real isolated environment reached the same way as a durable object: ask a provider for a typed handle by namespace, then call the container through that handle like a local object. Base re-exports Cloudflare's container primitive and wraps it in the familiar provider-and-handle pattern. Reach for a container only when a worker cannot do the job, a non-JavaScript binary, a long-running process, a native runtime, and let your worker stay the front door that calls into it.