[Containers] Document scheduling policies and snapshots

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

@@ -0,0 +1,56 @@
+---
+title: Snapshot and restore Container state
+description: Persist point-in-time container filesystem with experimental snapshot APIs.
+products:
+  - containers
+date: 2026-09-03
+---
+
+import { TypeScriptExample } from "~/components";
+
+[Containers](/containers/) now support experimental snapshot APIs 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()` to capture the full container filesystem. The example uses the [low-level Durable Object container API](/durable-objects/api/container/). Create snapshots from a container that is already running:
+
+<TypeScriptExample filename="src/index.ts">
+
+```ts
+import { DurableObject } from "cloudflare:workers";
+
+export class MyDurableObject extends DurableObject {
+	async saveSnapshot() {
+		const containerSnapshot = await this.ctx.container.snapshotContainer({});
+
+		await this.ctx.storage.put("containerSnapshot", containerSnapshot);
+	}
+}
+```
+
+</TypeScriptExample>
+
+Later, load the saved snapshot handle and restore it with `start()`:
+
+<TypeScriptExample filename="src/index.ts">
+
+```ts
+import { DurableObject } from "cloudflare:workers";
+
+export class MyDurableObject extends DurableObject {
+	async restoreSnapshot() {
+		const containerSnapshot =
+			await this.ctx.storage.get<ContainerSnapshot>("containerSnapshot");
+
+		if (!containerSnapshot) {
+			return;
+		}
+
+		this.ctx.container.start({ containerSnapshot });
+	}
+}
+```
+
+</TypeScriptExample>
+
+Snapshots are immutable.
+
+For more information, refer to [Snapshots](/containers/guides/snapshots/) and [Durable Object Container](/durable-objects/api/container/).

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

@@ -0,0 +1,50 @@
+---
+title: Configure Container image and instance size at runtime
+description: The durable_object scheduling policy gives each Durable Object control of Container configuration.
+products:
+  - containers
+date: 2026-09-28
+---
+
+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.
+
+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,
+	instance: "standard-2",
+});
+```
+
+</TypeScriptExample>
+
+Durable Object-managed Container instances have independent lifecycles and do not participate in application-wide image rollouts. The existing `default` policy and its rollout behavior are unchanged.
+
+For configuration, runtime sizing, snapshots, and update behavior, refer to [Scheduling Policies](/containers/configuration/scheduling-policy/).

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 `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/).
+
+With the `durable_object` policy, Wrangler prepares the named images for the application. Durable Object code can access their immutable references. The code selects an image and instance size when it calls `ctx.container.start()`. Running instances do not participate in application-wide image rollouts.
+
+Worker code goes live on deploy before any application-wide Container rollout finishes. Refer to [Deploy Containers](/containers/guides/deploy/).
 
 ## Lifecycle of a Request
 
@@ -41,8 +42,7 @@ state associated with each instance.
 
 ### 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 `default` policy uses the application image and instance type from Wrangler configuration. The `durable_object` policy uses the `image` and `instance` options supplied to `ctx.container.start()`.
 
 :::note
 Durable Objects and their associated Container instances are not guaranteed to run in the
@@ -52,12 +52,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
 
@@ -114,13 +109,14 @@ The [`Container` class](/containers/reference/container-class/) provides hooks t
 
 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, 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/environment-variables.mdx

@@ -3,7 +3,7 @@ pcx_content_type: reference
 title: Environment Variables
 description: Runtime and user-defined environment variables available inside Container instances.
 sidebar:
-  order: 2
+  order: 3
 products:
   - containers
 ---

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

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

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

@@ -3,13 +3,17 @@ pcx_content_type: reference
 title: Rollouts
 description: How container instances update after a deploy, including step percentages, grace periods, and rollout modes.
 sidebar:
-  order: 4
+  order: 5
 products:
   - containers
 ---
 
 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.

src/content/docs/containers/configuration/scaling-and-routing.mdx

@@ -3,7 +3,7 @@ pcx_content_type: reference
 title: Scaling and Routing
 description: Scale Container instances using explicit IDs or the getRandom helper for stateless load balancing.
 sidebar:
-  order: 3
+  order: 4
 products:
   - containers
 ---

src/content/docs/containers/configuration/scheduling-policy.mdx

@@ -0,0 +1,171 @@
+---
+pcx_content_type: concept
+title: Scheduling Policies
+description: Choose whether Container configuration is managed centrally or by each Durable Object at runtime.
+sidebar:
+  order: 1
+products:
+  - containers
+---
+
+import { TypeScriptExample, WranglerConfig } from "~/components";
+
+A scheduling policy determines where you configure a Container image and instance size. It also determines how image updates apply. Choose the policy when you create the Container application.
+
+| Policy | Configure image and instance size | Image updates | Best for |
+| - | - | - | - |
+| `default` | In Wrangler configuration | Cloudflare applies application-wide configuration changes with [rollouts](/containers/configuration/rollouts/) | Services whose instances use the same image and instance size |
+| `durable_object` | In Durable Object code when calling `ctx.container.start()` | Application code selects an image each time it starts an instance | Sandboxes, agent environments, and other workloads that need per-instance configuration |
+
+The scheduling policy is immutable. To use a different policy, create a new Container application. Deleting and recreating an application also replaces its Container instances.
+
+:::note
+The `durable_object` scheduling policy is in public beta.
+:::
+
+## Use the default scheduling policy
+
+The `default` policy preserves the existing Containers behavior. Define one `image`, one `instance_type`, and application-level settings such as `max_instances` in Wrangler configuration. Omitting `scheduling_policy` selects `default`.
+
+<WranglerConfig>
+
+```jsonc
+{
+	"containers": [
+		{
+			"class_name": "ApiContainer",
+			"scheduling_policy": "default",
+			"image": "./api/Dockerfile",
+			"instance_type": "standard-1",
+			"max_instances": 5,
+		},
+	],
+}
+```
+
+</WranglerConfig>
+
+When you change the image or instance type and deploy, Cloudflare rolls out that change across the application. Refer to [Rollouts](/containers/configuration/rollouts/).
+
+## Use the Durable Object scheduling policy
+
+The `durable_object` policy moves per-instance decisions into your Durable Object. Wrangler associates the Container application with the Durable Object class, and your code supplies a startup image or snapshot and an optional instance size to `ctx.container.start()`.
+
+Configure the policy and the images that the Durable Object can start:
+
+<WranglerConfig>
+
+```jsonc
+{
+	"name": "agent-computer",
+	"main": "src/index.ts",
+	"compatibility_date": "$today",
+	"containers": [
+		{
+			"class_name": "AgentComputer",
+			"scheduling_policy": "durable_object",
+			"images": {
+				"base": {
+					"dockerfile": "./container/Dockerfile",
+				},
+			},
+		},
+	],
+	"durable_objects": {
+		"bindings": [
+			{
+				"name": "AGENT_COMPUTER",
+				"class_name": "AgentComputer",
+			},
+		],
+	},
+	"migrations": [
+		{
+			"tag": "v1",
+			"new_sqlite_classes": ["AgentComputer"],
+		},
+	],
+}
+```
+
+</WranglerConfig>
+
+Wrangler builds or resolves each named image, prepares it for the Containers runtime, and exposes its digest-pinned reference on `ctx.container.images`. Select an image and instance size when the Durable Object starts its Container:
+
+<TypeScriptExample filename="src/index.ts">
+
+```ts
+import { DurableObject } from "cloudflare:workers";
+
+export class AgentComputer extends DurableObject {
+	startContainer() {
+		if (this.ctx.container.running) {
+			return;
+		}
+
+		this.ctx.container.start({
+			image: this.ctx.container.images.base,
+			instance: "standard-2",
+			enableInternet: true,
+		});
+	}
+}
+```
+
+</TypeScriptExample>
+
+`ctx.container.start()` initiates startup and returns before the Container is ready to accept requests. Add an application-specific readiness check before sending traffic or calling [`exec()`](/durable-objects/api/container/#exec).
+
+### Configure named images
+
+Each key in `images` is a name you choose. Each value must specify exactly one image source. Use `dockerfile` for a path to a Dockerfile. Wrangler builds and uploads the image. You can also set `build_context` and `build_vars` for that image.
+
+Use `image` for a digest-pinned image in the Cloudflare managed registry. Use the form `registry.cloudflare.com/<ACCOUNT_ID>/<REPOSITORY>@sha256:<DIGEST>`.
+
+A configuration can contain up to 100 named images. An image name must contain between 1 and 128 characters.
+
+The image map is uploaded with the Worker version. Updating the map does not restart or replace running Container instances. Your application selects an image from the map when it starts an instance.
+
+### Choose an instance size at runtime
+
+Set `instance` in `ctx.container.start()` to one of the following named instance types:
+
+- `lite`
+- `standard-1`
+- `standard-2`
+- `standard-3`
+- `standard-4`
+
+If you omit `instance`, the Container uses `lite`. You can also supply a custom instance object:
+
+```ts
+this.ctx.container.start({
+	image: this.ctx.container.images.base,
+	instance: {
+		vcpu: 1,
+		memoryMib: 4096,
+		diskMb: 8000,
+	},
+});
+```
+
+The runtime uses camel case (`memoryMib` and `diskMb`). Wrangler's application-level `instance_type` object uses snake case (`memory_mib` and `disk_mb`) and only applies to the `default` policy. Refer to [Limits and Instance Types](/containers/platform/limits/).
+
+### Start from an image or snapshot
+
+For a new filesystem, pass `image` to `ctx.container.start()`. To restore a full filesystem snapshot, pass `containerSnapshot` instead. `image` and `containerSnapshot` are mutually exclusive because a snapshot already identifies the filesystem to restore.
+
+Refer to [Snapshots](/containers/guides/snapshots/) for the complete save and restore flow.
+
+### Manage updates from application code
+
+Container instances that use the `durable_object` policy do not participate in application-wide image rollouts. A running instance continues to use its startup image. Your application decides when to stop that instance and start it with another configured image.
+
+One Wrangler configuration can contain applications with both policies. This lets a Worker use centrally managed service Containers alongside Durable Object-managed sandboxes.
+
+## Related resources
+
+- [Durable Object Container API](/durable-objects/api/container/)
+- [Lifecycle of a Container](/containers/concepts/architecture/)
+- [Image Management](/containers/guides/image-management/)
+- [Wrangler Containers configuration](/workers/wrangler/configuration/#containers)

src/content/docs/containers/configuration/workers-connections.mdx

@@ -2,7 +2,7 @@
 title: Connect to Workers and Bindings
 pcx_content_type: concept
 sidebar:
-  order: 1
+  order: 2
 description: Access KV, R2, Durable Objects, and other bindings from a container.
 products:
   - containers