vmsan

🔥 Kit de caja de arena microVM Firecracker

Crea, gestiona y conéctate a microVMs Firecracker aisladas desde la línea de comandos. Inicia una VM en caja de arena en milisegundos, ejecuta comandos, transfiere archivos — sin necesidad de SSH.

📚 Lee la documentación completa en vmsan.dev

✨ Características

• ⚡ Arranque en milisegundos — Las microVMs Firecracker arrancan en < 200ms
• 🔒 Aislamiento de seguridad — jailer, seccomp, cgroups y espacios de nombres de red por VM
• 🖥️ Shell interactivo — PTY sobre WebSocket con soporte completo de terminal
• 📂 Transferencia de archivos — subir y descargar sin SSH
• 🐳 Imágenes Docker — construir rootfs desde cualquier imagen OCI con --from-image
• 🏃 Ejecución de comandos — ejecutar comandos con salida en streaming, inyección de entorno y sudo
• 🧩 Múltiples runtimes — base, node22, node24, python3.13
• 📸 Instantáneas de VM — guardar y restaurar el estado de la VM
• 📊 Salida JSON — flag --json para scripting y automatización

📋 Requisitos previos

• Linux (x86_64 o aarch64) con soporte KVM
• Acceso root/sudo (necesario para redes de dispositivo TAP y jailer)
• Docker (para instalaciones desde fuente, reconstrucciones locales de runtimes y --from-image)

🚀 Instalación

curl -fsSL https://vmsan.dev/install | bash

Esto descarga e instala todo en ~/.vmsan/:

• Firecracker + Jailer (última versión)
• Kernel Linux (vmlinux 6.1)
• Rootfs Ubuntu 24.04 (convertido de squashfs a ext4)
• CLI vmsan + agente dentro de la VM
• Imágenes de runtime (node22, node24, python3.13) descargadas como artefactos preconstruidos

Las instalaciones estándar de lanzamiento descargan los runtimes integrados desde https://artifacts.vmsan.dev/ y no requieren Docker. Las instalaciones desde fuente aún construyen runtimes localmente.

curl -fsSL https://vmsan.dev/install | bash -s -- --uninstall

# Instalar dependencias
bun install

# Construir el agente dentro de la VM
cd agent && make install && cd ..

# Construir la CLI
bun run build

# Vincular construcción local
mkdir -p ~/.vmsan/bin
ln -sf "$(pwd)/dist/bin/cli.mjs" ~/.vmsan/bin/vmsan

📖 Uso

# Crear e iniciar una VM
vmsan create --runtime node22 --memory 512 --cpus 2

# Crear una VM desde una imagen Docker
vmsan create --from-image node:22-alpine

# Listar todas las VMs
vmsan list

# Ejecutar un comando dentro de una VM
vmsan exec <vm-id> ls -la

# Ejecución interactiva con PTY
vmsan exec -i <vm-id> bash

# Conectarse al shell de una VM en ejecución
vmsan connect <vm-id>

# Subir un archivo a una VM
vmsan upload <vm-id> ./local-file.txt /remote/path/file.txt

# Descargar un archivo de una VM
vmsan download <vm-id> /remote/path/file.txt ./local-file.txt

# Tomar instantánea de una VM en ejecución
vmsan snapshot create <vm-id>

# Listar instantáneas
vmsan snapshot list

# Restaurar una VM desde una instantánea
vmsan create --snapshot <snapshot-id>

# Detener una VM
vmsan stop <vm-id>

# Eliminar una VM
vmsan remove <vm-id>

Flags globales

Comandos

⚠️ Limitaciones conocidas

• Sin redes entre VMs (planificado para 0.4.0)
• Sin configuración declarativa / vmsan.toml (planificado para 0.5.0)
• Sin soporte multi-host (planificado para 0.7.0)
• Usa nftables con aplicación atómica de reglas para aislamiento de red (desde 0.2.0)
• Sin filtrado DNS o SNI (planificado para 0.3.0)
• ICMP bloqueado por defecto desde las VMs (evita tunelización ICMP)
• UDP bloqueado por defecto excepto DNS (evita filtración UDP; QUIC/HTTP3 no funcionará)
• NTP (UDP 123) bloqueado — se usa kvm-clock para sincronización horaria; las VMs de larga duración pueden derivar
• Es posible que el cortafuegos del host (ufw/firewalld) necesite reglas explícitas de permiso para el tráfico de vmsan
• Solo Linux — requiere soporte KVM
• Plataforma principal: Ubuntu 24.04 LTS

🛠️ Desarrollo

# Construir
bun run build

# Vincular construcción local
ln -sf "$(pwd)/dist/bin/cli.mjs" ~/.vmsan/bin/vmsan

# Modo desarrollo (vigilar)
bun run dev

# Ejecutar pruebas
bun run test

# Verificación de tipos
bun run typecheck

# Lint y formateo
bun run lint
bun run fmt

🏗️ Arquitectura

bin/            Punto de entrada de la CLI
src/
  commands/     Subcomandos de la CLI
  services/     Cliente Firecracker, cliente agente, servicio VM
  lib/          Utilidades (jailer, redes, shell, logging)
  errors/       Sistema de errores tipados
  generated/    Definiciones de tipos de la API de Firecracker
agent/          Agente Go que se ejecuta dentro de la VM
docs/           Sitio de documentación (vmsan.dev)

Cómo funciona

1. vmsan usa Firecracker para crear microVMs ligeras con un jailer para aislamiento de seguridad
2. Cada VM recibe un dispositivo de red TAP con su propia subred /30 (198.19.{slot}.0/30)
3. Un agente basado en Go se ejecuta dentro de la VM, exponiendo una API HTTP para ejecución de comandos, operaciones de archivos y acceso a shell
4. La CLI se comunica con el agente a través de la red host-invitado

El estado se persiste en ~/.vmsan/:

~/.vmsan/
  vms/          Archivos de estado de VM (JSON)
  jailer/       Directorios chroot
  bin/          Binario del agente
  kernels/      Imágenes del kernel de la VM
  rootfs/       Sistemas de archivos raíz base
  registry/     Caché de rootfs de imágenes Docker
  snapshots/    Instantáneas de VM

⚖️ Comparación con otras herramientas