Enhance your Workers with serverless containers
Run code written in any programming language, built for any runtime, as part of apps built on Workers.
Deploy your container image to Region:Earth without worrying about managing infrastructure - just define your
Worker and wrangler deploy.
With Containers you can run:
- Resource-intensive applications that require CPU cores running in parallel, large amounts of memory or disk space
- Applications and libraries that require a full filesystem, specific runtime, or Linux-like environment
- Existing applications and tools that have been distributed as container images
Container instances are spun up on-demand and controlled by code you write in your Worker. Instead of chaining together API calls or writing Kubernetes operators, you just write TypeScript or JavaScript.
import { DurableObject } from "cloudflare:workers";
import { rewriteRequestForContainer, startAndWaitForPort } from "./utils";
export class MyContainer extends DurableObject {
async fetch(request) {
const container = this.ctx.container;
await startAndWaitForPort(container, {
port: 4000,
inactivityTimeout: 10 * 60 * 1000,
});
const forwarded = rewriteRequestForContainer(request);
const response = await container.getTcpPort(4000).fetch(forwarded);
return response;
}
}
export default {
async fetch(request, env) {
const containerRequest = request.clone();
const { "session-id": sessionId } = await request.json();
return env.MY_CONTAINER.getByName(sessionId).fetch(containerRequest);
},
};import { DurableObject } from "cloudflare:workers";
import { rewriteRequestForContainer, startAndWaitForPort } from "./utils";
interface Env {
MY_CONTAINER: DurableObjectNamespace<MyContainer>;
}
export class MyContainer extends DurableObject<Env> {
async fetch(request: Request): Promise<Response> {
const container = this.ctx.container!;
await startAndWaitForPort(container, {
port: 4000,
inactivityTimeout: 10 * 60 * 1000,
});
const forwarded = rewriteRequestForContainer(request);
const response = await container.getTcpPort(4000).fetch(forwarded);
return response;
}
}
export default {
async fetch(request: Request, env: Env): Promise<Response> {
const containerRequest = request.clone();
const { "session-id": sessionId } = await request.json<{
"session-id": string;
}>();
return env.MY_CONTAINER.getByName(sessionId).fetch(containerRequest);
},
};export function rewriteRequestForContainer(request) {
const url = new URL(request.url);
url.protocol = "http:";
url.host = "container";
const forwarded = new Request(url, request);
forwarded.headers.delete("host");
return forwarded;
}
export async function startAndWaitForPort(container, options) {
await container.setInactivityTimeout(options.inactivityTimeout);
if (!container.running) {
container.start();
}
// start() returns before the container is ready, so poll its health endpoint.
const port = container.getTcpPort(options.port);
let lastError;
for (let attempt = 0; attempt < 100; attempt++) {
try {
const response = await port.fetch("http://container/health");
if (!response.ok) {
throw new Error(`Health check returned ${response.status}`);
}
return;
} catch (error) {
lastError = error;
await scheduler.wait(200);
}
}
throw new Error(`Container did not become ready on port ${options.port}`, {
cause: lastError,
});
}interface ReadinessOptions {
port: number;
inactivityTimeout: number;
}
type ContainerInstance = NonNullable<DurableObjectState["container"]>;
export function rewriteRequestForContainer(request: Request): Request {
const url = new URL(request.url);
url.protocol = "http:";
url.host = "container";
const forwarded = new Request(url, request);
forwarded.headers.delete("host");
return forwarded;
}
export async function startAndWaitForPort(
container: ContainerInstance,
options: ReadinessOptions,
): Promise<void> {
await container.setInactivityTimeout(options.inactivityTimeout);
if (!container.running) {
container.start();
}
// start() returns before the container is ready, so poll its health endpoint.
const port = container.getTcpPort(options.port);
let lastError: unknown;
for (let attempt = 0; attempt < 100; attempt++) {
try {
const response = await port.fetch("http://container/health");
if (!response.ok) {
throw new Error(`Health check returned ${response.status}`);
}
return;
} catch (error) {
lastError = error;
await scheduler.wait(200);
}
}
throw new Error(`Container did not become ready on port ${options.port}`, {
cause: lastError,
});
}{
"name": "container-starter",
"main": "src/index.ts",
// Set this to today's date
"compatibility_date": "2026-09-30",
"containers": [
{
"class_name": "MyContainer",
"image": "./Dockerfile",
"max_instances": 5,
},
],
"durable_objects": {
"bindings": [
{
"class_name": "MyContainer",
"name": "MY_CONTAINER",
},
],
},
"exports": {
"MyContainer": {
"type": "durable-object",
"storage": "sqlite",
},
},
}name = "container-starter"
main = "src/index.ts"
# Set this to today's date
compatibility_date = "2026-09-30"
[[containers]]
class_name = "MyContainer"
image = "./Dockerfile"
max_instances = 5
[[durable_objects.bindings]]
class_name = "MyContainer"
name = "MY_CONTAINER"
[exports.MyContainer]
type = "durable-object"
storage = "sqlite"Get started
Containers dashboard
Build and push an image, call a Container from a Worker, and try scaling and routing.
Stateless and stateful routing, regional placement, Workflow and Queue integrations, AI-generated code execution, and short-lived workloads.
Run your Worker and container together with wrangler dev or vite dev before you deploy.
Ship from your machine or Workers Builds, and confirm the deploy.
Scheduling policies
Choose whether image and instance configuration is managed centrally or from Durable Object code.
Rollouts
How container instances update after you deploy.
Image management
Build, push, and pull images for Containers.
Lifecycle of a Container
How a container is scheduled, started, routed, and shut down.
Limits
Instance counts, image size, and other platform limits.
Wrangler
CLI commands for images and containers.
APIs
Use the Durable Object Container API or reference the Container class.
SSH
Connect to running container instances with SSH through Wrangler.
Containers Discord
Ask questions, show what you are building, and talk with other Containers developers.