vmsan

🔥 Инструментарий для песочницы Firecracker microVM

Создавайте, управляйте и подключайтесь к изолированным microVM с помощью Firecracker прямо из командной строки. Загрузите изолированную VM за миллисекунды, выполняйте команды, передавайте файлы — без SSH.

📚 Полная документация на vmsan.dev

✨ Возможности

• ⚡ Загрузка за миллисекунды — microVM Firecracker стартуют менее чем за 200 мс
• 🔒 Изоляция безопасности — jailer, seccomp, cgroups и отдельные сетевые пространства имён для каждой VM
• 🖥️ Интерактивная оболочка — WebSocket PTY с полной поддержкой терминала
• 📂 Передача файлов — загрузка и скачивание без SSH
• 🐳 Docker-образы — создание rootfs из любого OCI-образа с помощью --from-image
• 🏃 Выполнение команд — запуск команд с потоковым выводом, инъекцией переменных окружения и sudo
• 🧩 Несколько сред выполнения — base, node22, node24, python3.13
• 📸 Снимки VM — сохранение и восстановление состояния VM
• 📊 Вывод в JSON — флаг --json для скриптов и автоматизации

📋 Предварительные требования

• Linux (x86_64 или aarch64) с поддержкой KVM
• Доступ root/sudo (требуется для настройки сетевых устройств TAP и jailer)
• Docker (для установки из исходников, локальной пересборки сред выполнения и --from-image)

🚀 Установка

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

Эта команда загружает и устанавливает всё в ~/.vmsan/:

• Firecracker + Jailer (последний релиз)
• Ядро Linux (vmlinux 6.1)
• Корневая файловая система Ubuntu 24.04 (преобразована из squashfs в ext4)
• CLI vmsan + внутри-VM агент
• Образы сред выполнения (node22, node24, python3.13) загружаются как предварительно собранные артефакты

При установке стандартного релиза встроенные среды выполнения загружаются с https://artifacts.vmsan.dev/ и не требуют Docker. При установке из исходников среды выполнения собираются локально.

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

# Установка зависимостей
bun install

# Сборка агента внутри VM
cd agent && make install && cd ..

# Сборка CLI
bun run build

# Связывание локальной сборки
mkdir -p ~/.vmsan/bin
ln -sf "$(pwd)/dist/bin/cli.mjs" ~/.vmsan/bin/vmsan

📖 Использование

# Создать и запустить VM
vmsan create --runtime node22 --memory 512 --cpus 2

# Создать VM из Docker-образа
vmsan create --from-image node:22-alpine

# Список всех VM
vmsan list

# Выполнить команду внутри VM
vmsan exec <vm-id> ls -la

# Интерактивное выполнение с PTY
vmsan exec -i <vm-id> bash

# Подключиться к оболочке запущенной VM
vmsan connect <vm-id>

# Загрузить файл в VM
vmsan upload <vm-id> ./local-file.txt /remote/path/file.txt

# Скачать файл из VM
vmsan download <vm-id> /remote/path/file.txt ./local-file.txt

# Создать снимок запущенной VM
vmsan snapshot create <vm-id>

# Список снимков
vmsan snapshot list

# Восстановить VM из снимка
vmsan create --snapshot <snapshot-id>

# Остановить VM
vmsan stop <vm-id>

# Удалить VM
vmsan remove <vm-id>

Глобальные флаги

Команды

⚠️ Известные ограничения

• Нет сетевого взаимодействия между VM (планируется в 0.4.0)
• Нет декларативной конфигурации / vmsan.toml (планируется в 0.5.0)
• Нет поддержки нескольких хостов (планируется в 0.7.0)
• Использует nftables с атомарным применением правил для сетевой изоляции (начиная с 0.2.0)
• Нет фильтрации DNS или SNI (планируется в 0.3.0)
• ICMP по умолчанию заблокирован из VM (предотвращает ICMP-туннелирование)
• UDP по умолчанию заблокирован, кроме DNS (предотвращает эксфильтрацию по UDP; QUIC/HTTP3 работать не будут)
• NTP (UDP 123) заблокирован — для синхронизации времени используется kvm-clock, долгоживущие VM могут дрейфовать
• Брандмауэр хоста (ufw/firewalld) может требовать явных правил разрешения для трафика vmsan
• Только Linux — требуется поддержка KVM
• Основная платформа: Ubuntu 24.04 LTS

🛠️ Разработка

# Сборка
bun run build

# Связывание локальной сборки
ln -sf "$(pwd)/dist/bin/cli.mjs" ~/.vmsan/bin/vmsan

# Режим разработки (слежение)
bun run dev

# Запуск тестов
bun run test

# Проверка типов
bun run typecheck

# Линтинг и форматирование
bun run lint
bun run fmt

🏗️ Архитектура

bin/            Точка входа CLI
src/
  commands/     Подкоманды CLI
  services/    Клиент Firecracker, клиент агента, сервис VM
  lib/         Утилиты (jailer, сеть, оболочка, логирование)
  errors/      Система типизированных ошибок
  generated/   Определения типов API Firecracker
agent/          Go-агент, работающий внутри VM
docs/           Сайт документации (vmsan.dev)

Как это работает

1. vmsan использует Firecracker для создания лёгких microVM с jailer для изоляции безопасности
2. Каждая VM получает сетевое устройство TAP с собственной подсетью /30 (198.19.{slot}.0/30)
3. Go-агент работает внутри VM и предоставляет HTTP API для выполнения команд, операций с файлами и доступа к оболочке
4. CLI взаимодействует с агентом через сеть хост-гость

Состояние сохраняется в ~/.vmsan/:

~/.vmsan/
  vms/          Файлы состояния VM (JSON)
  jailer/       Директории chroot
  bin/          Бинарный файл агента
  kernels/      Образы ядер VM
  rootfs/       Базовые корневые файловые системы
  registry/     Кэш rootfs Docker-образов
  snapshots/    Снимки VM

⚖️ Сравнение vmsan с аналогами