Suspend & resume

A running sandbox can be suspended and reconstructed on demand. Nothing keeps running in between, so there is no daemon and no background process to manage. Only the memory pages that changed since boot are written, which keeps a delta at a couple of megabytes rather than the size of the snapshot. Anything the guest held carries across, including variables set with env at creation. Pass env to Sandbox.resume only when you want to add or change one on the way back up.

The delta is bytes, not a location

This is the one place the TypeScript SDK deliberately differs from the Python one. A browser tab has nowhere to put a file, so suspend() hands you the state and lets you decide where it goes. For a hosted app that is usually your own backend.

const sandbox = await Sandbox.create();
await sandbox.commands.run("uv pip install --system requests");

const delta = await sandbox.suspend(); // Uint8Array, a couple of MiB
await sandbox.close();

// Later, possibly in another tab or another process:
const resumed = await Sandbox.resume({
    id: "my-instance",
    snapshotId: sandbox.snapshotId,
    delta,
});

const result = await resumed.code.run("import requests; print(requests.__version__)");
console.log(result.text);

Letting the browser hold it

In a browser you can skip the round trip and keep the delta in origin-private storage:

const instanceId = await sandbox.suspendToOpfs();

// After a page reload:
const resumed = await Sandbox.resume(instanceId);

This is what makes an export MARKER=1, a refresh, and an echo $MARKER that still answers work in a single tab.

Managing instances

Method	Description
`sandbox.suspend()`	Suspend and return the delta bytes
`sandbox.suspendToOpfs()`	Suspend into browser storage, returns an instance id
`Sandbox.resume(idOrInstance, options?)`	Resume from an id or from delta bytes
`Sandbox.listInstances()`	List instances held in browser storage
`Sandbox.destroy(id)`	Delete a stored instance

for (const instance of await Sandbox.listInstances()) {
    console.log(instance.id, instance.snapshotId, new Date(instance.savedAt));
}

sandbox.close() shuts down a running sandbox and leaves suspended instances alone. Use Sandbox.destroy(id) to remove one, or snapshots.clear({ instances: true }) to drop them all.

A delta only resumes against the snapshot it was taken from. snapshotId is recorded for exactly that reason, so keep it with the bytes if you store them yourself.

Get Started

TypeScript SDK

Python SDK

Embedded preview (In Iframe)

CLI

Resources

Suspend & resume

The delta is bytes, not a location

Letting the browser hold it

Managing instances

​The delta is bytes, not a location

​Letting the browser hold it

​Managing instances

The delta is bytes, not a location

Letting the browser hold it

Managing instances