vmsan

🔥 Boîte à outils pour microVM Firecracker en mode bac à sable

Créez, gérez et connectez-vous à des microVM Firecracker isolées depuis la ligne de commande. Démarrez une VM en mode bac à sable en quelques millisecondes, exécutez des commandes, transférez des fichiers — pas besoin de SSH.

📚 Lisez la documentation complète sur vmsan.dev

✨ Fonctionnalités

• ⚡ Démarrage en millisecondes — Les microVM Firecracker démarrent en < 200ms
• 🔒 Isolation sécuritaire — jailer, seccomp, cgroups et espaces de noms réseau par VM
• 🖥️ Shell interactif — PTY WebSocket avec prise en charge complète du terminal
• 📂 Transfert de fichiers — téléversement et téléchargement sans SSH
• 🐳 Images Docker — construction d'un rootfs à partir de n'importe quelle image OCI avec --from-image
• 🏃 Exécution de commandes — exécutez des commandes avec sortie en flux, injection de variables d'environnement et sudo
• 🧩 Plusieurs environnements d'exécution — base, node22, node24, python3.13
• 📸 Instantanés de VM — sauvegardez et restaurez l'état d'une VM
• 📊 Sortie JSON — drapeau --json pour les scripts et l'automatisation

📋 Prérequis

• Linux (x86_64 ou aarch64) avec support KVM
• Accès root/sudo (nécessaire pour le réseau d'appareils TAP et jailer)
• Docker (pour les installations depuis les sources, les reconstructions locales des environnements d'exécution, et --from-image)

🚀 Installation

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

Cette commande télécharge et installe tout dans ~/.vmsan/ :

• Firecracker + Jailer (dernière version)
• Noyau Linux (vmlinux 6.1)
• Rootfs Ubuntu 24.04 (converti de squashfs à ext4)
• CLI vmsan + agent in-VM
• Images runtime (node22, node24, python3.13) téléchargées en tant qu'artefacts préconstruits

Les installations standard des versions téléchargent les environnements intégrés depuis https://artifacts.vmsan.dev/ et ne nécessitent pas Docker. Les installations depuis les sources construisent encore les environnements localement.

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

# Installer les dépendances
bun install

# Compiler l'agent in-VM
cd agent && make install && cd ..

# Compiler la CLI
bun run build

# Lier la version locale
mkdir -p ~/.vmsan/bin
ln -sf "$(pwd)/dist/bin/cli.mjs" ~/.vmsan/bin/vmsan

📖 Utilisation

# Créer et démarrer une VM
vmsan create --runtime node22 --memory 512 --cpus 2

# Créer une VM à partir d'une image Docker
vmsan create --from-image node:22-alpine

# Lister toutes les VM
vmsan list

# Exécuter une commande dans une VM
vmsan exec <vm-id> ls -la

# Exécution interactive avec PTY
vmsan exec -i <vm-id> bash

# Se connecter au shell d'une VM en cours d'exécution
vmsan connect <vm-id>

# Téléverser un fichier vers une VM
vmsan upload <vm-id> ./local-file.txt /remote/path/file.txt

# Télécharger un fichier depuis une VM
vmsan download <vm-id> /remote/path/file.txt ./local-file.txt

# Prendre un instantané d'une VM en cours d'exécution
vmsan snapshot create <vm-id>

# Lister les instantanés
vmsan snapshot list

# Restaurer une VM à partir d'un instantané
vmsan create --snapshot <snapshot-id>

# Arrêter une VM
vmsan stop <vm-id>

# Supprimer une VM
vmsan remove <vm-id>

Drapeaux globaux

Commandes

⚠️ Limitations connues

• Pas de réseau inter-VM (prévu en 0.4.0)
• Pas de configuration déclarative / vmsan.toml (prévu en 0.5.0)
• Pas de support multi-hôte (prévu en 0.7.0)
• Utilise nftables avec application atomique des règles pour l'isolation réseau (depuis 0.2.0)
• Pas de filtrage DNS ou SNI (prévu en 0.3.0)
• ICMP bloqué par défaut depuis les VM (empêche le tunneling ICMP)
• UDP bloqué par défaut sauf DNS (empêche l'exfiltration UDP ; QUIC/HTTP3 ne fonctionnera pas)
• NTP (UDP 123) bloqué — kvm-clock utilisé pour la synchronisation temporelle, les VM de longue durée peuvent dériver
• Le pare-feu hôte (ufw/firewalld) peut nécessiter des règles d'autorisation explicites pour le trafic vmsan
• Linux uniquement — nécessite le support KVM
• Plateforme principale : Ubuntu 24.04 LTS

🛠️ Développement

# Compiler
bun run build

# Lier la version locale
ln -sf "$(pwd)/dist/bin/cli.mjs" ~/.vmsan/bin/vmsan

# Mode développement (surveillance)
bun run dev

# Exécuter les tests
bun run test

# Vérification de types
bun run typecheck

# Lint et formatage
bun run lint
bun run fmt

🏗️ Architecture

bin/            Point d'entrée de la CLI
src/
  commands/     Sous-commandes de la CLI
  services/     Client Firecracker, client agent, service VM
  lib/          Utilitaires (jailer, réseau, shell, journalisation)
  errors/       Système d'erreurs typé
  generated/    Définitions de types de l'API Firecracker
agent/          Agent Go qui s'exécute à l'intérieur de la VM
docs/           Site de documentation (vmsan.dev)

Comment ça fonctionne

1. vmsan utilise Firecracker pour créer des microVM légères avec un jailer pour l'isolation sécuritaire
2. Chaque VM obtient un périphérique réseau TAP avec son propre sous-réseau /30 (198.19.{slot}.0/30)
3. Un agent écrit en Go s'exécute à l'intérieur de la VM, exposant une API HTTP pour l'exécution de commandes, les opérations sur fichiers et l'accès au shell
4. La CLI communique avec l'agent via le réseau hôte-invité

L'état est persistant dans ~/.vmsan/ :