[Containers] Document scheduling policies and snapshots

src/content/changelog/containers/2026-09-30-durable-object-scheduling-policy.mdx

@@ -0,0 +1,54 @@
+---
+title: New scheduling policy for Containers to configure image and instance from Durable Objects
+description: The durable_object scheduling policy gives each Durable Object control of Container configuration.
+products:
+  - containers
+date: "2026-09-30T08:45:00-04:00"
+publish_future_dated_entry: true
+---
+
+import { TypeScriptExample, WranglerConfig } from "~/components";
+
+[Containers](/containers/) now support the `durable_object` scheduling policy in public beta. This policy lets a Durable Object select the image and instance size for a Container at runtime instead of using one centrally managed configuration for the application.
+
+To use custom images, configure the policy and one or more named images in Wrangler:
+
+<WranglerConfig>
+
+```jsonc
+{
+	"containers": [
+		{
+			"class_name": "AgentComputer",
+			"scheduling_policy": "durable_object",
+			"images": {
+				"base": {
+					"dockerfile": "./container/Dockerfile",
+				},
+			},
+		},
+	],
+}
+```
+
+</WranglerConfig>
+
+Wrangler prepares each image and exposes its immutable reference through `ctx.container.images`. Supply that reference and an instance size when you start the Container:
+
+<TypeScriptExample filename="src/index.ts">
+
+```ts
+this.ctx.container.start({
+	image: this.ctx.container.images.base,
+	enableInternet: false,
+	instance: "standard-2",
+});
+```
+
+</TypeScriptExample>
+
+The `durable_object` policy also supports the new [`cloudflare/debian-trixie` Cloudflare-managed image](/containers/guides/image-management/#use-the-cloudflare-managed-image), which includes Node.js 24.20.0 on Debian Trixie slim. Start it directly without configuring a named image.
+
+Durable Object-managed Container instances have independent lifecycles and do not participate in application-wide image rollouts.
+
+For configuration, runtime sizing, snapshots, and update behavior, refer to [Scheduling Policies](/containers/configuration/scheduling-policy/).

src/content/changelog/containers/2026-09-30-snapshots.mdx

@@ -0,0 +1,47 @@
+---
+title: Snapshot and restore Container filesystem
+description: Persist point-in-time container filesystem with snapshot APIs in public beta.
+products:
+  - containers
+date: "2026-09-30T08:45:00-04:00"
+publish_future_dated_entry: true
+---
+
+import { TypeScriptExample } from "~/components";
+
+[Containers](/containers/) now support snapshot APIs in public beta for saving and restoring point-in-time filesystem state. Create a snapshot first, then pass it back to `start()` to restore files after container sleep, restart, or handoff to another Durable Object.
+
+Use `snapshotContainer()` through the [Durable Object Container API](/containers/api/durable-object-container/) to capture the full container filesystem. Create a snapshot from a running Container, store its handle, and pass that handle to `start()` when you restore it later:
+
+<TypeScriptExample filename="src/index.ts">
+
+```ts
+import { DurableObject } from "cloudflare:workers";
+
+export class MyDurableObject extends DurableObject {
+	async saveSnapshot() {
+		// Create a snapshot from the running Container.
+		const containerSnapshot = await this.ctx.container.snapshotContainer({});
+
+		await this.ctx.storage.put("containerSnapshot", containerSnapshot);
+	}
+
+	async restoreSnapshot() {
+		// Restore the saved snapshot later.
+		const containerSnapshot =
+			await this.ctx.storage.get<ContainerSnapshot>("containerSnapshot");
+
+		if (!containerSnapshot) {
+			return;
+		}
+
+		this.ctx.container.start({ containerSnapshot, enableInternet: false });
+	}
+}
+```
+
+</TypeScriptExample>
+
+Snapshots are only supported for Container applications that use the [`durable_object` scheduling policy](/containers/configuration/scheduling-policy/#use-the-durable-object-scheduling-policy). Snapshots are immutable, so create a new snapshot to persist filesystem changes made after a restore.
+
+For more information, refer to [Snapshots](/containers/guides/snapshots/) and the [Durable Object Container API](/containers/api/durable-object-container/).

src/content/docs/containers/api/container-class.mdx

@@ -12,9 +12,17 @@ import { PackageManagers, TypeScriptExample } from "~/components";
 
 The [`Container` class](https://github.com/cloudflare/containers) from [`@cloudflare/containers`](https://www.npmjs.com/package/@cloudflare/containers) provides lifecycle helpers for container instances. For direct lifecycle control, use the [Durable Object Container API](/containers/api/durable-object-container/).
 
+**`Container` extends [`DurableObject`](/durable-objects/api/base/).** The Durable Object manages routing, persistent state, and lifecycle hooks, while the container process runs your image inside a Linux VM. Because your subclass is a Durable Object, you have access to the full Durable Object API — including [`this.ctx.storage`](/durable-objects/api/sqlite-storage-api/) for persistent SQLite-backed storage and [`this.ctx.id`](/durable-objects/api/id/) for the unique instance identifier. Use Durable Object storage to persist state that should survive container restarts, such as configuration, user data, or task results.
+
+:::note
+The `Container` class does not support applications that use the [`durable_object` scheduling policy](/containers/configuration/scheduling-policy/#use-the-durable-object-scheduling-policy). It is available only with the `default` scheduling policy. For `durable_object` applications, use the [Durable Object Container API](/containers/api/durable-object-container/).
+:::
+
 To move an existing application to direct control, refer to [Migrate to the Durable Object Container API](/containers/guides/migrate-to-durable-object-container-api/).
 
-**`Container` extends [`DurableObject`](/durable-objects/api/base/).** The Durable Object manages routing, persistent state, and lifecycle hooks, while the container process runs your image inside a Linux VM. Because your subclass is a Durable Object, you have access to the full Durable Object API — including [`this.ctx.storage`](/durable-objects/api/sqlite-storage-api/) for persistent SQLite-backed storage and [`this.ctx.id`](/durable-objects/api/id/) for the unique instance identifier. Use Durable Object storage to persist state that should survive container restarts, such as configuration, user data, or task results.
+## Use the Container class
+
+Start by installing the `@cloudflare/containers` package:
 
 <PackageManagers pkg="@cloudflare/containers" />
 

src/content/docs/containers/api/durable-object-container.mdx

@@ -9,7 +9,7 @@ products:
   - durable-objects
 ---
 
-import { TypeScriptExample } from "~/components";
+import { Badge, TypeScriptExample } from "~/components";
 
 Each [container](/containers/) is managed and proxied by a Durable Object. The Durable Object manages routing and persistent state. The container process runs your image inside a Linux VM.
 
@@ -35,7 +35,11 @@ export class MyDurableObject extends DurableObject<Env> {
 			throw new Error("No container is configured for this Durable Object");
 		}
 		if (!container.running) {
-			container.start();
+			// With the `default` scheduling policy, call `container.start()` without options.
+			container.start({
+				image: container.images.base,
+				enableInternet: false,
+			});
 			await this.ctx.storage.put("lastStartedAt", Date.now());
 		}
 	}
@@ -54,6 +58,16 @@ export class MyDurableObject extends DurableObject<Env> {
 
 ## Attributes
 
+### `images` <Badge text="durable_object policy only" variant="note" size="small" />
+
+`images` is a read-only map generated from the [`images` field in the application's Wrangler configuration](/workers/wrangler/configuration/#durable_object-scheduling-policy). Wrangler builds or resolves each named image and exposes its digest-pinned reference under the same key. This attribute is available only for applications that use the [`durable_object` scheduling policy](/containers/configuration/scheduling-policy/#use-the-durable-object-scheduling-policy).
+
+```js
+const image = this.ctx.container.images.base;
+```
+
+Pass a value from this map as the `image` option to [`start()`](#start).
+
 ### `running`
 
 `running` is `true` when the container is running. It does not confirm that the container is ready to accept requests.
@@ -68,21 +82,55 @@ this.ctx.container.running;
 
 `start()` boots a container. It returns before the container is ready to accept requests. Confirm readiness before sending traffic.
 
+The required options depend on the application's scheduling policy.
+
 ```js
+// `default` scheduling policy:
+// The image and instance size come from Wrangler configuration.
 this.ctx.container.start();
+
+// `durable_object` scheduling policy:
+// Pass an image and choose whether to allow outbound Internet access.
+// The instance size is optional and defaults to "lite".
+this.ctx.container.start({
+	image: this.ctx.container.images.base,
+	enableInternet: true,
+});
 ```
 
 #### Parameters
 
-- `options` (`object`, optional): Common container startup options:
+- `options` (`object`, conditionally required): Startup options. Required for applications that use the `durable_object` scheduling policy and optional for applications that use the `default` scheduling policy.
   - `env` (`Record<string, string>`, optional): Environment variables to pass to the container.
   - `entrypoint` (`string[]`, optional): Command and arguments to run in the container.
   - `enableInternet` (`boolean`, required): Whether to allow outbound Internet access. Required when you pass `options`.
+  - `image` (`string`, conditionally required) <Badge text="durable_object policy only" variant="note" size="small" />: Image reference to start. Required unless you pass `containerSnapshot`. Pass the [`cloudflare/debian-trixie` managed image](/containers/guides/image-management/#use-the-cloudflare-managed-image) or a value from [`ctx.container.images`](#images).
+  - `instance` (`string | object`, optional) <Badge text="durable_object policy only" variant="note" size="small" />: Instance size. Pass `"lite"`, `"standard-1"`, `"standard-2"`, `"standard-3"`, `"standard-4"`, or a custom object with `vcpu`, `memoryMib`, and `diskMb` properties. Defaults to `"lite"`.
+  - `containerSnapshot` (`ContainerSnapshotRestoreParams`, optional) <Badge text="durable_object policy only" variant="note" size="small" />: Snapshot handle to restore before startup. Pass the `ContainerSnapshot` returned by [`snapshotContainer()`](#snapshotcontainer), or an object containing its `id`. You cannot pass both `containerSnapshot` and `image`.
+  - `labels` (`Record<string, string>`, optional): Up to 10 labels that [`inspect()`](#inspect) returns. Label names must contain 1 to 16 bytes. Label values can contain up to 64 bytes. Names and values cannot contain control characters.
 
 #### Return values
 
 - `void`: No return value.
 
+### `inspect`
+
+`inspect()` returns the image and labels for a running container. It returns `null` when no container is running.
+
+```js
+const containerInfo = await this.ctx.container.inspect();
+```
+
+#### Parameters
+
+- None.
+
+#### Return values
+
+- `Promise<ContainerInfo | null>`: Resolves with `null` when no container is running. Otherwise, it resolves with a `ContainerInfo` object containing:
+  - `image` (`string`): Image reference passed to [`start()`](#start). The value is an empty string while the container is starting and for a container restored from `containerSnapshot`.
+  - `labels` (`Record<string, string>`): Labels passed to [`start()`](#start).
+
 ### `exec`
 
 `exec()` starts another process inside an already-running container. It does not start a stopped container.
@@ -170,6 +218,30 @@ With `stderr: "combined"`, `stderr` is `null` on `ExecProcess` and an empty `Arr
 
 For task-oriented examples, refer to [Execute commands](/containers/guides/execute-commands/).
 
+### `snapshotContainer` <Badge text="durable_object policy only" variant="note" size="small" />
+
+`snapshotContainer()` creates a point-in-time snapshot of the running container filesystem. This method is only supported for applications that use the [`durable_object` scheduling policy](/containers/configuration/scheduling-policy/#use-the-durable-object-scheduling-policy).
+
+```js
+const snapshot = await this.ctx.container.snapshotContainer({
+	name: "before-upgrade",
+});
+```
+
+#### Parameters
+
+- `options` (`ContainerSnapshotOptions`): Snapshot configuration:
+  - `name` (`string`, optional): Human-readable name for the snapshot.
+
+#### Return values
+
+- `Promise<ContainerSnapshot>`: Resolves with an opaque handle for the stored filesystem snapshot. The snapshot data is not returned to the Worker. The handle contains:
+  - `id` (`string`): Unique snapshot identifier. Pass the returned `ContainerSnapshot` to [`start()`](#start) as `containerSnapshot`, or store it for a later restore.
+  - `size` (`number`): Snapshot size in bytes.
+  - `name` (`string`, optional): Human-readable name supplied in `options`.
+
+Container snapshots are immutable. Snapshot handles have an implicit 30-day time-to-live that refreshes when you restore them. For the complete save and restore flow, refer to [Use snapshots](/containers/guides/snapshots/).
+
 ### `destroy`
 
 `destroy()` stops the container and can include an optional reason for the operation.
@@ -272,7 +344,11 @@ interface Env {}
 class MyDurableObject extends DurableObject<Env> {
 	startAndMonitor() {
 		const container = this.ctx.container;
-		container.start();
+		// With the `default` scheduling policy, call `container.start()` without options.
+		container.start({
+			image: container.images.base,
+			enableInternet: false,
+		});
 		this.ctx.waitUntil(
 			container
 				.monitor()
@@ -374,3 +450,4 @@ await this.ctx.container.interceptOutboundHttps("*", worker);
 - [Get started with Containers](/containers/get-started/): Deploy your first container.
 - [SQLite storage API](/durable-objects/api/sqlite-storage-api/): Persist state across container restarts.
 - [Durable Objects](/durable-objects/): The underlying platform that powers Containers.
+- [Snapshots](/containers/guides/snapshots/): Save and restore container filesystems.

src/content/docs/containers/concepts/architecture.mdx

@@ -10,12 +10,13 @@ products:
 
 ## Deployment
 
-After you deploy an application with a Container, your image is uploaded to
-[Cloudflare's Registry](/containers/guides/image-management/) and distributed globally to Cloudflare's Network.
-Cloudflare will pre-schedule instances and pre-fetch images across the globe to ensure quick start
-times when scaling up the number of concurrent container instances.
+How images and running Container instances update depends on the [scheduling policy](/containers/configuration/scheduling-policy/) for the application.
 
-Worker code goes live on deploy. Container instances update with a [rollout](/containers/configuration/rollouts/). Refer to [Deploy Containers](/containers/guides/deploy/).
+With the `durable_object` policy, Wrangler prepares the named images for the application. Durable Object code can access their immutable references and selects an image and instance size when it calls `ctx.container.start()`. When an image reference changes, the Durable Object code decides whether to stop the running Container and start it with the new image or let it continue with the previous image. This application-controlled restart is how you roll out image changes with the `durable_object` policy. These instances do not participate in application-wide image rollouts.
+
+With the `default` policy, Wrangler uploads or resolves the application image. Cloudflare distributes that image across its network and prepares capacity for new instances. Changes to the image or instance type use a [rollout](/containers/configuration/rollouts/).
+
+Worker code goes live on deploy before any application-wide Container rollout finishes. Refer to [Deploy Containers](/containers/guides/deploy/).
 
 ## Container instance lifecycle
 
@@ -70,8 +71,7 @@ developers to address and route to specific container instances, run code when a
 
 ### Starting a Container
 
-When a Durable Object instance requests to start a new container instance, the **nearest location
-with a pre-fetched image** is selected.
+When a Durable Object requests a new Container instance, Cloudflare selects eligible capacity with the required image available. The `durable_object` policy uses the `image` and `instance` options supplied to `ctx.container.start()`. The `default` policy uses the application image and instance type from Wrangler configuration.
 
 :::note
 Durable Objects and their associated Container instances are not guaranteed to run in the
@@ -81,12 +81,7 @@ Container placement is optimized for request routing and startup speed, so a Con
 start in a different location than its Durable Object.
 :::
 
-Starting additional container instances will use other locations with pre-fetched images,
-and Cloudflare will automatically begin prepping additional machines behind the scenes
-for additional scaling and quick cold starts. Because there are a finite number of pre-warmed
-locations, some container instances may be started in locations that are farther away from
-the end-user. This is done to ensure that the container instance starts quickly. You are
-only charged for actively running instances and not for any unused pre-warmed images.
+Starting additional Container instances can use other locations where the image is available. Cloudflare prepares additional capacity as demand grows. Because prepared capacity is finite, some Container instances may start in locations farther from the end user. You are only charged for actively running instances, not for prepared images that are not running.
 
 #### Cold starts
 
@@ -145,13 +140,14 @@ The [`Container` class](/containers/api/container-class/) adds hooks that run Wo
 
 Refer to the [status hooks example](/containers/examples/status-hooks/) for a full implementation.
 
-#### Persistent disk
+#### Use snapshots
 
-All disk is ephemeral. When a Container instance goes to sleep, the next time
-it is started, it will have a fresh disk as defined by its container image.
+All disk is ephemeral by default. When a Container instance goes to sleep, the
+next time it starts, it uses a fresh disk from the container image.
 
-Snapshots are coming soon, which allow the user to quickly persist and restore the disk
-from an entire container or a directory.
+If you need point-in-time filesystem state, Container applications that use the [`durable_object` scheduling policy](/containers/configuration/scheduling-policy/#use-the-durable-object-scheduling-policy) can create and restore a snapshot.
+Snapshots are immutable, so later file changes require a new snapshot. For more
+information, refer to [Snapshots](/containers/guides/snapshots/).
 
 You can also use [FUSE](/containers/examples/r2-fuse-mount/) to persist disk
 to R2 or other object storage backends. Though you should not expect native

src/content/docs/containers/configuration/index.mdx

@@ -1,7 +1,7 @@
 ---
 pcx_content_type: navigation
 title: Configuration
-description: Configure Containers in Wrangler, connect them to Workers and bindings, set environment variables, tune scaling and routing, and manage rollouts.
+description: Choose a scheduling policy, configure Containers in Wrangler, connect bindings, set environment variables, tune scaling, and manage rollouts.
 sidebar:
   order: 5
   group:

src/content/docs/containers/configuration/rollouts.mdx

@@ -10,6 +10,10 @@ products:
 
 import { WranglerConfig, PackageManagers } from "~/components";
 
+:::note
+Rollouts apply to Container applications that use the [`default` scheduling policy](/containers/configuration/scheduling-policy/). Durable Object-managed Container instances do not participate in application-wide rollouts; application code selects their image when it calls `ctx.container.start()`.
+:::
+
 ## How rollouts work
 
 A **rollout** applies a target container application configuration after you [deploy](/containers/guides/deploy/) a Worker that uses Containers. The target can change the image, instance type, limits, placement, or other container settings.
@@ -144,12 +148,12 @@ Use none when the deploy should not publish a new image or start a container ins
 			},
 		],
 	},
-	"migrations": [
-		{
-			"tag": "v1",
-			"new_sqlite_classes": ["MyContainer"],
+	"exports": {
+		"MyContainer": {
+			"type": "durable-object",
+			"storage": "sqlite",
 		},
-	],
+	},
 }
 ```