capsulerun/vpodSandbox Linux leggere e sicure per processi non attendibili. Funzionano nel browser e sul server.
Vpod 
vpod ?Un vpod è una sandbox leggera e portabile che offre a un processo non fidato un ambiente Linux immediato. Utilizza un'architettura RISC‑V e gira interamente all'interno di WebAssembly.
Un vpod esegue un sistema RISC‑V completo (RV64GC, singola vCPU) compilato in WebAssembly. Al suo interno avvia un vero kernel Linux con un vero userspace, quindi shell, strumenti e demoni si comportano come farebbero su hardware reale.
Snapshot. Invece di avviare Linux da zero, un vpod ripristina uno snapshot: uno stato della macchina salvato (registri CPU, RAM, filesystem) catturato subito dopo l'avvio. Ripristinarne uno richiede meno di un secondo. La sospensione funziona allo stesso modo al contrario: solo le pagine di memoria sporche vengono riscritte su disco, così puoi mettere in pausa una sandbox e riprenderla in seguito, anche da un altro processo.
Traduzione ahead-of-time. La pura emulazione istruzione-per-istruzione è lenta e WebAssembly esclude un JIT a runtime. Quindi, al momento della creazione dello snapshot, i percorsi di codice guest più caldi vengono tradotti da RISC‑V in codice nativo che viene compilato nel modulo WASM stesso. A runtime l'emulatore esegue il dispatch in questi blocchi tradotti quando il codice guest corrisponde e ripiega sull'interprete quando non corrisponde. Questo vale circa 5x sul lavoro CPU-bound, con zero effetti sull'isolamento: il codice tradotto passa attraverso gli stessi controlli MMU e di memoria del codice interpretato.
Il confine WASI. Il componente WASM comunica con l'host esclusivamente tramite WASI 0.2. Il guest non vede mai descrittori di file, socket o memoria dell'host: l'accesso al filesystem passa attraverso directory montate esplicitamente e la rete passa attraverso uno stack di rete user-mode all'interno del componente che chiede all'host solo socket outbound semplici. Tutto il resto (kernel guest, processi, memoria) vive nella memoria lineare WASM e muore con essa.
G (Estensioni per scopi generali)
C (Istruzioni compresse) Riduce la dimensione del codice del 30%, migliorando la velocità di fetch delle istruzioni e l'efficienza della memoria. Questo è importante quando si esegue un userspace Linux completo nel nostro ambiente WASM con memoria limitata.
[!NOTE] L'estensione V (vettoriale) non è implementata. Le istruzioni RVV verrebbero eseguite come RISC-V emulato; non c'è pass-through SIMD alla CPU host. Aggiungere V aumenterebbe l'overhead di emulazione senza alcun beneficio prestazionale per i carichi di lavoro vettorializzati.
npm install @capsule-run/vpod
import { Sandbox } from "@capsule-run/vpod";
const sandbox = await Sandbox.create();
// Lo stato è preservato tra le chiamate
await sandbox.commands.run("export API_KEY=secret");
const key = await sandbox.commands.run("echo $API_KEY");
console.log(key.stdout); // secret
// REPL Python — le variabili persistono
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();
Lo stesso pacchetto funziona in una scheda del browser, dove lo snapshot viene memorizzato nella cache di storage origin-private invece che su disco.
[!IMPORTANT] La prima chiamata a
Sandbox.create()scarica lo snapshot predefinito (alpine) e lo memorizza nella cache locale se non è già presente.
pip install vpod
from vpod import Sandbox
# Esegui un comando
sandbox = Sandbox.create()
result = sandbox.commands.run("whoami")
print(result.stdout) # root
sandbox.close()
# Sessione persistente — stato preservato tra le chiamate
with Sandbox.create() as sandbox:
sandbox.commands.run("export API_KEY=secret")
result = sandbox.commands.run("echo $API_KEY")
print(result.stdout) # secret
# REPL Python — le variabili persistono
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
curl -fsSL https://install.vpod.sh | sh
Oppure installa tramite PowerShell (Windows)
irm https://install.vpod.sh | iex
# Scarica uno snapshot
vpod pull alpine:latest
# Avvia una shell interattiva
vpod
Visita la documentazione di Vpod.
I contributi sono benvenuti, dai report di bug al supporto di nuovi dispositivi. Apri un issue per discutere qualsiasi cosa sostanziale prima di realizzarla.
wasm32-wasip2: rustup target add wasm32-wasip2# Una tantum: genera lo stub AOT (un clone fresco non ha blocchi tradotti)
./scripts/aot-stub.sh
# Compila il componente WASM (libreria + CLI). Copia entrambi i livelli in sdks/python/vpod/
./scripts/build-wasm.sh
# Installa la CLI host
cargo install --path crates/vpod
# Installa l'SDK Python in modalità dev
pip install -e "sdks/python[dev]"
# Compila l'SDK TypeScript. Preleva il componente dalla directory dell'SDK Python
cd sdks/typescript && npm install && npm run build
npm run build usa come predefinito --tier aot; CI fissa --tier base. La build
rifiuta un componente più vecchio del file più recente sotto crates/, quindi riesegui
./scripts/build-wasm.sh dopo aver toccato l'emulatore. Una modifica all'emulatore si
manifesta solo attraverso il guest, quindi un componente obsoleto compila e supera quasi
tutto.
CI esegue questi test su ogni PR, quindi eseguili prima di fare push:
cargo fmt --all -- --check # formattazione
cargo clippy --all-targets --all-features -- -D warnings
cargo test --all # test Rust
# Test di integrazione SDK Python (richiede la libreria WASM in posizione)
cp target/wasm32-wasip2/release/vpod_wasi_lib.wasm sdks/python/vpod/
pytest sdks/python/tests/ -v -m integration
# SDK TypeScript (da sdks/typescript)
npm run typecheck
npm test # unità
npm run test:all # unità + integrazione, richiede uno snapshot locale
npm run test:perf # regressioni del tempo guest, costanti esatte
I test TypeScript importano la dist/ compilata, non src/, quindi compila prima di
eseguirli. Cercano uno snapshot nella directory cache condivisa;
VPOD_TEST_SNAPSHOT=/path/to/x.snap li indirizza altrove.
Per esercitare il browser end-to-end, npm run dev serve la pagina con COOP/COEP
attivi e node dev/run-network.mjs --browser chrome la guida in modalità headless.
Gli SDK scaricano da registry.vpod.sh per impostazione predefinita. Per eseguirne uno compilato da te,
passalo direttamente invece di un nome di registry:
// TypeScript: un file su disco (Node), o byte (ovunque)
await Sandbox.create({ snapshot: { path: "./dist/alpine-3.23.0-256mb.snap" } });
await Sandbox.create({ snapshot: { bytes, name: "alpine-3.23.0-256mb.snap" } });
# Python: VPOD_SNAPSHOT=/path/to/x.snap
Mantieni la dimensione della RAM nel nome del file in ogni caso, perché l'emulatore la legge da lì.
Il progetto usa snapshot Alpine precompilati da registry.vpod.sh, quindi normalmente non ne hai bisogno. Per crearne uno localmente:
./scripts/build-default-snapshot.sh # dist/alpine-3.23.0-256mb.snap
./scripts/build-data-snapshot.sh # variante da 512 MB con numpy/pandas/scipy
[!TIP] Per usare uno snapshot compilato localmente nella CLI, decommenta le righe in
resolve_snapshot()incrates/vpod/src/main.rs.
Le build di snapshot possono anche eseguire il passaggio AOT (scripts/aot-snapshot.sh <snapshot>), che traccia un carico di lavoro rappresentativo, traduce i blocchi caldi e ricompila l'emulatore con essi incorporati. Richiede tempo; lo stub di aot-stub.sh è sufficiente per lo sviluppo quotidiano, tutto funziona allo stesso modo, solo più lentamente.
Gli snapshot personalizzati possono anche essere creati da un Dockerfile. Il builder usa
il CLI container di Apple su macOS e
Docker Buildx su Linux. Una nuova installazione macOS richiede la configurazione del runtime una volta,
altrimenti la build attende un builder che non si avvia mai:
container system kernel set --recommended
container builder start
Su Linux, installa Docker con il plugin Buildx e registra l'emulazione riscv64 una volta se l'host non è già configurato per build cross-platform:
docker run --privileged --rm tonistiigi/binfmt --install riscv64
./scripts/build-custom-snapshot.sh -f Dockerfile -n my-image # dist/my-image-256mb.snap
# opzionalmente: --aot --trace-cmd '<il comando caldo dell'immagine>' per incorporare i blocchi AOT
Il Dockerfile viene compilato per linux/riscv64 (BuildKit esegue i passaggi RUN
sotto emulazione), il suo rootfs appiattito sostituisce il minirootfs Alpine,
e il resto della pipeline è identico: overlay vpod, avvio,
--snapshot-save.
Solo il filesystem sopravvive all'esportazione. ENV, CMD e ENTRYPOINT dalla
configurazione dell'immagine vengono scartati, quindi persisti l'ambiente tramite /etc/profile.d/ in
un passaggio RUN. Il warm-start Python viene applicato automaticamente per le immagini basate su musl
che includono python3 in /usr/bin o /bin.
fmt, clippy e la suite di test devono passare (CI impone tutti e tre).Questo progetto è concesso in licenza sotto la Apache License 2.0. Consulta il file LICENSE per i dettagli.