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, 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
• Bun >= 1.2
• Go >= 1.22 (to build the in-VM agent)
• Root/sudo access (required for TAP device networking and jailer)
• squashfs-tools (for rootfs conversion during install)

🚀 Install

1. Install Firecracker, kernel, and rootfs

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

Uninstall

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

This downloads and installs into ~/.vmsan/:

• Firecracker + Jailer (latest release)
• Linux kernel (vmlinux 6.1)
• Ubuntu 24.04 rootfs (converted from squashfs to ext4)

2. Install vmsan CLI

# ✨ Auto-detect
npx nypm install vmsan

# npm
npm install vmsan

# yarn
yarn add vmsan

# pnpm
pnpm add vmsan

# bun
bun install vmsan

# deno
deno install npm:vmsan

3. Build the in-VM agent

cd agent
make install
cd ..

Link globally (optional)

bun link

This makes the vmsan command available system-wide.

📖 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

# Stop a VM
vmsan stop <vm-id>

# Remove a VM
vmsan remove <vm-id>

Global flags

Flag	Description
--json	Output structured JSON
--verbose	Show detailed debug output

Commands

Command	Alias	Description
create		Create and start a new microVM
list	ls	List all VMs
start		Start a stopped VM
stop		Stop a running VM
remove	rm	Remove a VM
exec		Execute a command inside a running VM
connect		Open an interactive shell to a VM
upload		Upload files to a VM
download		Download files from a VM
network		Update network policy on a running VM

🛠️ 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 (172.16.{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

	vmsan	Docker	gVisor	Kata Containers	Vagrant
Isolation level	✅ Hardware (KVM)	❌ Shared kernel	⚠️ User-space kernel	✅ Hardware (QEMU/CH)	✅ Hardware (VBox/VMware)
Boot time	✅ ~125ms	✅ ~50ms	✅ ~5ms	⚠️ ~200ms+	❌ 30-60s
Setup complexity	✅ One command	✅ Low	⚠️ Medium	❌ High	⚠️ Medium
Security model	✅ Jailer + seccomp + cgroups + dedicated kernel	⚠️ Namespaces + cgroups	⚠️ Syscall filtering	✅ Full VM + nested containers	✅ Full VM
Network isolation	✅ Built-in policies (allow/deny/custom)	❌ Manual (iptables)	⚠️ Inherits Docker	❌ Manual	⚠️ NAT/bridged
Docker image support	✅ --from-image	✅ Native	✅ Via runsc	✅ Via containerd	❌
Interactive shell	✅ WebSocket PTY	✅ exec	✅ exec	✅ exec	✅ SSH
File transfer	✅ Built-in upload/download	✅ cp	✅ cp	✅ cp	⚠️ Shared folders / SCP
JSON output	✅ All commands	⚠️ Partial	❌	⚠️ Partial	❌
Memory overhead	✅ ~5 MiB per VM	✅ ~1 MiB	⚠️ ~15 MiB	❌ ~30 MiB+	❌ 512 MiB+
Best for	🏆 AI sandboxing, untrusted code, multi-tenant	General workloads	K8s hardening	K8s compliance	Dev environments

Why vmsan? Docker shares the host kernel — a container escape means game over. gVisor intercepts syscalls in user-space, reducing attack surface but not eliminating it. Kata Containers provides real VM isolation but requires complex orchestration (containerd, shimv2, K8s). Vagrant boots full VMs that take 30+ seconds and hundreds of MBs.

vmsan gives you hardware-level isolation with Firecracker's minimal attack surface (< 50k lines of code), boots in milliseconds, and requires zero configuration — install and go.

📄 License

Apache-2.0

Published under the APACHE-2.0 license. Made by @angelorc and community 💛

---

🤖 auto updated with automd