Vpod

Primeros pasos • Documentación • Problemas • Contribuciones

¿Qué es un vpod?

Un vpod es un sandbox ligero y portátil que proporciona a un proceso no confiable un entorno Linux instantáneo. Utiliza una arquitectura RISC‑V y se ejecuta enteramente dentro de WebAssembly.

• Inicio rápido : Arranca en menos de un segundo.
• Portátil : Se ejecuta en cualquier lugar sin necesidad de configuración.
• Aislado : Todo el estado de ejecución permanece dentro de los sandboxes WASM.

Cómo funciona

Un vpod ejecuta un sistema RISC‑V completo (RV64GC, una sola vCPU) compilado a WebAssembly. En su interior arranca un kernel Linux real con un userspace real, de modo que shells, herramientas y demonios se comportan como lo harían en hardware real.

Instantáneas. En lugar de arrancar Linux desde cero, un vpod restaura una instantánea (snapshot): un estado de máquina guardado (registros de CPU, RAM, sistema de archivos) capturado justo después del arranque. Restaurar una toma mucho menos de un segundo. La suspensión funciona de la misma manera en sentido inverso: solo las páginas de memoria sucias se escriben de vuelta al disco, por lo que puedes pausar un sandbox y reanudarlo más tarde, incluso desde otro proceso.

Traducción anticipada (AOT). La emulación pura instrucción por instrucción es lenta, y WebAssembly descarta un JIT en tiempo de ejecución. Así que, al construir la instantánea, las rutas de código invitado más calientes se traducen de RISC‑V a código nativo que se compila dentro del propio módulo WASM. En tiempo de ejecución, el emulador despacha a estos bloques traducidos cuando el código invitado coincide, y recurre al intérprete cuando no coincide. Esto supone aproximadamente 5 veces más velocidad en trabajo limitado por CPU, sin ningún efecto sobre el aislamiento: el código traducido pasa por los mismos chequeos de MMU y memoria que el código interpretado.

El límite de WASI. El componente WASM se comunica con el host exclusivamente a través de WASI 0.2. El invitado nunca ve descriptores de archivo, sockets o memoria del host: el acceso al sistema de archivos pasa por directorios montados explícitamente, y la red pasa por una pila de red en modo usuario dentro del componente que solo pide al host sockets de salida simples. Todo lo demás (kernel invitado, procesos, memoria) vive dentro de la memoria lineal de WASM y muere con ella.

Especificación RV64GC

G (extensiones de propósito general)

• I : Conjunto de instrucciones enteras de 64 bits base.
• M : Multiplicación y división por hardware, útil para hash y criptografía.
• A : Operaciones atómicas para programas seguros frente a hilos.
• F/D : Punto flotante de precisión simple y doble, adecuado para computación científica e inferencia de ML.

C (instrucciones comprimidas) Reduce el tamaño del código en un 30 %, mejorando la velocidad de búsqueda de instrucciones y la eficiencia de memoria. Esto importa al ejecutar un userspace Linux completo dentro de nuestro entorno WASM con memoria limitada.

[!NOTE] La extensión V (vectorial) no está implementada. Las instrucciones RVV se ejecutarían como RISC-V emulado; no hay paso SIMD a la CPU del host. Añadir V aumentaría la sobrecarga de emulación sin ningún beneficio de rendimiento para cargas de trabajo vectorizadas.

Primeros pasos

SDK de 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 primera llamada a Sandbox.create() descarga la instantánea predeterminada (alpine) y la guarda en caché localmente si aún no está presente.

CLI

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

O instala mediante PowerShell (Windows)

root@kitploit:~

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

# Pull a snapshot
vpod pull alpine:latest

# Start an interactive shell
vpod

Documentación

Visita la documentación de Vpod.

Limitaciones

• Sobrecarga de emulación: No hay virtualización por hardware dentro de WebAssembly, por lo que todo el código invitado es emulado. La sobrecarga depende completamente de la carga de trabajo: el trabajo limitado por E/S y por red se ejecuta cerca de la velocidad nativa, mientras que el trabajo intensivo de CPU se ejecuta notablemente más lento incluso con traducción AOT. Si tu carga de trabajo consiste principalmente en "ejecutar una herramienta, leer un archivo, llamar a una API", no lo notarás.
• Sin acceso a GPU: CUDA, Metal y los aceleradores ML por hardware no están disponibles. El soporte podría añadirse en el futuro con wasi-nn.

Contribuciones

Las contribuciones son bienvenidas, desde informes de errores hasta soporte para nuevos dispositivos. Abre un issue para discutir cualquier cosa sustancial antes de construirla.

Requisitos previos

• Rust (última versión estable) con el objetivo wasm32-wasip2: rustup target add wasm32-wasip2
• Python 3.10+ para el SDK
• Zig (0.16) y bsdtar, solo necesarios si compilas instantáneas tú mismo

Configuración de desarrollo

# 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]"

Ejecutar pruebas

CI ejecuta estas en cada PR, así que ejecútalas antes de hacer 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

Compilar instantáneas

El proyecto utiliza instantáneas Alpine precompiladas desde registry.vpod.sh, por lo que normalmente no necesitas esto. Para compilar una 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] Para usar una instantánea compilada localmente, descomenta las líneas en resolve_snapshot() en crates/vpod/src/main.rs.

Las compilaciones de instantáneas también pueden ejecutar el pase AOT (scripts/aot-snapshot.sh <snapshot>), que traza una carga de trabajo representativa, traduce los bloques calientes y reconstruye el emulador con ellos integrados. Tarda un tiempo; el stub de aot-stub.sh es suficiente para el desarrollo diario, todo funciona igual, solo más lento.

Pull requests

• Mantén los PR enfocados: un cambio por PR.
• fmt, clippy y la suite de pruebas deben pasar (CI lo exige para los tres).
• Si tocas las rutas de ejecución o memoria del emulador, explica cómo validaste la corrección (como mínimo la suite de pruebas; para cambios sutiles, un arranque más una carga de trabajo real en el invitado es una buena comprobación de cordura).

Licencia

Este proyecto está licenciado bajo la Apache License 2.0. Consulta el archivo LICENSE para más detalles.