vmsan

🔥 Firecracker 微虚拟机沙盒工具包

从命令行创建、管理和连接隔离的 Firecracker 微虚拟机。可在毫秒内启动沙盒虚拟机，运行命令，传输文件 —— 无需 SSH。

📚 阅读完整文档：vmsan.dev

✨ 特性

• ⚡ 毫秒级启动 — Firecracker 微虚拟机在 200ms 内启动
• 🔒 安全隔离 — jailer、seccomp、cgroups 以及每 VM 网络命名空间
• 🖥️ 交互式 Shell — 支持完整终端的 WebSocket PTY
• 📂 文件传输 — 无需 SSH 即可上传和下载
• 🐳 Docker 镜像 — 使用 --from-image 从任意 OCI 镜像构建根文件系统
• 🏃 命令执行 — 运行命令，支持流式输出、环境变量注入和 sudo
• 🧩 多种运行时 — base、node22、node24、python3.13
• 📸 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）
• vmsan CLI + 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

📖 用法

# 创建并启动一个虚拟机
vmsan create --runtime node22 --memory 512 --cpus 2

# 从 Docker 镜像创建虚拟机
vmsan create --from-image node:22-alpine

# 列出所有虚拟机
vmsan list

# 在虚拟机内执行命令
vmsan exec <vm-id> ls -la

# 交互式执行（带 PTY）
vmsan exec -i <vm-id> bash

# 连接到运行中的虚拟机 Shell
vmsan connect <vm-id>

# 上传文件到虚拟机
vmsan upload <vm-id> ./local-file.txt /remote/path/file.txt

# 从虚拟机下载文件
vmsan download <vm-id> /remote/path/file.txt ./local-file.txt

# 对运行中的虚拟机创建快照
vmsan snapshot create <vm-id>

# 列出快照
vmsan snapshot list

# 从快照恢复虚拟机
vmsan create --snapshot <snapshot-id>

# 停止虚拟机
vmsan stop <vm-id>

# 移除虚拟机
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（防止 ICMP 隧道）
• 除 DNS 外默认阻止 UDP（防止 UDP 泄露；QUIC/HTTP3 将无法工作）
• NTP（UDP 123）被阻止 — 使用 kvm-clock 进行时间同步，长时间运行的虚拟机可能发生漂移
• 主机防火墙（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 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)

工作原理

1. vmsan 使用 Firecracker 创建轻量级微虚拟机，并借助 jailer 实现安全隔离
2. 每个虚拟机获得一个 TAP 网络设备，拥有自己的 /30 子网（198.19.{slot}.0/30）
3. 一个基于 Go 的 代理 在虚拟机内运行，提供 HTTP API 供命令执行、文件操作和 Shell 访问
4. CLI 通过主机-客户机网络与代理通信

状态持久化存储在 ~/.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 对比

为什么选择 vmsan？ Docker 共享宿主机内核 — 容器逃逸意味着全盘崩溃。gVisor 在用户态拦截系统调用，减少了攻击面但仍未根除。Kata Containers 提供了真正的虚拟机隔离，但需要复杂的编排（containerd、shimv2、K8s）。Vagrant 启动完整的虚拟机，需要 30 多秒和数百 MB。

vmsan 利用 Firecracker 极小的攻击面（不到 5 万行代码）提供了 硬件级隔离，启动时间仅 毫秒级，并且 零配置 — 安装即用。

📄 许可证

Apache-2.0

根据 APACHE-2.0 许可证发布。 由 @angelorc 和 社区 💛 制作

🤖 自动更新自 automd