Vpod Python SDK
A lightweight, portable sandbox that gives an untrusted process an instant Linux environment.
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 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!')")
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.
1 maintainer
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file vpod-0.6.1.tar.gz.
File metadata
- Download URL: vpod-0.6.1.tar.gz
- Upload date:
- Size: 6.0 MB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via:
twine/7.0.0 CPython/3.10.20
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
a8c383839bb023f51699ea88350603394cd80c702656969a8544fe3db5f63d2b
|
|
| MD5 |
94c28ace454f0c1c58aa157b6577c0b7
|
|
| BLAKE2b-256 |
e5e62ffb7732dd07ceda6382e4653fbfc79e0c6c493200d1a49097aa22e7f3c5
|
File details
Details for the file vpod-0.6.1-py3-none-any.whl.
File metadata
- Download URL: vpod-0.6.1-py3-none-any.whl
- Upload date:
- Size: 6.0 MB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via:
twine/7.0.0 CPython/3.10.20
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
f6d08b4844cf74be16dd9b8d5d94064ef5abe249a9e57d91ce96af33a3a983eb
|
|
| MD5 |
2659f9ed92978abd351ce25114ab41b3
|
|
| BLAKE2b-256 |
2bc6bb5bc5d841a9576ea0a8fabfdc93f13e808c5e94c03fde876044fa6155b1
|
