Durable Object Container API·续2

Parameters

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

Return values

  • Fetcher: Object used to send HTTP requests or TCP connections to the container port.

monitor

monitor() returns a promise that resolves when a container exits and rejects if the container errors. Use it to handle container status changes in your Workers code.

A pending monitor() call prevents eviction until the container exits or for up to 15 minutes, whichever comes first. Starting another operation later can extend the Durable Object's time in memory.

import { DurableObject } from "cloudflare:workers";

class MyDurableObject extends DurableObject {
    startAndMonitor() {
        const container = this.ctx.container;
        // With the `default` scheduling policy, call `container.start()` without options.
        container.start({
            image: container.images.base,
            enableInternet: false,
        });
        this.ctx.waitUntil(
            container
                .monitor()
                .then(() => console.log("Container exited"))
                .catch((error) => console.error("Container errored", error)),
        );
    }
}

import { DurableObject } from "cloudflare:workers";

interface Env {}

class MyDurableObject extends DurableObject<Env> {
    startAndMonitor() {
        const container = this.ctx.container;
        // With the `default` scheduling policy, call `container.start()` without options.
        container.start({
            image: container.images.base,
            enableInternet: false,
        });
        this.ctx.waitUntil(
            container
                .monitor()
                .then(() => console.log("Container exited"))
                .catch((error) => console.error("Container errored", error)),
        );
    }
}

A monitor() promise does not carry over when the Durable Object restarts, for example after a deploy. If running is true when the Durable Object starts, call monitor() again to observe the container.

Parameters

  • None.

Return values

  • Promise<void>: Settles when the container stops, including a container that stopped before the call. The outcome depends on how the container stopped:
  • It resolves when the main process exits with code 0, or when destroy() stops the container without an error value.
  • It rejects with an Error that has an exitCode property when the main process exits with another code.
  • It rejects with the value passed to destroy(), when there is one.
  • It rejects with an error that describes the failure when the container stops for another reason.

Exceptions

  • monitor() throws an Error when this Durable Object instance has no container. An instance has a container after it calls start(), or when a container was already running as the instance started.

interceptOutboundHttp

interceptOutboundHttp() routes outbound HTTP requests matching a hostname, hostname glob, IP address, IP:port, or CIDR range through a Fetcher. Call it before or after starting the container. An intercept lasts until the container stops, so register intercepts again for each new container. Registering a target again replaces its handler, and open connections use the new handler without being dropped.

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

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

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

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

// Match an IPv4 CIDR range. Register an IPv6 range separately.
await this.ctx.container.interceptOutboundHttp("203.0.113.0/24", worker);

In a container started with enableInternet: false, no public resolver answers DNS lookups. Lookups resolve as follows:

  • A and AAAA lookups for an intercepted hostname return a placeholder address that routes the request to the intercept.
  • interceptAllOutboundHttp() and a * hostname target make every hostname resolve, including hostnames that do not exist.
  • IP address and CIDR targets add no DNS answers, except for 0.0.0.0/0 and ::/0, which make every hostname resolve.
  • Every other lookup times out, including a lookup made before you register an intercept.

Intercept limit

A container has 128 intercept entries, which interceptOutboundHttp(), interceptOutboundHttps(), and interceptAllOutboundHttp() share. Each new target uses entries as follows:

  • A hostname or hostname glob, including *, uses two entries, one for IPv4 and one for IPv6.
  • An IP address, IP:port, or CIDR range uses one entry.
  • The interceptAllOutboundHttp() rule uses two entries.

A hostname intercepted for both HTTP and HTTPS is two targets and uses four entries. A container can hold up to 64 hostname targets, or up to 128 IP address and CIDR targets. Registering an existing target again uses no more entries.

You cannot remove an intercept while the container runs. To route a changing set of hostnames, register interceptAllOutboundHttp() or the * target once. Then choose the behavior for each hostname inside the WorkerEntrypoint, for example from its props. To change the props, register the rule again with new props.

When a new target does not fit, awaiting the call throws an Error with the message You can't configure more than 128 egress interceptors. Intercepts registered earlier keep working.

Parameters

  • addr ( string): Hostname, hostname glob (for example, *.example.com), IP address, IP:port, or CIDR range to match.
  • binding ( Fetcher): Worker entrypoint or service binding that handles matching requests.

Return values

  • Promise<void>: Resolves when the intercept rule is installed.

