Vpod

Was ist ein vpod?

Ein vpod ist eine leichtgewichtige, portable Sandbox, die einem nicht vertrauenswürdigen Prozess eine sofortige Linux-Umgebung bietet. Sie verwendet eine RISC‑V-Architektur und läuft vollständig in WebAssembly.

• Schneller Start: Bootet in unter einer Sekunde.
• Portabel: Läuft überall ohne jegliche Einrichtung.
• Isoliert: Der gesamte Ausführungszustand bleibt in den WASM-Sandboxes.

So funktioniert es

Ein vpod führt ein vollständiges RISC‑V-System (RV64GC, einzelne vCPU) aus, das zu WebAssembly kompiliert wurde. Darin bootet ein echtes Linux-Kernel mit einem echten Userspace, sodass sich Shells, Tools und Daemons genau so verhalten wie auf echter Hardware.

Snapshots. Statt Linux von Grund auf zu booten, stellt ein vpod einen Snapshot wieder her: einen gespeicherten Maschinenzustand (CPU-Register, RAM, Dateisystem), der direkt nach dem Boot erfasst wurde. Die Wiederherstellung dauert deutlich unter einer Sekunde. Suspend funktioniert auf die gleiche Weise in umgekehrter Richtung – nur schmutzige Speicherseiten werden zurück auf die Festplatte geschrieben, sodass Sie eine Sandbox pausieren und später fortsetzen können, sogar aus einem anderen Prozess.

Ahead-of-time-Übersetzung. Reine Befehls-für-Befehls-Emulation ist langsam, und WebAssembly schließt einen Laufzeit-JIT aus. Daher werden beim Erstellen des Snapshots die heißesten Gast-Codepfade von RISC‑V in nativen Code übersetzt, der direkt in das WASM-Modul kompiliert wird. Zur Laufzeit leitet der Emulator in diese übersetzten Blöcke um, wenn der Gastcode übereinstimmt, und fällt auf den Interpreter zurück, wenn dies nicht der Fall ist. Das bringt etwa 5x bei CPU-gebundener Arbeit, ohne Auswirkungen auf die Isolation: Übersetzter Code durchläuft dieselben MMU- und Speicherprüfungen wie interpretierter Code.

Die WASI-Grenze. Die WASM-Komponente kommuniziert mit dem Host ausschließlich über WASI 0.2. Der Gast sieht niemals Host-Dateideskriptoren, Sockets oder Speicher: Dateisystemzugriff erfolgt über explizit gemountete Verzeichnisse, und Netzwerkzugriff läuft über einen User-Mode-Netzwerkstack innerhalb der Komponente, der den Host nur um einfache ausgehende Sockets bittet. Alles andere (Gast-Kernel, Prozesse, Speicher) lebt im linearen WASM-Speicher und stirbt mit ihm.

RV64GC-Spezifikation

G (Allzweck-Erweiterungen)

• I: Basis-Befehlssatz für 64-Bit-Ganzzahlen.
• M: Hardware-Multiplikation und -Division, nützlich für Hashing und Kryptografie.
• A: Atomare Operationen für threadsichere Programme.
• F/D: Gleitkommazahlen mit einfacher und doppelter Genauigkeit, geeignet für wissenschaftliches Rechnen und ML-Inferenz.

C (Komprimierte Befehle) Reduziert die Codegröße um 30 %, verbessert die Befehlsabrufgeschwindigkeit und die Speichereffizienz. Das ist wichtig, wenn ein vollständiger Linux-Userspace in unserer speicherbeschränkten WASM-Umgebung läuft.

[!NOTE] Die V-Erweiterung (Vektor) ist nicht implementiert. RVV-Befehle würden als emuliertes RISC-V ausgeführt; es gibt kein SIMD-Passthrough zur Host-CPU. Das Hinzufügen von V würde den Emulationsaufwand erhöhen, ohne einen Leistungsvorteil für vektorisierte Workloads zu bringen.

Erste Schritte

TypeScript-SDK

npm install @capsule-run/vpod

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

const sandbox = await Sandbox.create();

// Der Zustand bleibt über Aufrufe hinweg erhalten
await sandbox.commands.run("export API_KEY=secret");
const key = await sandbox.commands.run("echo $API_KEY");
console.log(key.stdout); // secret

// Python-REPL — Variablen bleiben erhalten
await sandbox.code.run("data = [1, 2, 3]");
const total = await sandbox.code.run("print(sum(data))");
console.log(total.text); // 6

await sandbox.close();

Dasselbe Paket läuft in einem Browser-Tab, wo der Snapshot im origin-privaten Speicher statt auf der Festplatte zwischengespeichert wird.

[!IMPORTANT] Der erste Aufruf von Sandbox.create() lädt den Standard-Snapshot (alpine) herunter und speichert ihn lokal zwischen, falls er nicht bereits vorhanden ist.

Python-SDK

pip install vpod

from vpod import Sandbox

# Einen Befehl ausführen
sandbox = Sandbox.create()
result = sandbox.commands.run("whoami")
print(result.stdout)  # root
sandbox.close()

# Persistente Sitzung — Zustand bleibt über Aufrufe hinweg erhalten
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 — Variablen bleiben erhalten
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

CLI

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

Oder per PowerShell installieren (Windows)

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

# Einen Snapshot ziehen
vpod pull alpine:latest

# Eine interaktive Shell starten
vpod

Dokumentation

Besuchen Sie die Vpod-Dokumentation.

Einschränkungen

• Emulationsaufwand: Es gibt keine Hardware-Virtualisierung in WebAssembly, daher wird der gesamte Gastcode emuliert. Der Aufwand hängt vollständig vom Workload ab: I/O-gebundene und netzwerkgebundene Arbeit läuft nahezu in nativer Geschwindigkeit, während stark CPU-gebundene Arbeit auch mit AOT-Übersetzung spürbar langsamer läuft. Wenn Ihr Workload hauptsächlich aus „Tool ausführen, Datei lesen, API aufrufen“ besteht, werden Sie es nicht bemerken.
• Kein GPU-Zugriff: CUDA, Metal und Hardware-ML-Beschleuniger sind nicht verfügbar. Unterstützung könnte in Zukunft mit wasi-nn hinzugefügt werden.

Mitwirken

Beiträge sind willkommen, von Fehlerberichten bis zur Unterstützung neuer Geräte. Öffnen Sie ein Issue, um alles Wesentliche zu besprechen, bevor Sie es bauen.

Voraussetzungen

• Rust (aktuelles Stable) mit dem wasm32-wasip2-Target: rustup target add wasm32-wasip2
• Python 3.10+ für das Python-SDK
• Node 20+ für das TypeScript-SDK
• Zig (0.16) und bsdtar, nur benötigt, wenn Sie Snapshots selbst bauen

Entwicklungseinrichtung

# Einmalig: AOT-Stub generieren (ein frischer Klon hat keine übersetzten Blöcke)
./scripts/aot-stub.sh

# Die WASM-Komponente bauen (Bibliothek + CLI). Kopiert beide Stufen in sdks/python/vpod/
./scripts/build-wasm.sh

# Die Host-CLI installieren
cargo install --path crates/vpod

# Das Python-SDK im Entwicklermodus installieren
pip install -e "sdks/python[dev]"

# Das TypeScript-SDK bauen. Übernimmt die Komponente aus dem Python-SDK-Verzeichnis
cd sdks/typescript && npm install && npm run build