vmsan

🔥 Kit di strumenti sandbox per microVM Firecracker

Crea, gestisci e connettiti a microVM Firecracker isolate dalla riga di comando. Avvia una VM sandbox in millisecondi, esegui comandi, trasferisci file — nessun SSH necessario.

📚 Leggi la documentazione completa su vmsan.dev

✨ Funzionalità

• ⚡ Avvio in millisecondi — Le microVM Firecracker si avviano in < 200ms
• 🔒 Isolamento di sicurezza — jailer, seccomp, cgroups e namespace di rete per VM
• 🖥️ Shell interattiva — WebSocket PTY con supporto terminale completo
• 📂 Trasferimento file — carica e scarica senza SSH
• 🐳 Immagini Docker — costruisci rootfs da qualsiasi immagine OCI con --from-image
• 🏃 Esecuzione comandi — esegui comandi con output in streaming, iniezione di env e sudo
• 🧩 Runtime multipli — base, node22, node24, python3.13
• 📸 Snapshot VM — salva e ripristina lo stato della VM
• 📊 Output JSON — flag --json per scripting e automazione

📋 Prerequisiti

• Linux (x86_64 o aarch64) con supporto KVM
• Accesso root/sudo (richiesto per networking dispositivo TAP e jailer)
• Docker (per installazioni da sorgente, ricostruzioni runtime locali e --from-image)

🚀 Installa

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

Questo scarica e installa tutto in ~/.vmsan/:

• Firecracker + Jailer (ultima release)
• Kernel Linux (vmlinux 6.1)
• rootfs Ubuntu 24.04 (convertito da squashfs a ext4)
• CLI vmsan + agente in-VM
• Immagini runtime (node22, node24, python3.13) scaricate come artefatti precompilati

Le installazioni di release standard scaricano i runtime integrati da https://artifacts.vmsan.dev/ e non richiedono Docker. Le installazioni da sorgente costruiscono ancora i runtime localmente.

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

# Install dependencies
bun install

# Build the in-VM agent
cd agent && make install && cd ..

# Build the CLI
bun run build

# Link local build
mkdir -p ~/.vmsan/bin
ln -sf "$(pwd)/dist/bin/cli.mjs" ~/.vmsan/bin/vmsan

📖 Utilizzo

# Create and start a VM
vmsan create --runtime node22 --memory 512 --cpus 2

# Create a VM from a Docker image
vmsan create --from-image node:22-alpine

# List all VMs
vmsan list

# Execute a command inside a VM
vmsan exec <vm-id> ls -la

# Interactive exec with PTY
vmsan exec -i <vm-id> bash

# Connect to a running VM shell
vmsan connect <vm-id>

# Upload a file to a VM
vmsan upload <vm-id> ./local-file.txt /remote/path/file.txt

# Download a file from a VM
vmsan download <vm-id> /remote/path/file.txt ./local-file.txt

# Snapshot a running VM
vmsan snapshot create <vm-id>

# List snapshots
vmsan snapshot list

# Restore a VM from a snapshot
vmsan create --snapshot <snapshot-id>

# Stop a VM
vmsan stop <vm-id>

# Remove a VM
vmsan remove <vm-id>

Flag globali

Comandi

⚠️ Limitazioni note

• Nessun networking tra VM (pianificato per 0.4.0)
• Nessuna configurazione dichiarativa / vmsan.toml (pianificato per 0.5.0)
• Nessun supporto multi-host (pianificato per 0.7.0)
• Utilizza nftables con applicazione atomica delle regole per l'isolamento di rete (dalla 0.2.0)
• Nessun filtro DNS o SNI (pianificato per 0.3.0)
• ICMP bloccato per default dalle VM (previene il tunneling ICMP)
• UDP bloccato per default tranne DNS (previene l'esfiltrazione UDP; QUIC/HTTP3 non funzionerà)
• NTP (UDP 123) bloccato — kvm-clock usato per sincronizzazione ora, VM a lunga esecuzione possono slittare
• Il firewall host (ufw/firewalld) potrebbe necessitare regole di permesso esplicite per il traffico vmsan
• Solo Linux — richiede supporto KVM
• Piattaforma principale: Ubuntu 24.04 LTS

🛠️ Sviluppo

# Build
bun run build

# Link local build
ln -sf "$(pwd)/dist/bin/cli.mjs" ~/.vmsan/bin/vmsan

# Dev mode (watch)
bun run dev

# Run tests
bun run test

# Type check
bun run typecheck

# Lint & format
bun run lint
bun run fmt

🏗️ Architettura

bin/            CLI entry point
src/
  commands/     CLI subcommands
  services/     Firecracker client, agent client, VM service
  lib/          Utilities (jailer, networking, shell, logging)
  errors/       Typed error system
  generated/    Firecracker API type definitions
agent/          Go agent that runs inside the VM
docs/           Documentation site (vmsan.dev)

Come funziona

1. vmsan utilizza Firecracker per creare microVM leggere con un jailer per isolamento di sicurezza
2. Ogni VM riceve un dispositivo di rete TAP con la propria sottorete /30 (198.19.{slot}.0/30)
3. Un agente basato su Go viene eseguito all'interno della VM, esponendo un'API HTTP per esecuzione comandi, operazioni file e accesso shell
4. La CLI comunica con l'agente tramite la rete host-guest

Lo stato è persistito in ~/.vmsan/:

~/.vmsan/
  vms/          VM state files (JSON)
  jailer/       Chroot directories
  bin/          Agent binary
  kernels/      VM kernel images
  rootfs/       Base root filesystems
  registry/     Docker image rootfs cache
  snapshots/    VM snapshots

⚖️ Confronto con vmsan