Vpod

Per iniziare • Documentazione • Issue • Contribuisci

Cos'è un vpod ?

Un vpod è una sandbox leggera e portabile che offre a un processo non affidabile un ambiente Linux immediato. Utilizza un'architettura RISC‑V e gira interamente all'interno di WebAssembly.

• Avvio rapido : Avvio in meno di un secondo.
• Portabile : Funziona ovunque senza alcuna configurazione richiesta.
• Isolato : Tutto lo stato di esecuzione rimane all'interno delle sandbox WASM.

Come funziona

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 daemon si comportano esattamente 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) acquisito 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 un sandbox e riprenderlo 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 all'interno del modulo WASM stesso. A runtime, l'emulatore passa a questi blocchi tradotti quando il codice guest corrisponde e ripiega sull'interprete quando non corrisponde. Questo offre un guadagno di circa 5x sui workload 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 attraverso uno stack di rete in modalità utente all'interno del componente che chiede all'host solo semplici socket in uscita. Tutto il resto (kernel guest, processi, memoria) vive nella memoria lineare WASM e muore con essa.

Specifica RV64GC

G (Estensioni per uso generale)

• I : Set di istruzioni intere a 64 bit di base.
• M : Moltiplicazione e divisione hardware, utili per hashing e crittografia.
• A : Operazioni atomiche per programmi thread-safe.
• F/D : Virgola mobile a precisione singola e doppia, adatta per il calcolo scientifico e l'inferenza ML.

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 all'interno del nostro ambiente WASM con memoria limitata.

[!NOTE] L'estensione V (vettoriale) non è implementata. Le istruzioni RVV verrebbero eseguite come RISC-V emulato; non c'è alcun passthrough SIMD verso la CPU host. Aggiungere V aumenterebbe l'overhead di emulazione senza alcun beneficio prestazionale per i workload vettorializzati.

Per iniziare

SDK Python

pip install vpod

from vpod import Sandbox

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

# 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

[!IMPORTANT] La prima chiamata a Sandbox.create() scarica lo snapshot predefinito (alpine) e lo memorizza nella cache locale se non è già presente.

CLI

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

Oppure installa tramite PowerShell (windows)

root@kitploit:~

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

# Pull a snapshot
vpod pull alpine:latest

# Start an interactive shell
vpod

Documentazione

Visita la documentazione di Vpod.

Limitazioni

• Overhead di emulazione: Non c'è virtualizzazione hardware all'interno di WebAssembly, quindi tutto il codice guest viene emulato. L'overhead dipende interamente dal workload: il lavoro I/O-bound e network-bound gira a velocità vicina a quella nativa, mentre un lavoro pesante CPU-bound gira notevolmente più lento anche con la traduzione AOT. Se il tuo workload consiste principalmente in "esegui uno strumento, leggi un file, chiama un'API", non te ne accorgerai.
• Nessun accesso GPU: CUDA, Metal e acceleratori ML hardware non sono disponibili. Il supporto potrebbe essere aggiunto in futuro con wasi-nn.

Contribuire

I contributi sono benvenuti, dalle segnalazioni di bug al supporto per nuovi dispositivi. Apri una issue per discutere qualsiasi cosa di sostanziale prima di realizzarla.

Prerequisiti

• Rust (ultima versione stabile) con il target wasm32-wasip2: rustup target add wasm32-wasip2
• Python 3.10+ per l'SDK
• Zig (0.16) e bsdtar, necessari solo se compili gli snapshot da solo

Configurazione di sviluppo

# One-time: generate the AOT stub (a fresh clone has no translated blocks)
./scripts/aot-stub.sh

# Build the WASM component (library + CLI)
./scripts/build-wasm.sh

# Install the host CLI
cargo install --path crates/vpod

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

Esecuzione dei test

La CI esegue questi test su ogni PR, quindi eseguili prima di fare push:

cargo fmt --all -- --check                        # formatting
cargo clippy --all-targets --all-features -- -D warnings
cargo test --all                                  # Rust tests

# Python SDK integration tests (needs the WASM library in place)
cp target/wasm32-wasip2/release/vpod_wasi_lib.wasm sdks/python/vpod/
pytest sdks/python/tests/ -v -m integration

Creazione degli snapshot

Il progetto utilizza 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      # 512 MB variant with numpy/pandas/scipy

[!IMPORTANT] Per utilizzare uno snapshot creato localmente, decommenta le righe in resolve_snapshot() in crates/vpod/src/main.rs.

Le build degli snapshot possono anche eseguire il passaggio AOT (scripts/aot-snapshot.sh <snapshot>), che traccia un carico di lavoro rappresentativo, traduce i blocchi caldi e ricostruisce l'emulatore con questi incorporati. Richiede un po' di tempo; lo stub di aot-stub.sh è sufficiente per lo sviluppo quotidiano, tutto funziona allo stesso modo, solo più lentamente.

Pull request

• Mantieni le PR focalizzate: una modifica per PR.
• fmt, clippy e la suite di test devono passare (la CI impone tutti e tre).
• Se tocchi i percorsi di esecuzione o memoria dell'emulatore, spiega come hai validato la correttezza (la suite di test come minimo; per modifiche sottili, un avvio più un carico di lavoro reale nel guest sono un buon controllo di sanità).

Licenza

Questo progetto è concesso in licenza secondo la Apache License 2.0. Vedi il file LICENSE per i dettagli.