vmsan

🔥 Firecracker microVM Sandbox Toolkit

Erstellen, verwalten und verbinden Sie isolierte Firecracker‑microVMs von der Kommandozeile. Starten Sie eine sandboxierte VM in Millisekunden, führen Sie Befehle aus, übertragen Sie Dateien — kein SSH erforderlich.

📚 Lesen Sie die vollständige Dokumentation auf vmsan.dev

✨ Funktionen

• ⚡ Millisekunden‑Start — Firecracker‑microVMs starten in < 200ms
• 🔒 Sicherheitsisolierung — jailer, seccomp, cgroups und Netzwerknamespaces pro VM
• 🖥️ Interaktive Shell — WebSocket‑PTY mit vollständiger Terminalunterstützung
• 📂 Dateiübertragung — hochladen und herunterladen ohne SSH
• 🐳 Docker‑Images — rootfs aus jedem OCI‑Image erstellen mit --from-image
• 🏃 Befehlsausführung — Befehle mit Streaming‑Ausgabe, Umgebungsvariablen‑Injektion und sudo
• 🧩 Mehrere Laufzeiten — base, node22, node24, python3.13
• 📸 VM‑Snapshots — VM‑Zustand speichern und wiederherstellen
• 📊 JSON‑Ausgabe — --json‑Flag für Skripterstellung und Automatisierung

📋 Voraussetzungen

• Linux (x86_64 oder aarch64) mit KVM‑Unterstützung
• Root‑/sudo‑Zugriff (erforderlich für TAP‑Geräte‑Netzwerk und jailer)
• Docker (für Quellinstallationen, lokale Neuerstellungen der Laufzeiten und --from-image)

🚀 Install

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

Dies lädt alles herunter und installiert es in ~/.vmsan/:

• Firecracker + Jailer (neueste Version)
• Linux‑Kernel (vmlinux 6.1)
• Ubuntu 24.04 rootfs (von squashfs zu ext4 konvertiert)
• vmsan CLI + In‑VM‑Agent
• Laufzeit‑Images (node22, node24, python3.13) als vorgefertigte Artefakte heruntergeladen

Standard‑Releases laden integrierte Laufzeiten von https://artifacts.vmsan.dev/ herunter und benötigen kein Docker. Quellinstallationen bauen Laufzeiten weiterhin lokal.

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

📖 Verwendung

# 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>

Globale Flags

Befehle

⚠️ Bekannte Einschränkungen

• Kein Netzwerk zwischen VMs (geplant für 0.4.0)
• Keine deklarative Konfiguration / vmsan.toml (geplant für 0.5.0)
• Keine Multi‑Host‑Unterstützung (geplant für 0.7.0)
• Verwendet nftables mit atomarer Regelanwendung für Netzwerkisolierung (seit 0.2.0)
• Kein DNS‑ oder SNI‑Filter (geplant für 0.3.0)
• ICMP standardmäßig von VMs blockiert (verhindert ICMP‑Tunneling)
• UDP standardmäßig blockiert außer DNS (verhindert UDP‑Exfiltration; QUIC/HTTP3 funktioniert nicht)
• NTP (UDP 123) blockiert — kvm‑clock für Zeitsynchronisierung verwendet, langlaufende VMs können abweichen
• Host‑Firewall (ufw/firewalld) benötigt möglicherweise explizite Allow‑Regeln für vmsan‑Datenverkehr
• Nur Linux — erfordert KVM‑Unterstützung
• Primäre Plattform: Ubuntu 24.04 LTS

🛠️ Entwicklung

# 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

🏗️ Architektur

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)

Funktionsweise

1. vmsan verwendet Firecracker, um leichte microVMs mit einem Jailer für Sicherheitsisolierung zu erstellen
2. Jede VM erhält ein TAP‑Netzwerkgerät mit eigenem /30‑Subnetz (198.19.{slot}.0/30)
3. Ein auf Go basierender Agent läuft in der VM und stellt eine HTTP‑API für Befehlsausführung, Dateioperationen und Shell‑Zugriff bereit
4. Die CLI kommuniziert mit dem Agenten über das Host‑Gast‑Netzwerk

Der Zustand wird in ~/.vmsan/ gespeichert:

~/.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

⚖️ Wie vmsan im Vergleich abschneidet