`Vpod` Python SDK

A lightweight, portable sandbox that gives an untrusted process an instant Linux environment.

Documentation • Issues

It uses a RISC‑V architecture and runs entirely inside WebAssembly.

Fast startup : Boot in under a second.
Portable : Runs anywhere without any setup required.
Isolated : All execution state stays inside the WASM sandbox.

Installation

pip install vpod

Usage

Persistent session (Recommended)

All calls share the same running sandbox. Using a context manager (with) automatically cleans up resources when done:

from vpod import Sandbox

with Sandbox.create() as sbx:
    sbx.commands.run("export FOO=bar")
    sbx.commands.run("touch /tmp/data.csv")

    result = sbx.commands.run("echo $FOO")
    print(result.stdout)  # bar

Python REPL

Run Python code with persistent state across calls. Variables and imports persist for the lifetime of the session.

from vpod import Sandbox

with Sandbox.create() as sbx:
    sbx.code.run("import requests")
    sbx.code.run("data = [1, 2, 3]")
    result = sbx.code.run("print(sum(data))")
    print(result.text)  # 6

Advanced Configuration

You can mount local directories into the sandbox, set environment variables, and specify which snapshot to use.

from vpod import Sandbox

# Mount a local workspace and use a snapshot with pre-installed data science tools
mounts = {"workspace": "/workspace:rw"}

with Sandbox.create(snapshot="vsnap-data", mounts=mounts) as sbx:
    sbx.code.run("import pandas as pd")
    sbx.code.run("print('Pandas is ready!')")

Environment variables are set at creation and reach both commands and code.run:

with Sandbox.create(env={"TZ": "UTC"}) as sbx:
    sbx.commands.run("date")

Suspend & Resume

Pause a running sandbox and resume it later — no daemon, no background process. Only dirty memory pages are saved, making it fast and storage-efficient.

from vpod import Sandbox

with Sandbox.create() as sbx:
    sbx.commands.run("uv pip install --system requests")
    instance_id = sbx.suspend()

# Later (even from a new process):
sbx = Sandbox.resume(instance_id)
sbx.code.run("import requests; print(requests.__version__)")

Method	Description
`sandbox.suspend()`	Suspend to disk, returns instance ID
`Sandbox.resume(id)`	Resume a suspended instance
`Sandbox.list_instances()`	List all instances
`Sandbox.destroy(id)`	Delete a suspended instance from disk

Shell commands (stateless)

If you just need a quick one-off execution without preserving state:

from vpod import Sandbox

sbx = Sandbox.create()
result = sbx.commands.run("echo hello")
print(result.stdout)    # hello
sbx.close()             # Clean up the sandbox process

Snapshots

The first call to Sandbox.create() downloads the snapshot and caches it locally. Subsequent calls use the cache instantly.

To pre-download (e.g. in a Dockerfile or CI setup):

from vpod import snapshots

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

snapshots.pull("alpine:latest")

Available Snapshots

Name	Tag	Description	Memory Limit (RAM)
`alpine`	3.23.0	Minimal Alpine Linux snapshot.	256 MB
`vsnap-base`	0.1.0	Alpine-based general-purpose snapshot with Python.	256 MB
`vsnap-base-512mb`	0.1.0	Same as `vsnap-base` with more memory headroom, for web servers and larger installs.	512 MB
`vsnap-data`	0.1.0	Alpine-based snapshot with `numpy`, `pandas`, and `scipy`.	512 MB

Documentation

Visit the Vpod documentation for the full guide and API reference. To report issues or contribute, head to the main GitHub repository.

Metadata

Release files for vpod 0.8.5rc1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for vpod 0.8.5rc1
File	Size	Uploaded
vpod-0.8.5rc1.tar.gz	6.2 MB	Sep 21, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for vpod 0.8.5rc1
File	Interpreter	ABI	Platform	Reset
vpod-0.8.5rc1-py3-none-any.whl 6.3 MB Sep 21, 2026	Python 3	none	any	Details

Total release size: 12.5 MB

Release files / vpod-0.8.5rc1.tar.gz

Download URL	vpod-0.8.5rc1.tar.gz
Size	6.2 MB
Tags	Source
SHA-256 checksum How to use checksums	`c704981e672df005a899b7104a1c620c405954db719300724e8e0072bde89f76`
BLAKE2b-256 checksum How to use checksums	`46f26d6e10dfedcdd54a2e54a6d1587e3fddb6cd39ed4ad2d3cae309a1b593e4`
Upload date	Sep 21, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.10.21`

Release files / vpod-0.8.5rc1-py3-none-any.whl

Download URL	vpod-0.8.5rc1-py3-none-any.whl
Size	6.3 MB
Tags	Python 3
SHA-256 checksum How to use checksums	`d22603ade524289b16536fd80f951b6c38335fcce9601e7c24f5a5e62a8c4b64`
BLAKE2b-256 checksum How to use checksums	`fed66e6da7549d16b3e5587a21fe4aea4540acd5fd29c91f5f463699f61fada1`
Upload date	Sep 21, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.10.21`