← Durable Objects / durable-objects / api

Durable Object Container

Each container is managed by a Durable Object. The Container class from @cloudflare/containers extends DurableObject and handles lifecycle management, port readiness, and sleep timeouts for you. The Durable Object manages routing, persistent state, and lifecycle hooks, while the container process runs your image inside a Linux VM.

The low-level API documented on this page is available on this.ctx.container inside any Durable Object class that has a container binding. Use it when you need direct control over the container process or cannot use the Container class.

Because the Container class extends DurableObject, you also have access to SQLite storage via this.ctx.storage, alarms, and all other Durable Object APIs.

export class MyDurableObject extends DurableObject {
	constructor(ctx, env) {
		super(ctx, env);

		// boot the container when starting the DO
		this.ctx.blockConcurrencyWhile(async () => {
			this.ctx.container.start();
		});
	}
}

export class MyDurableObject extends DurableObject {
	constructor(ctx: DurableObjectState, env: Env) {
		super(ctx, env);

    	// boot the container when starting the DO
    	this.ctx.blockConcurrencyWhile(async () => {
    		this.ctx.container.start();
    });
    }

}

running returns true if the container is currently running. It does not ensure that the container has fully started and ready to accept requests.

	this.ctx.container.running;

start boots a container. This method does not block until the container is fully started. You may want to confirm the container is ready to accept requests before using it.

this.ctx.container.start({
	env: {
		FOO: "bar",
	},
	enableInternet: false,
	entrypoint: ["node", "server.js"],
});

• options (optional): An object with the following properties:
  • env: An object containing environment variables to pass to the container. This is useful for passing configuration values or secrets to the container.
  • entrypoint: An array of strings representing the command to run in the container.
  • enableInternet: A boolean indicating whether to enable internet access for the container.

• None.

exec starts another process inside an already-running Container. It does not start a stopped Container.

The following example calls this.ctx.container.exec() inside a class extending Container from @cloudflare/containers. In RPC methods, check this.ctx.container.running and call await this.start() when needed. You can also use the onStart() hook to run any series of commands whenever the Container starts.

exec(
  cmd: string[],
  options?: ContainerExecOptions,
): Promise<ExecProcess>

The exec operation starts the executable directly with the provided arguments. It does not start a shell or interpret pipes, redirects, expansion, or other shell syntax. Invoke Bash explicitly with ["bash", "-lc", "<COMMAND>"] when Bash exists in the image. Use ["sh", "-c", "<COMMAND>"] for images with only a Portable Operating System Interface (POSIX) shell.

The following RPC method starts the Container before executing a command:

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

export class MyContainer extends Container {
	async runCommand() {
		if (!this.ctx.container.running) {
			await this.start();
		}

		const process = await this.ctx.container.exec(["node", "--version"]);
		const output = await process.output();

		return {
			pid: process.pid,
			exitCode: output.exitCode,
			stdout: new TextDecoder().decode(output.stdout),
		};
	}
}

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

export class MyContainer extends Container {
	async runCommand() {
		if (!this.ctx.container.running) {
			await this.start();
		}

		const process = await this.ctx.container.exec(["node", "--version"]);
		const output = await process.output();

		return {
			pid: process.pid,
			exitCode: output.exitCode,
			stdout: new TextDecoder().decode(output.stdout),
		};
	}
}

• cmd (string[]) — executable followed by its arguments.
• options (ContainerExecOptions, optional) — process configuration:
  • stdin (ReadableStream | "pipe") — source for standard input. Use "pipe" to write through the returned stdin stream. When omitted, standard input closes and sends end-of-file (EOF).
  • stdout ("pipe" | "ignore", default "pipe") — captures or discards standard output.
  • stderr ("pipe" | "ignore" | "combined", default "pipe") — captures, discards, or merges standard error into standard output. The "combined" value requires stdout: "pipe". Combined output does not guarantee ordering between its source streams.
  • cwd (string) — working directory for the process.
  • env (Record<string, string>) — environment additions and overrides. The process inherits existing Container variables. Matching keys use the per-execution value.
  • user (string) — image user for the process.

Returns Promise<ExecProcess>.

An ExecProcess has these fields and methods:

• stdin (WritableStream | null) — writable standard input when stdin is "pipe".
• stdout (ReadableStream | null) — readable standard output when piped.
• stderr (ReadableStream | null) — readable standard error when piped separately.
• pid (number) — process identifier.
• exitCode (Promise<number>) — resolves when the process exits. Nonzero codes resolve normally instead of rejecting.
• output() (Promise<ExecOutput>) — reads buffered output once. ExecOutput contains stdout (ArrayBuffer), stderr (ArrayBuffer), and exitCode (number). Ignored streams produce empty buffers. Use TextDecoder to decode text.
• kill(signal?: number) (void) — queues a signal for the process. The default is SIGTERM, signal 15. The signal must be from 1 through 64.

With stderr: "combined", stderr is null on ExecProcess and an empty ArrayBuffer on ExecOutput. Read both output channels from stdout.

output() throws a TypeError when called more than once or after either readable stream starts being consumed. For large output, consume both readable streams concurrently instead of buffering them with output().

