vmsan

🔥 Conjunto de ferramentas para sandbox microVM Firecracker

Crie, gerencie e conecte-se a microVMs Firecracker isoladas a partir da linha de comando. Inicie uma VM em sandbox em milissegundos, execute comandos, transfira arquivos — sem necessidade de SSH.

📚 Leia a documentação completa em vmsan.dev

✨ Recursos

• ⚡ Inicialização em milissegundos — microVMs Firecracker iniciam em < 200ms
• 🔒 Isolamento de segurança — jailer, seccomp, cgroups e namespaces de rede por VM
• 🖥️ Shell interativo — PTY via WebSocket com suporte total a terminal
• 📂 Transferência de arquivos — upload e download sem SSH
• 🐳 Imagens Docker — construa rootfs a partir de qualquer imagem OCI com --from-image
• 🏃 Execução de comandos — execute comandos com saída em streaming, injeção de variáveis de ambiente e sudo
• 🧩 Múltiplos runtimes — base, node22, node24, python3.13
• 📸 Snapshots de VM — salve e restaure o estado da VM
• 📊 Saída JSON — flag --json para scripts e automação

📋 Pré-requisitos

• Linux (x86_64 ou aarch64) com suporte a KVM
• Acesso root/sudo (necessário para rede com dispositivo TAP e jailer)
• Docker (para instalações a partir da fonte, reconstruções de runtime locais e --from-image)

🚀 Instalação

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

Isso baixa e instala tudo em ~/.vmsan/:

• Firecracker + Jailer (última versão)
• Kernel Linux (vmlinux 6.1)
• Rootfs Ubuntu 24.04 (convertido de squashfs para ext4)
• CLI vmsan + agente in-VM
• Imagens de runtime (node22, node24, python3.13) baixadas como artefatos pré-construídos

As instalações de versão padrão baixam runtimes integrados de https://artifacts.vmsan.dev/ e não exigem Docker. Instalações a partir da fonte ainda constroem runtimes localmente.

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

# Instalar dependências
bun install

# Compilar o agente in-VM
cd agent && make install && cd ..

# Compilar a CLI
bun run build

# Vincular compilação local
mkdir -p ~/.vmsan/bin
ln -sf "$(pwd)/dist/bin/cli.mjs" ~/.vmsan/bin/vmsan

📖 Uso

# Criar e iniciar uma VM
vmsan create --runtime node22 --memory 512 --cpus 2

# Criar uma VM a partir de uma imagem Docker
vmsan create --from-image node:22-alpine

# Listar todas as VMs
vmsan list

# Executar um comando dentro de uma VM
vmsan exec <vm-id> ls -la

# Execução interativa com PTY
vmsan exec -i <vm-id> bash

# Conectar ao shell de uma VM em execução
vmsan connect <vm-id>

# Fazer upload de um arquivo para uma VM
vmsan upload <vm-id> ./local-file.txt /remote/path/file.txt

# Fazer download de um arquivo de uma VM
vmsan download <vm-id> /remote/path/file.txt ./local-file.txt

# Criar snapshot de uma VM em execução
vmsan snapshot create <vm-id>

# Listar snapshots
vmsan snapshot list

# Restaurar uma VM a partir de um snapshot
vmsan create --snapshot <snapshot-id>

# Parar uma VM
vmsan stop <vm-id>

# Remover uma VM
vmsan remove <vm-id>

Flags globais

Comandos

⚠️ Limitações conhecidas

• Sem rede entre VMs (planejado para 0.4.0)
• Sem configuração declarativa / vmsan.toml (planejado para 0.5.0)
• Sem suporte a múltiplos hosts (planejado para 0.7.0)
• Usa nftables com aplicação atômica de regras para isolamento de rede (desde 0.2.0)
• Sem filtragem DNS ou SNI (planejado para 0.3.0)
• ICMP bloqueado por padrão nas VMs (impede tunelamento ICMP)
• UDP bloqueado por padrão, exceto DNS (impede exfiltração UDP; QUIC/HTTP3 não funcionarão)
• NTP (UDP 123) bloqueado — kvm-clock usado para sincronização de tempo; VMs de longa duração podem apresentar desvio
• Firewall do host (ufw/firewalld) pode precisar de regras explícitas de permissão para tráfego vmsan
• Apenas Linux — requer suporte KVM
• Plataforma principal: Ubuntu 24.04 LTS

🛠️ Desenvolvimento

# Compilar
bun run build

# Vincular compilação local
ln -sf "$(pwd)/dist/bin/cli.mjs" ~/.vmsan/bin/vmsan

# Modo de desenvolvimento (watch)
bun run dev

# Executar testes
bun run test

# Verificação de tipos
bun run typecheck

# Lint e formatação
bun run lint
bun run fmt

🏗️ Arquitetura

bin/            Ponto de entrada da CLI
src/
  commands/     Subcomandos da CLI
  services/     Cliente Firecracker, cliente agente, serviço de VM
  lib/          Utilitários (jailer, rede, shell, logging)
  errors/       Sistema de erros tipados
  generated/    Definições de tipos da API do Firecracker
agent/          Agente Go que executa dentro da VM
docs/           Site de documentação (vmsan.dev)

Como funciona

1. vmsan usa Firecracker para criar microVMs leves com um jailer para isolamento de segurança
2. Cada VM recebe um dispositivo de rede TAP com sua própria sub-rede /30 (198.19.{slot}.0/30)
3. Um agente baseado em Go é executado dentro da VM, expondo uma API HTTP para execução de comandos, operações com arquivos e acesso ao shell
4. A CLI se comunica com o agente através da rede host-convidado

O estado é persistido em ~/.vmsan/:

~/.vmsan/
  vms/          Arquivos de estado da VM (JSON)
  jailer/       Diretórios chroot
  bin/          Binário do agente
  kernels/      Imagens do kernel da VM
  rootfs/       Sistemas de arquivos raiz base
  registry/     Cache de rootfs de imagens Docker
  snapshots/    Snapshots da VM

⚖️ Comparação com outras ferramentas