Exceptions

  • Awaiting interceptOutboundHttp() throws an Error when addr is new and the container does not have enough free entries for it. For more information, refer to Intercept limit.

interceptAllOutboundHttp

interceptAllOutboundHttp() routes outbound HTTP requests on port 80 from the container through a Fetcher, regardless of destination.

This rule does not intercept other ports, including HTTPS on port 443. To intercept HTTPS as well, also register interceptOutboundHttps("*"). In a container started with enableInternet: true, connections that no intercept covers reach the Internet directly. To block them, start the container with enableInternet: false.

Register hostname intercepts before interceptAllOutboundHttp(). A hostname intercept that interceptOutboundHttp() registers first keeps receiving its requests, even after you register this rule again. A hostname intercept registered after this rule receives no requests.

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

Parameters

  • binding ( Fetcher): Worker entrypoint or service binding that handles all outbound HTTP requests.

Return values

  • Promise<void>: Resolves when the intercept rule is installed.

Exceptions

  • Awaiting interceptAllOutboundHttp() throws an Error when the rule is not registered yet and the container does not have two free entries. For more information, refer to Intercept limit.

interceptOutboundHttps

interceptOutboundHttps() routes outbound HTTPS requests matching a hostname or hostname glob, with an optional port, through a Fetcher. It works like interceptOutboundHttp() but handles HTTPS traffic. The container must trust the CA certificate at /etc/cloudflare/certs/cloudflare-containers-ca.crt for HTTPS interception.

Hostname globs support * to match any sequence of characters.

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

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

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

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

interceptOutboundHttps() intercepts HTTPS on port 443 by default. To use another port, include it in the target, for example "api.example.com:8443". It matches the hostname that the client sends. In a container started with enableInternet: false, HTTPS requests to a bare IP address fail while a * intercept is registered.

Parameters

  • addr ( string): Hostname or hostname glob pattern to match, with an optional port such as api.example.com:8443. Use * to intercept all HTTPS traffic on port 443.
  • binding ( Fetcher): Worker entrypoint or service binding that handles matching requests.

Return values

  • Promise<void>: Resolves when the intercept rule is installed.

Exceptions

  • Awaiting interceptOutboundHttps() throws an Error when addr is new and the container does not have enough free entries for it. For more information, refer to Intercept limit.

Was this helpful?

YesNo

On this page

Durable Object Container API·续2 - 图1Docs

{"@context":"https://schema.org","@type":"TechArticle","@id":"https://developers.cloudflare.com/containers/api/durable-object-container/#page","headline":"Durable Object Container API","description":"Access and manage containers associated with a Durable Object, including start, stop, and interaction methods.","url":"https://developers.cloudflare.com/containers/api/durable-object-container/","inLanguage":"en","image":"https://developers.cloudflare.com/containers/api/durable-object-container/og.png?v=f13dbe1f95442c69","dateModified":"2026-09-30","publisher":{"@type":"Organization","name":"Cloudflare","description":"One platform for your apps, agents, and workforce. Build, secure, and scale without managing infrastructure","url":"https://www.cloudflare.com/","sameAs":["https://github.com/cloudflare","https://www.linkedin.com/company/cloudflare","https://x.com/cloudflare"],"logo":{"@type":"ImageObject","url":"https://developers.cloudflare.com/logo.svg"},"address":{"@type":"PostalAddress","streetAddress":"101 Townsend St","addressLocality":"San Francisco","addressRegion":"CA","postalCode":"94107","addressCountry":"US"},"contactPoint":[{"@type":"ContactPoint","contactType":"Customer Support","url":"https://support.cloudflare.com/","availableLanguage":["English"]},{"@type":"ContactPoint","contactType":"Sales","url":"https://www.cloudflare.com/contact/","availableLanguage":["English"]}]},"isPartOf":{"@type":"WebSite","@id":"https://developers.cloudflare.com/#website","name":"Cloudflare Docs","url":"https://developers.cloudflare.com/"}}

description: Code examples showing how to use Containers with Workers for stateless routing, cron jobs, WebSockets, and more. title: Examples image: https://developers.cloudflare.com/containers/examples/og.png?v=e9cf0d7d69da226c

Skip to content

Documentation Index
Fetch the complete documentation index at: https://developers.cloudflare.com/containers/llms.txt
Use this file to discover all available pages before exploring further.