exec has no built-in timeout. Use kill() to request termination, then observe completion through exitCode. A process can handle or ignore a signal, so this does not enforce a hard deadline. Do not infer a specific exit code from the signal.

• exec() throws when the Container is not running.
• exec() throws a TypeError when cmd is empty, an option mode is invalid, or stderr: "combined" is used with stdout: "ignore".
• exec() rejects if the runtime cannot create or start the process.
• Environment variable names cannot contain = or null characters. Environment values, cwd, and user cannot contain null characters.
• kill() throws a RangeError when the signal is outside the supported range.

For task-oriented examples, refer to Execute commands.

destroy stops the container and optionally returns a custom error message to the monitor() error callback.

this.ctx.container.destroy("Manually Destroyed");

• error (optional): A string that will be sent to the error handler of the monitor method. This is useful for logging or debugging purposes.

• A promise that returns once the container is destroyed.

signal sends an IPC signal to the container, such as SIGKILL or SIGTERM. This is useful for stopping the container gracefully or forcefully.

const SIGTERM = 15;
this.ctx.container.signal(SIGTERM);

• signal: a number representing the signal to send to the container. This is typically a POSIX signal number, such as SIGTERM (15) or SIGKILL (9).

• None.

getTcpPort returns a TCP port from the container. This can be used to communicate with the container over TCP and HTTP.

const port = this.ctx.container.getTcpPort(8080);
const res = await port.fetch("http://container/set-state", {
	body: initialState,
	method: "POST",
});

const conn = this.ctx.container.getTcpPort(8080).connect("10.0.0.1:8080");
await conn.opened;

try {
	if (request.body) {
		await request.body.pipeTo(conn.writable);
	}
	return new Response(conn.readable);
} catch (err) {
	console.error("Request body piping failed:", err);
	return new Response("Failed to proxy request body", { status: 502 });
}

• port (number): a TCP port number to use for communication with the container.

• TcpPort: a TcpPort object representing the TCP port. This object can be used to send requests to the container over TCP and HTTP.

monitor returns a promise that resolves when a container exits and errors if a container errors. This is useful for setting up callbacks to handle container status changes in your Workers code.

class MyContainer extends DurableObject {
	constructor(ctx, env) {
		super(ctx, env);
		function onContainerExit() {
			console.log("Container exited");
		}

		// the "err" value can be customized by the destroy() method
		async function onContainerError(err) {
			console.log("Container errored", err);
		}

		this.ctx.container.start();
		this.ctx.container.monitor().then(onContainerExit).catch(onContainerError);
	}
}

• None

• A promise that resolves when the container exits.

interceptOutboundHttp routes outbound HTTP requests matching a hostname, hostname glob, IP address, IP:port, or CIDR range through a WorkerEntrypoint. Can be called before or after starting the container. Open connections pick up the new handler without being dropped.

const worker = this.ctx.exports.MyWorker({ props: { message: "hello" } });

// Match a specific hostname
this.ctx.container.interceptOutboundHttp("api.example.com", worker);

// Match a hostname glob pattern
this.ctx.container.interceptOutboundHttp("*.example.com", worker);

// Match an IP:port
await this.ctx.container.interceptOutboundHttp("15.0.0.1:80", worker);

// Match a CIDR range (IPv4 and IPv6)
await this.ctx.container.interceptOutboundHttp("123.123.123.123/23", worker);

• target (string): A hostname, hostname glob (for example, *.example.com), IP address, IP:port, or CIDR range to match.
• worker (WorkerEntrypoint): A WorkerEntrypoint instance to handle matching requests.

• None.

interceptAllOutboundHttp routes all outbound HTTP requests from the container through a WorkerEntrypoint, regardless of destination.

await this.ctx.container.interceptAllOutboundHttp(worker);

• worker (WorkerEntrypoint): A WorkerEntrypoint instance to handle all outbound HTTP requests.

• A promise that resolves once the intercept rule is installed.

interceptOutboundHttps routes outbound HTTPS requests matching a hostname or hostname glob through a WorkerEntrypoint. Works the same way as interceptOutboundHttp but for HTTPS traffic. The container must trust the CA certificate at /etc/cloudflare/certs/cloudflare-containers-ca.crt for HTTPS interception to work.

Supports glob patterns where * matches any sequence of characters.

const worker = this.ctx.exports.MyWorker({ props: {} });

// Match a specific hostname
this.ctx.container.interceptOutboundHttps("api.example.com", worker);

// Match a hostname glob pattern
this.ctx.container.interceptOutboundHttps("*.example.com", worker);

// Intercept all HTTPS traffic
this.ctx.container.interceptOutboundHttps("*", worker);

• target (string): A hostname or hostname glob pattern to match. Use * to intercept all HTTPS traffic.
• worker (WorkerEntrypoint): A WorkerEntrypoint instance to handle matching requests.

• None.

• Container class reference — the recommended high-level API built on top of this interface
• Containers overview
• Get started with Containers
• SQLite storage API — persist state across container restarts
• Durable Objects — the underlying platform that powers Containers