> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vpod.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Suspend & resume

> Pause a sandbox and pick it up later, in another tab or another process.

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.

## 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.

```ts theme={null}
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:

```ts theme={null}
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                             |

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

<Note>
  `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.
</Note>

<Warning>
  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.
</Warning>