angelorc/vmsanFirecracker simplificado. Inicia microVMs seguras en milisegundos, desde la instalación hasta la shell interactiva en un solo comando.
<p align="center">
<h1 align="center">vmsan</h1>
<p align="center">🔥 Kit de caja de arena microVM Firecracker</p>
</p>
<!-- automd:badges color="yellow" license licenseSrc bundlephobia packagephobia -->
[](https://npmjs.com/package/vmsan)
[](https://npm.chart.dev/vmsan)
[](https://bundlephobia.com/package/vmsan)
[](https://packagephobia.com/result?p=vmsan)
[](https://github.com/angelorc/vmsan/blob/main/LICENSE)
<!-- /automd -->
Crea, gestiona y conéctate a microVMs [Firecracker](https://github.com/firecracker-microvm/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](https://vmsan.dev)**
<p align="center">
<img src="https://assets.kitploit.com/production/public/readmes/12341/9b50cd0526e48ca7ade0ad567c67888b0d5a5b9e33ab977bcc36b38a03906b8c.gif" alt="vmsan demo" width="720" />
</p>
## ✨ 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
```bash
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.
<details>
<summary>Desinstalación</summary>
```bash
curl -fsSL https://vmsan.dev/install | bash -s -- --uninstall
```
</details>
<details>
<summary>Configuración de desarrollo</summary>
Si quieres construir desde la fuente:
```bash
# 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
```
</details>
## 📖 Uso
```bash
# 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
| Flag | Descripción |
| ----------- | ------------------------------ |
| `--json` | Salida JSON estructurada |
| `--verbose` | Mostrar salida detallada de depuración |
### Comandos
| 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 |
## ⚠️ 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
```bash
# 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](https://github.com/firecracker-microvm/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
| | 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.
## 📄 Licencia
[Apache-2.0](https://github.com/angelorc/vmsan/blob/main/LICENSE)
<!-- automd:contributors author="angelorc" license="Apache-2.0" -->
Publicado bajo la licencia [APACHE-2.0](https://github.com/angelorc/vmsan/blob/main/LICENSE).
Hecho por [@angelorc](https://github.com/angelorc) y [comunidad](https://github.com/angelorc/vmsan/graphs/contributors) 💛
<br><br>
<a href="https://github.com/angelorc/vmsan/graphs/contributors">
<img src="https://contrib.rocks/image?repo=angelorc/vmsan" />
</a>
<!-- /automd -->
<!-- automd:with-automd -->
---
_🤗 actualizado automáticamente con [automd](https://automd.unjs.io)_
<!-- /automd -->