vmsan

🔥 Firecracker microVM サンドボックスツールキット

コマンドラインから、隔離された Firecracker マイクロVMを作成、管理、接続できます。数ミリ秒でサンドボックス化されたVMを起動し、コマンドを実行、ファイルを転送 — SSHは不要です。

📚 詳細なドキュメントは vmsan.dev をご覧ください

✨ 機能

• ⚡ ミリ秒起動 — Firecracker マイクロVMが200ms未満で起動
• 🔒 セキュリティ分離 — jailer、seccomp、cgroups、VMごとのネットワーク名前空間
• 🖥️ インタラクティブシェル — フルターミナル対応のWebSocket PTY
• 📂 ファイル転送 — SSH不要でアップロード/ダウンロード
• 🐳 Docker イメージ — --from-image で任意のOCIイメージからrootfsを構築
• 🏃 コマンド実行 — ストリーミング出力、環境変数注入、sudo対応のコマンド実行
• 🧩 複数のランタイム — base、node22、node24、python3.13
• 📸 VMスナップショット — VM状態の保存と復元
• 📊 JSON出力 — スクリプトや自動化のための --json フラグ

📋 前提条件

• KVM対応のLinux (x86_64 または aarch64)
• root/sudo アクセス (TAPデバイスネットワークとjailerに必要)
• Docker (ソースインストール、ローカルランタイム再構築、--from-image に必要)

🚀 インストール

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

これにより、すべてが ~/.vmsan/ にダウンロードされインストールされます:

• Firecracker + Jailer (最新リリース)
• Linuxカーネル (vmlinux 6.1)
• Ubuntu 24.04 rootfs (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

📖 使い方

# VMを作成して起動
vmsan create --runtime node22 --memory 512 --cpus 2

# DockerイメージからVMを作成
vmsan create --from-image node:22-alpine

# すべてのVMを一覧表示
vmsan list

# VM内でコマンドを実行
vmsan exec <vm-id> ls -la

# PTYを使用した対話型実行
vmsan exec -i <vm-id> bash

# 実行中のVMシェルに接続
vmsan connect <vm-id>

# VMにファイルをアップロード
vmsan upload <vm-id> ./local-file.txt /remote/path/file.txt

# VMからファイルをダウンロード
vmsan download <vm-id> /remote/path/file.txt ./local-file.txt

# 実行中のVMのスナップショットを作成
vmsan snapshot create <vm-id>

# スナップショットを一覧表示
vmsan snapshot list

# スナップショットからVMを復元
vmsan create --snapshot <snapshot-id>

# VMを停止
vmsan stop <vm-id>

# VMを削除
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 で計画)
• VMからのICMPはデフォルトでブロック (ICMPトンネリング防止)
• UDPはDNS以外デフォルトでブロック (UDP外部送信防止; QUIC/HTTP3は動作しない)
• NTP (UDP 123) はブロック — 時刻同期にはkvm-clockを使用、長時間実行VMはドリフトの可能性
• ホストファイアウォール (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

# Lint & フォーマット
bun run lint
bun run fmt

🏗️ アーキテクチャ

bin/            CLIエントリポイント
src/
  commands/     CLIサブコマンド
  services/    Firecrackerクライアント、エージェントクライアント、VMサービス
  lib/          ユーティリティ (jailer、ネットワーキング、シェル、ロギング)
  errors/      型付きエラーシステム
  generated/   Firecracker API型定義
agent/          VM内で動作するGoエージェント
docs/           ドキュメントサイト (vmsan.dev)

仕組み

1. vmsan は Firecracker を使用して、jailerによるセキュリティ分離で軽量なマイクロVMを作成
2. 各VMは独自の /30 サブネット (198.19.{slot}.0/30) を持つTAPネットワークデバイスを取得
3. VM内ではGoベースのエージェントが動作し、コマンド実行、ファイル操作、シェルアクセスのためのHTTP APIを公開
4. CLIはホスト-ゲストネットワークを介してエージェントと通信

状態は ~/.vmsan/ に保存されます:

~/.vmsan/
  vms/          VM状態ファイル (JSON)
  jailer/       Chrootディレクトリ
  bin/          エージェントバイナリ
  kernels/      VMカーネルイメージ
  rootfs/       ベースルートファイルシステム
  registry/     Dockerイメージrootfsキャッシュ
  snapshots/    VMスナップショット

⚖️ vmsanとの比較

なぜvmsanなのか？ Dockerはホストカーネルを共有するため、コンテナエスケープが発生するとゲームオーバーです。gVisorはユーザー空間でシステムコールをインターセプトし、攻撃対象領域を減らしますが、排除するわけではありません。Kata Containersは本物のVM分離を提供しますが、複雑なオーケストレーション（containerd、shimv2、K8s）が必要です。VagrantはフルVMを起動し、30秒以上と数百MBを要します。

vmsanは、Firecrackerの最小限の攻撃対象領域（5万行未満のコード）によりハードウェアレベルの分離を提供し、ミリ秒で起動し、設定不要でインストールしてすぐに使えます。

📄 ライセンス

Apache-2.0

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

🤖 automd で自動更新