Snapshots

A snapshot is a saved state that a sandbox boots from. Because the environment (OS, libraries) is already set up inside the snapshot, booting skips installation entirely. Each snapshot ships with a matching ahead-of-time translation module. If the bundled module doesn’t match the snapshot, the SDK prints a warning — the sandbox still works, but runs at interpreter speed.

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-base`	`vsnap-base-1024mb`	1.0.0	Same contents, the largest a wasm host can restore	1024 MB
`vsnap-data`	`vsnap-data-512mb`	1.0.0	Alpine-based snapshot with `numpy` and `pandas` pre-installed	512 MB

A name resolves to the first entry carrying it, so vsnap-base gives you the 256 MB one. To pin another, pass its id. Both columns are accepted anywhere a snapshot is named, and name:tag works too.

uv comes preinstalled in every snapshot, so additional Python packages can be installed with uv pip install --system <package>. System packages remain available through Alpine’s package manager with apk add <package>.

from vpod import Sandbox

with Sandbox.create(snapshot="vsnap-data") as sandbox:
    sandbox.code.run("import pandas as pd; import numpy as np")
    r = sandbox.code.run("s = pd.Series([1, 2, 3, 4, 5]); print(s.sum(), s.mean())")
    print(r.text)

Pulling ahead of time

Sandbox.create() pulls whatever it needs, so there is usually nothing to do. Pull explicitly when you want the download to happen at a different moment from the run: baking a container image, a CI setup step, or before going offline.

from vpod import snapshots

path = snapshots.pull("vsnap-base-512mb")

It is a no-op when the snapshot is already cached and its digest matches, so it is safe to call on every start. The returned Path is the decompressed snapshot on disk.

Snapshot API

Method	Description	Return type
`snapshots.catalog(registry_url=None, api_key=None)`	Fetch available snapshots	`list[dict]`
`snapshots.pull(name, registry_url=None, api_key=None)`	Pull a snapshot	`Path`

from vpod import snapshots

for snap in snapshots.catalog():
    print(snap["name"], snap["tag"])

snapshots.pull("vsnap-data")

Private snapshots

A snapshot you built in the console is not in the public catalogue. Pass an API key to reach it:

import os

from vpod import Sandbox

with Sandbox.create(
    snapshot="my-snapshot",
    api_key=os.environ["VPOD_API_KEY"],
) as sandbox:
    print(sandbox.commands.run("whoami").stdout)

VPOD_API_KEY is read from the environment when api_key is not passed, so you normally set the variable and leave the argument out:

with Sandbox.create(snapshot="my-snapshot") as sandbox:
    ...

The same argument works on snapshots.pull() and snapshots.catalog().

The private and public catalogues replace each other rather than merging. With a key in play, vsnap-base and the other public snapshots are no longer resolvable by name, so a globally exported VPOD_API_KEY will break a Sandbox.create() that relied on the default snapshot.

Python takes secret keys (vpod_sk_) only. A publishable key (vpod_pk_) is refused: those are guarded by an allowlist of browser origins, and Python is not a browser. See Private snapshots.

Where the cache lives

Downloads land in ~/.local/share/vpod/snapshots on Linux and ~/Library/Application Support/vpod/snapshots on macOS, shared with the CLI and the Node SDK. Files are named by snapshot id and verified against the digest in the catalogue, so a name that resolves differently under another key is re-downloaded rather than reused. Set VPOD_SNAPSHOT to an absolute path to bypass the registry entirely and boot a snapshot you built yourself.

Get Started

TypeScript SDK

Python SDK

Embedded preview (In Iframe)

CLI

Resources

Available snapshots

Pulling ahead of time

Snapshot API

Private snapshots

Where the cache lives

​Available snapshots

​Pulling ahead of time

​Snapshot API

​Private snapshots

​Where the cache lives

Available snapshots

Pulling ahead of time

Snapshot API

Private snapshots

Where the cache lives