angelorc/vmsanFirecracker simplificado. Inicia microVMs seguras en milisegundos, desde la instalación hasta la shell interactiva en un solo comando.
🔥 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.
--from-imagebase, node22, node24, python3.13--json para scripting y automatización--from-image)curl -fsSL https://vmsan.dev/install | bash
Esto descarga e instala todo en ~/.vmsan/:
node22, node24, python3.13) descargadas como artefactos preconstruidosLas 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
Si quieres construir desde la fuente:
# 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
# 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>
| Flag | Descripción |
|---|---|
--json | Salida JSON estructurada |
--verbose | Mostrar salida detallada de depuración |
| Comando | Alias | Descripción |
|---|---|---|
create | Crear e iniciar una nueva microVM | |
list | ls | Listar todas las VMs |
start | Iniciar una VM detenida | |
stop | Detener una VM en ejecución | |
remove | rm | Eliminar una VM |
exec | Ejecutar un comando dentro de una VM en ejecución | |
connect | Abrir un shell interactivo a una VM | |
upload | Subir archivos a una VM | |
download | Descargar archivos de una VM | |
network | Actualizar política de red en una VM en ejecución | |
snapshot | Gestionar instantáneas de VM (crear, listar, eliminar) | |
doctor | Verificar requisitos del sistema y estado de la instalación |
vmsan.toml (planificado para 0.5.0)nftables con aplicación atómica de reglas para aislamiento de red (desde 0.2.0)# 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
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)
/30 (198.19.{slot}.0/30)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
| vmsan | Docker | gVisor | Kata Containers | Vagrant | |
|---|---|---|---|---|---|
| Nivel de aislamiento | ✅ Hardware (KVM) | ❌ Kernel compartido | ⚠️ Kernel en espacio de usuario | ✅ Hardware (QEMU/CH) | ✅ Hardware (VBox/VMware) |
| Tiempo de arranque | ✅ ~125ms | ✅ ~50ms | ✅ ~5ms | ⚠️ ~200ms+ | ❌ 30-60s |
| Complejidad de configuración | ✅ Un comando | ✅ Baja | ⚠️ Media | ❌ Alta | ⚠️ Media |
| Modelo de seguridad | ✅ Jailer + seccomp + cgroups + kernel dedicado | ⚠️ Namespaces + cgroups | ⚠️ Filtrado de syscalls | ✅ VM completa + contenedores anidados | ✅ VM completa |
| Aislamiento de red | ✅ Políticas integradas (permitir/denegar/personalizado) | ❌ Manual (iptables) | ⚠️ Hereda Docker | ❌ Manual | ⚠️ NAT/puente |
| Soporte de imágenes Docker | ✅ --from-image | ✅ Nativo | ✅ A través de runsc | ✅ A través de containerd | ❌ |
| Shell interactivo | ✅ WebSocket PTY | ✅ exec | ✅ exec | ✅ exec | ✅ SSH |
| Transferencia de archivos | ✅ Subir/descargar integrado | ✅ cp | ✅ cp | ✅ cp | ⚠️ Carpetas compartidas / SCP |
| Salida JSON | ✅ Todos los comandos | ⚠️ Parcial | ❌ | ⚠️ Parcial | ❌ |
| Sobrecarga de memoria | ✅ ~5 MiB por VM | ✅ ~1 MiB | ⚠️ ~15 MiB | ❌ ~30 MiB+ | ❌ 512 MiB+ |
| Mejor para | 🏆 Aislamiento de IA, código no confiable, multi-inquilino | Cargas de trabajo generales | Endurecimiento K8s | Cumplimiento K8s | Entornos de desarrollo |
¿Por qué vmsan? Docker comparte el kernel del anfitrión — un escape del contenedor significa fin del juego. gVisor intercepta syscalls en espacio de usuario, reduciendo la superficie de ataque pero sin eliminarla. Kata Containers proporciona aislamiento real de VM pero requiere orquestación compleja (containerd, shimv2, K8s). Vagrant arranca VMs completas que tardan 30+ segundos y cientos de MB.
vmsan te brinda aislamiento a nivel de hardware con la superficie de ataque mínima de Firecracker (< 50k líneas de código), arranca en milisegundos y no requiere ninguna configuración — instala y listo.
Publicado bajo la licencia APACHE-2.0.
Hecho por @angelorc y comunidad 💛
🤗 actualizado automáticamente con automd