🔥 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.
- ⚡ 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 —
--jsonflag for scripting and automation
- 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)
curl -fsSL https://vmsan.dev/install | bashThis 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.
Uninstall
curl -fsSL https://vmsan.dev/install | bash -s -- --uninstallDevelopment setup
If you want to build from source:
# 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# 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>| Flag | Description |
|---|---|
--json |
Output structured JSON |
--verbose |
Show detailed debug output |
| 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 | |
snapshot |
Manage VM snapshots (create, list, delete) | |
doctor |
Check system prerequisites and installation health |
- 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
nftableswith 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
# 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 fmtbin/ 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)
- vmsan uses Firecracker to create lightweight microVMs with a jailer for security isolation
- Each VM gets a TAP network device with its own
/30subnet (198.19.{slot}.0/30) - A Go-based agent runs inside the VM, exposing an HTTP API for command execution, file operations, and shell access
- 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
| vmsan | Docker | gVisor | Kata Containers | Vagrant | |
|---|---|---|---|---|---|
| Isolation level | ✅ Hardware (KVM) | ❌ Shared kernel | ✅ Hardware (QEMU/CH) | ✅ Hardware (VBox/VMware) | |
| Boot time | ✅ ~125ms | ✅ ~50ms | ✅ ~5ms | ❌ 30-60s | |
| Setup complexity | ✅ One command | ✅ Low | ❌ High | ||
| Security model | ✅ Jailer + seccomp + cgroups + dedicated kernel | ✅ Full VM + nested containers | ✅ Full VM | ||
| Network isolation | ✅ Built-in policies (allow/deny/custom) | ❌ Manual (iptables) | ❌ Manual | ||
| 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 | |
| JSON output | ✅ All commands | ❌ | ❌ | ||
| Memory overhead | ✅ ~5 MiB per VM | ✅ ~1 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.
Published under the APACHE-2.0 license.
Made by @angelorc and community 💛
🤖 auto updated with automd