What is a vpod ?

A vpod is 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 sandboxes.

How it works

A vpod runs a RISC‑V virtual machine compiled to WebAssembly, implementing the RV64GC specification. When you start a vpod, it boots from a snapshot, a saved VM state ready in under a second.

The WASM component communicates with the host through WASI 0.2, providing controlled access to filesystem, networking, and standard I/O while keeping all execution state (CPU registers, memory, filesystem) isolated inside the sandbox.

RV64GC Specification

G (General-purpose extensions)

• I : Base 64-bit integer instruction set.
• M : Hardware multiply and divide, useful for hashing and cryptography.
• A : Atomic operations for thread-safe programs.
• F/D : Single and double-precision floating-point, suited for scientific computing and ML inference.

C (Compressed instructions) Reduces code size by 30%, improving instruction fetch speed and memory efficiency. This matters when running a full Linux userspace inside our memory-constrained WASM environment.

Getting started

CLI

curl -fsSL https://install.vpod.sh | sh

Or install via PowerShell (windows)

irm https://install.vpod.sh | iex

Or install via cargo

# Pull a snapshot
vpod pull alpine:latest

# Start an interactive shell
vpod

Python SDK

from vpod import Sandbox

# Run a command
sandbox = Sandbox.create()
result = sandbox.commands.run("whoami")
print(result.stdout)  # root

# Persistent session — state preserved across calls
with Sandbox.create() as sandbox:
    sandbox.commands.run("export API_KEY=secret")
    result = sandbox.commands.run("echo $API_KEY")
    print(result.stdout)  # secret

# Python REPL — variables persist
with Sandbox.create() as sandbox:
    sandbox.code.run("import requests")
    sandbox.code.run("data = [1, 2, 3]")
    result = sandbox.code.run("print(sum(data))")
    print(result.text)  # 6

Documentation

Full reference for the CLI and Python SDK.

CLI commands

Python SDK

Sandbox

Snapshots

Example

from vpod import snapshots

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

path = snapshots.pull("alpine:latest")

Limitations

• Emulation overhead: No hardware acceleration in the WASM component. CPU-intensive workloads may run slower than native.
• No GPU access: CUDA, Metal, and hardware ML accelerators are not yet available. Support may be added in the future with wasi-nn.

Contributing

Prerequisites

• Rust (latest stable)
• Python 3.10+

Development setup

# Build WASM component
./scripts/build-wasm.sh

# Install CLI
cargo install --path crates/vpod

# Install Python SDK in dev mode
pip install -e sdks/python[dev]

# Run tests
cargo test                              # Rust tests
pytest sdks/python/tests/ -v -m integration  # Integration tests (requires WASM build)

Building snapshots

The project uses pre-built Alpine snapshots from registry.vpod.sh. To build a custom snapshot:

./scripts/build-default-snapshot.sh

This creates dist/alpine-3.23.0-256mb.snap.

License

This project is licensed under the Apache License 2.0. See the LICENSE file for details.