Vpod

¿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 completamente 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. Dentro arranca un kernel Linux real con un userspace real, por lo 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: 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. Por eso, al compilar 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 5x en trabajo con uso intensivo de CPU, sin ningún efecto sobre el aislamiento: el código traducido pasa por las mismas comprobaciones de MMU y memoria que el código interpretado.

El límite 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 solicita al host sockets de salida simples. Todo lo demás (kernel invitado, procesos, memoria) vive dentro de la memoria lineal WASM y muere con ella.

Especificación RV64GC

G (Extensiones de propósito general)

• I: Conjunto de instrucciones enteras base de 64 bits.
• M: Multiplicación y división por hardware, útil para hash y criptografía.
• A: Operaciones atómicas para programas seguros con 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 captura de instrucciones y la eficiencia de memoria. Esto importa al ejecutar un userspace Linux completo dentro de nuestro entorno WASM con restricciones de memoria.

[!NOTE] La extensión V (vectorial) no está implementada. Las instrucciones RVV se ejecutarían como RISC-V emulado; no hay paso directo de 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 TypeScript

npm install @capsule-run/vpod

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

const sandbox = await Sandbox.create();

// El estado se conserva entre llamadas
await sandbox.commands.run("export API_KEY=secret");
const key = await sandbox.commands.run("echo $API_KEY");
console.log(key.stdout); // secret

// REPL de Python — las variables persisten
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();

El mismo paquete se ejecuta en una pestaña del navegador, donde la instantánea se almacena en caché en almacenamiento privado de origen en lugar de en disco.

[!IMPORTANT] La primera llamada a Sandbox.create() descarga la instantánea predeterminada (alpine) y la almacena en caché localmente si aún no está presente.

SDK de Python

pip install vpod

from vpod import Sandbox

# Ejecutar un comando
sandbox = Sandbox.create()
result = sandbox.commands.run("whoami")
print(result.stdout)  # root
sandbox.close()

# Sesión persistente — el estado se conserva entre llamadas
with Sandbox.create() as sandbox:
    sandbox.commands.run("export API_KEY=secret")
    result = sandbox.commands.run("echo $API_KEY")
    print(result.stdout)  # secret

# REPL de Python — las variables persisten
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

O instalar mediante PowerShell (Windows)

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

# Descargar una instantánea
vpod pull alpine:latest

# Iniciar un shell interactivo
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 se emula. 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 pesado limitado por 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 aceleradores de hardware ML no están disponibles. El soporte podría añadirse en el futuro con wasi-nn.

Contribuir

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 target wasm32-wasip2: rustup target add wasm32-wasip2
• Python 3.10+ para el SDK de Python
• Node 20+ para el SDK de TypeScript
• Zig (0.16) y bsdtar, solo necesarios si compilas instantáneas tú mismo

Configuración de desarrollo

# Una sola vez: generar el stub AOT (un clon nuevo no tiene bloques traducidos)
./scripts/aot-stub.sh

# Compilar el componente WASM (biblioteca + CLI). Copia ambos niveles en sdks/python/vpod/
./scripts/build-wasm.sh

# Instalar la CLI del host
cargo install --path crates/vpod

# Instalar el SDK de Python en modo desarrollo
pip install -e "sdks/python[dev]"

# Compilar el SDK de TypeScript. Toma el componente del directorio del SDK de Python
cd sdks/typescript && npm install && npm run build