Skip to content

API

Last updated View as MarkdownAgent setup

Containers provide two APIs for managing a container from a Durable Object. Both APIs address the same container runtime.

For new applications, use the Durable Object Container API when you need direct lifecycle control. Use the Container class when you prefer built-in lifecycle helpers.

Container class

Use a higher-level class built on Durable Objects, with routing, readiness checks, lifecycle hooks, and scheduling.

Choose an API

Durable Object Container API

The Durable Object Container API exposes the container runtime through ctx.container. Choose it when you need direct control over startup, shutdown, networking, or resource usage. You can add readiness checks, custom request routing, or lifecycle policies when your application needs them.

Container class

The Container class builds on Durable Objects and the runtime API. Choose it when you prefer built-in request proxying, readiness checks, lifecycle hooks, and scheduling. These helpers reduce application code, but some features use Durable Object storage and alarms.

The following table compares both options:

Requirement Durable Object Container API Container class
Start and stop a container start(), signal(), and destroy() start(), stop(), and destroy()
Send and proxy traffic getTcpPort(port).fetch() and getTcpPort(port).connect() fetch() and containerFetch()
Execute another process exec() ctx.container.exec()
Check port readiness Use getTcpPort() in application code startAndWaitForPorts() and waitForPort()
Handle concurrent starts Coordinate calls to start() when needed Handled by start() and startAndWaitForPorts()
Run lifecycle hooks monitor() and application code onStart(), onStop(), onError(), and onActivityExpired()
Stop inactive containers setInactivityTimeout() sleepAfter and onActivityExpired()
Schedule callbacks ctx.storage.setAlarm() (Durable Object API) schedule()

Use the Durable Object Container API for latency-sensitive workloads or workloads that need a smaller storage footprint.

Use the Durable Object Container API

The Durable Object Container API is available through ctx.container of the Durable Object. It exposes the container runtime without adding lifecycle policy.

import { DurableObject } from "cloudflare:workers";

export class MyContainer extends DurableObject<Env> {
	constructor(ctx: DurableObjectState, env: Env) {
		super(ctx, env);
		ctx.blockConcurrencyWhile(() =>
			ctx.container.setInactivityTimeout(10 * 60 * 1000),
		);
	}

	async fetch(request: Request): Promise<Response> {
		if (!this.ctx.container.running) {
			this.ctx.container.start({ enableInternet: true });
		}

		return this.ctx.container.getTcpPort(8080).fetch(request);
	}
}

The running property does not indicate port readiness. Check the required port before routing the first request if your process needs time to start.

For all methods, refer to the Durable Object Container API.

Use the Container class

The Container class ↗ extends DurableObject. It adds default routing, readiness checks, lifecycle hooks, activity tracking, and scheduled callbacks.

import { Container } from "@cloudflare/containers";

export class MyContainer extends Container {
	defaultPort = 8080;
	sleepAfter = "10m";
}

These helpers reduce application code. They also add lifecycle state and scheduled work to the Durable Object. For all properties and methods, refer to the Container class API.

Was this helpful?