Snapshots

A snapshot is a saved state that a sandbox boots from. The environment is already set up inside it, so booting skips installation entirely.

Available snapshots

Name	Id	Tag	Description	Memory limit (RAM)
`alpine`	`alpine-3.23.0-256mb`	3.23.0	Minimal Alpine Linux snapshot	256 MB
`vsnap-base`	`vsnap-base-256mb`	1.0.0	Alpine-based snapshot with Python pre-installed	256 MB
`vsnap-base`	`vsnap-base-512mb`	1.0.0	Same contents with a larger memory limit	512 MB
`vsnap-data`	`vsnap-data-512mb`	1.0.0	Alpine-based snapshot with `numpy`, `pandas`, and `scipy` pre-installed	512 MB

A name resolves to the first entry carrying it, so vsnap-base gives you the 256 MB one. To pin the other, pass its id. Both columns are accepted anywhere a snapshot is named. vsnap-base:latest is the default. Pass any other:

await using sandbox = await Sandbox.create({ snapshot: "vsnap-base-512mb" });

await using sandbox = await Sandbox.create({ snapshot: "vsnap-data" });

await sandbox.code.run("import pandas as pd");
const result = await sandbox.code.run("print(pd.Series([1, 2, 3]).sum())");
console.log(result.text); // 6

uv is preinstalled in every snapshot, so more Python packages can be added with uv pip install --system <package>. In a browser that reaches PyPI because PyPI sends CORS headers; apk add does not work there, because Alpine’s mirrors do not.

Snapshot API

import { snapshots } from "@capsule-run/vpod";

Method	Description
`snapshots.catalog()`	Fetch the available snapshots
`snapshots.resolve(name)`	Resolve one name to a catalogue entry
`snapshots.cached()`	List what is stored locally, with sizes
`snapshots.clear(options?)`	Delete cached snapshots, returns bytes reclaimed

for (const entry of await snapshots.catalog()) {
    console.log(entry.name, entry.tag);
}

Where the cache lives

The first Sandbox.create() downloads a snapshot and keeps it: on disk in Node, in origin-private storage in a browser. Later runs boot from the copy. Snapshots are stored compressed, so a 256 MB snapshot occupies well under a hundred megabytes. Still enough to be worth showing people.

for (const entry of await snapshots.cached()) {
    console.log(entry.id, entry.byteLength);
}

const reclaimed = await snapshots.clear();

clear() returns the number of bytes it freed and keeps suspended sandboxes, which live alongside the snapshots. Pass { instances: true } to drop those too. The next Sandbox.create() downloads again.

In Node the cache directory is shared with the CLI and the Python SDK. clear() removes only what it downloaded itself and leaves anything it could not fetch again, such as a snapshot you built locally. cached() still lists everything that is there, so the two can disagree, and that is deliberate.

Storage in a browser

Origin-private storage is site data rather than the HTTP cache, so the browser’s “clear cached images and files” does not touch it. A browser is also free to evict it when the disk fills up, which costs a re-download and nothing else.

await snapshots.SnapshotStore.persist();   // ask the browser not to evict
await snapshots.SnapshotStore.persisted(); // whether it agreed
await snapshots.SnapshotStore.quota();     // { usage, quota } or null

Firefox prompts the user when you request persistence, so call it from something they clicked rather than on page load.

Get Started

CLI

TypeScript SDK

Python SDK

Resources

Available snapshots

Snapshot API

Where the cache lives

Storage in a browser

​Available snapshots

​Snapshot API

​Where the cache lives

​Storage in a browser

Available snapshots

Snapshot API

Where the cache lives

Storage in a browser