Cloudflare Sandbox SDK 1.0: execution state, snapshots, and migration boundaries

A sandbox has state, authority, and a lifecycle

Cloudflare announced Sandbox SDK 1.0 on September 30, 2026. The important change for an agent or code-execution service is not simply “a newer SDK.” The announcement moves the operational center of a sandbox toward the Durable Object that owns it: the class can start a container with a selected image and instance size, decide when it stops, stream command I/O, and expose preview ports through Worker-controlled handling.

That gives a useful implementation question: which durable object is allowed to resume, inspect, stop, or publish the work of this execution? A container is not an anonymous scratch directory. Its filesystem can contain an unfinished build, a generated artifact, cached dependencies, or material that must be discarded. Its preview can become a network-facing capability. Its outbound requests can touch a remote system. Treating all of this as one generic “agent sandbox” hides the boundaries that need separate tests.

1. 1Authenticated task
2. 2Durable Object owner
3. 3chosen image and instance
4. 4container run

1. 1Container filesystem
2. 2immutable snapshot handle
3. 3explicit restore
4. 4new run

1. 1Preview port
2. 2Worker hostname and authentication
3. 3authorized viewer

1. 1Task finish or idle policy
2. 2stop decision
3. 3retained snapshot or discard record

The existing Cloudflare foundation chapter explains route-to-binding authority and deployment evidence. This update fills a narrower gap: a running execution environment now has its own state transition and recovery contract. A successful Worker deployment does not prove which filesystem state was resumed, whether internet access was enabled, or whether an old sandbox stayed alive.

Separate SDK availability from beta platform features

The September 30 post says Sandbox SDK 1.0 is available. It also says that container snapshots and the durable_object scheduling policy are in public beta. Those statements must not be flattened into “all of Sandbox 1.0 is generally available.” Availability of a package version, a runtime feature’s beta status, and a particular account’s enablement are separate facts.

The scheduling-policy announcement says a Durable Object can choose an image and instance size at runtime rather than relying on one centrally managed application configuration. It also says Durable Object-managed instances have independent lifecycles and do not participate in application-wide image rollouts. That changes release review: an image deployment cannot be assumed to restart or replace every running execution. Record the image reference, the instance choice, the owner object, and the reason the run ended for each task. Do not infer capacity, isolation strength, uptime, or account availability from this announcement.

The same announcement shows an explicit enableInternet choice when starting a container. Use that as an authority decision, not as a convenience default. A build that only needs checked-in source and a local compiler has a different outbound boundary from a task that must call an allowlisted artifact registry. The dated sources do not establish a universal egress policy, so define one for the application and test it with a harmless deny case.

A snapshot is a recovery input, not a mutable workspace

Cloudflare’s separate snapshot update describes public-beta APIs for saving and restoring point-in-time container filesystem state. It says snapshots require the durable_object scheduling policy and are immutable. Therefore a restore is not permission to quietly rewrite a historical checkpoint: filesystem changes made after restore require a new snapshot to be persisted.

This makes a small state ledger more valuable than a bare snapshot handle. For each checkpoint, retain the task identifier, owner, source revision or input digest, image reference, snapshot creation time, restore purpose, retention decision, and the policy that permitted it. Keep secret names in an execution design if they matter, but never write values into the snapshot record, source repository, preview URL, or agent-visible log. The changelog says Worker code can handle outbound requests so credentials and bindings remain in the Worker; it does not prove that every application has correctly implemented that separation.

Snapshots also do not prove that a build is reproducible. A snapshot preserves a filesystem state; it does not by itself identify the user authorization, input provenance, network effects, image behavior, or commands that created it. A recovery flow should label a restored run as restored, then require the same output checks and authorization checks as a fresh run before publishing an artifact or taking an external action.

Rehearse the migration before moving state

The SDK 1.0 announcement says 0.x applications continue to run and receive bug and security fixes until December 31, 2026. It also says moving an existing class to the new policy is one-way, and recommends rehearsal. “One-way” is an operational property, not an invitation to migrate on a production task.

Use a disposable fixture before any real migration. The following is an offline, unexecuted planning fixture, not a command sequence or evidence that a Cloudflare account is configured:

Fixture state	Intended check	Passing observation
New owner with no snapshot	Start a sandbox with the chosen image, size, and explicit network policy	The run record names the owner and configuration.
Finished disposable task	Create a checkpoint	A snapshot handle is recorded with its source/input identity.
Restored checkpoint	Alter a harmless output file, then checkpoint again	The second checkpoint is a new handle; the first remains the old state.
Unauthorized viewer	Request a preview hostname	Worker-side authentication rejects it.
Migration rehearsal	Run only the intended 1.0 class in isolation with disposable, non-production state	The target state and stop/abandon criteria are documented before the irreversible move.

This fixture deliberately avoids claiming that a container is a complete security boundary, that a preview is safe, or that a snapshot includes/excludes any undocumented file class. Read the current product documentation and account terms before implementation. Exercise the exact image, outbound hosts, storage mount, preview authentication, command policy, retention period, and deletion path that the real service will use.

What to measure after implementation

The first production question is not “did the agent finish?” Record whether the requested task was authorized, which execution state was used, whether a snapshot was new or restored, which network policy applied, and whether the final output passed its own validation. Measure start/recovery failures and stale checkpoint rejection separately from model or build success. Test a restore with a different principal, an expired authorization, a changed input digest, and a forbidden preview request.

The September 30 documents are release signals from Cloudflare, not independent security evaluations or performance measurements. They provide concrete vocabulary for a better execution contract: owner, image, instance, network policy, snapshot, restore, retention, stop, and migration. The application still has to authorize and observe each transition, treating the policy-class migration as irreversible.