vmsan

🔥 Firecracker microVM sandbox toolkit

Create, manage, and connect to isolated Firecracker microVMs from the command line. Boot a sandboxed VM in milliseconds, run commands, transfer files — no SSH required.

📚 Read the full documentation at vmsan.dev

✨ Features

• ⚡ Millisecond boot — Firecracker microVMs start in < 200ms
• 🔒 Security isolation — jailer, seccomp, cgroups, and per-VM network namespaces
• 🖥️ Interactive shell — WebSocket PTY with full terminal support
• 📂 File transfer — upload and download without SSH
• 🐳 Docker images — build rootfs from any OCI image with --from-image
• 🏃 Command execution — run commands with streaming output, env injection, and sudo
• 🧩 Multiple runtimes — base, node22, node24, python3.13
• 📸 VM snapshots — save and restore VM state
• 📊 JSON output — --json flag for scripting and automation

📋 Prerequisites

• Linux (x86_64 or aarch64) with KVM support
• Root/sudo access (required for TAP device networking and jailer)
• Docker (for source installs, local runtime rebuilds, and --from-image)

🚀 Install

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

This downloads and installs everything into ~/.vmsan/:

• Firecracker + Jailer (latest release)
• Linux kernel (vmlinux 6.1)
• Ubuntu 24.04 rootfs (converted from squashfs to ext4)
• vmsan CLI + in-VM agent
• Runtime images (node22, node24, python3.13) downloaded as prebuilt artifacts

Standard release installs download built-in runtimes from https://artifacts.vmsan.dev/ and do not require Docker. Source installs still build runtimes locally.

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

📖 Usage

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

Global flags

Commands

⚠️ Known Limitations

• No inter-VM networking (planned for 0.4.0)
• No declarative config / vmsan.toml (planned for 0.5.0)
• No multi-host support (planned for 0.7.0)
• Uses nftables with atomic rule application for network isolation (since 0.2.0)
• No DNS or SNI filtering (planned for 0.3.0)
• ICMP blocked by default from VMs (prevents ICMP tunneling)
• UDP blocked by default except DNS (prevents UDP exfiltration; QUIC/HTTP3 will not work)
• NTP (UDP 123) blocked — kvm-clock used for time sync, long-running VMs may drift
• Host firewall (ufw/firewalld) may need explicit allow rules for vmsan traffic
• Linux only — requires KVM support
• Primary platform: Ubuntu 24.04 LTS

🛠️ Development

# 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

🏗️ Architecture

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)

How it works

1. vmsan uses Firecracker to create lightweight microVMs with a jailer for security isolation
2. Each VM gets a TAP network device with its own /30 subnet (198.19.{slot}.0/30)
3. A Go-based agent runs inside the VM, exposing an HTTP API for command execution, file operations, and shell access
4. The CLI communicates with the agent over the host-guest network

State is persisted 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

⚖️ How vmsan compares