smolvm

デフォルトで分離された状態でソフトウェアを配布・実行します。

これは以下のことを可能にするCLIツールです：

1. カスタムLinux仮想マシンをローカルで管理・実行：サブ秒のコールドスタート、クロスプラットフォーム（macOS、Linux、Windows）、弾力的なメモリ使用量。
2. ステートフルな仮想マシンを単一ファイル（.smolmachine）にパックし、サポートされている任意のプラットフォームで再水和（rehydrate）できます。

インストール

# インストール（macOS + Linux）
curl -sSL https://smolmachines.com/install.sh | bash

# コーディングエージェント向け — インストール + 全コマンドの確認
curl -sSL https://smolmachines.com/install.sh | bash && smolvm --help

または GitHub Releases からダウンロードし、~/.local/share/ に配置します。

Windows: windows-x86_64 リリース（krun.dll + libkrunfw.dll を同梱）をダウンロードし、解凍して smolvm.exe を実行します。Windows Hypervisor Platform（WHP）機能を有効にする必要があります。

クイックスタート

# 一時的なVMでコマンドを実行（終了後にクリーンアップ）
smolvm machine run --net --image alpine -- sh -c "echo 'Hello world from a microVM' && uname -a"

# 対話型シェル
smolvm machine run --net -it --image alpine -- /bin/sh
# VM内で: apk add sl && sl && exit

Smolfile

Smolfile はマシンを TOML で宣言します — Dockerfile や cloud-init ファイルに相当しますが、VM全体を対象とします：イメージ、リソース、ネットワークポリシー、マウント、ポート、セットアップコマンドを1つのチェックインされたファイルにまとめます。

image = "python:3.12-alpine"
net = true
cpus = 4
memory = 4096

ports = ["8000:8000", "5173-5180:5173-5180"]
volumes = ["./src:/app"]
init = ["pip install -r /app/requirements.txt"]

[network]
allow_hosts = ["api.stripe.com", "pypi.org"]

[auth]
ssh_agent = true

smolvm machine create --name myvm -s Smolfile   # または --smolfile <PATH>
smolvm machine start --name myvm

ポートマッピングは単一ポート（"8080"）、明示的なマッピング（"8080:80"）、または等長の1対1レンジ（"5173-5180:5173-5180"）を受け付けます。マシンは最大64個の具体的なマッピングを公開できます。

不明なキーは無視されるのではなく拒否されるため、タイプミスは作成時に失敗し、静かに何も行われないことはありません。

一般的なキー：image、cpus、memory、net、ports、volumes、env、 init、workdir、gpu、cuda、docker_socket、storage、overlay、および [network]、[dev]、[auth]、[health]、[restart]、[service] テーブル。

マシンを再利用可能なイメージにスナップショット

環境を維持するために Dockerfile は必要ありません。手動または Smolfile からマシンを自由にセットアップし、停止したマシンを .smolmachine アーティファクトにパックして、任意の OCI レジストリにプッシュします：

smolvm machine shell --name myvm          # 対話的にインストール・設定
smolvm machine stop  --name myvm
smolvm pack create --from-vm myvm -o myvm
smolvm pack push --file myvm.smolmachine ghcr.io/you/myvm:v1

その後、誰でもプルしてまったく同じマシンを起動できます：

smolvm pack pull ghcr.io/you/myvm:v1

動作する Smolfile の例：python · node · docker-in-vm · local-llm · headless-browser · doom

こんな用途に

信頼できないコードのサンドボックス化 — 信頼できないプログラムをハードウェア分離されたVMで実行します。ホストのファイルシステム、ネットワーク、認証情報はハイパーバイザーの境界によって分離されます。

# ネットワークはデフォルトでオフ — 信頼できないコードは外部に通信できない
smolvm machine run --image alpine -- nslookup example.com
# 失敗 — ネットワークアクセスなし

# 送信を制限 — 特定のホストのみ許可
smolvm machine run --net --image alpine --allow-host registry.npmjs.org -- wget -q -O /dev/null https://registry.npmjs.org
# 成功 — 許可されたホスト

smolvm machine run --net --image alpine --allow-host registry.npmjs.org -- wget -q -O /dev/null https://google.com
# 失敗 — 許可リストにない

ポータブル実行ファイルへのパック — 任意のワークロードを自己完結型バイナリに変換します。すべての依存関係は事前に組み込まれており、インストール手順や実行時のダウンロードは不要で、<200msで起動します。

smolvm pack create --image python:3.12-alpine -o ./python312
./python312 run -- python3 --version
# Python 3.12.x — 分離されており、pyenv/venv/condaは不要

ローカルコンテナイメージの使用 — CI、エアギャップ環境、高速なイテレーション向け。--image に docker save / podman save アーカイブを指定するか、stdin からパイプするか、展開済みの rootfs ディレクトリを指定します。イメージ処理はコンテナツールに委任され、smolvm は結果を起動するだけです。

# ローカルでビルドし、push/pullなしでVMで実行
docker build -t myapp .
docker save myapp | smolvm machine run --image - -- ./app

# アーカイブファイルから（ネットワークなしで起動）
smolvm machine run --image ./myapp.tar -- ./app

# 展開済みの rootfs ディレクトリから
smolvm machine run --image ./rootfs/ -- ./app

開発用の永続マシン — 作成、停止、開始。インストールしたパッケージは再起動後も保持されます。

smolvm machine create --net --name myvm
smolvm machine start --name myvm
smolvm machine exec --name myvm -- apk add sl
smolvm machine exec --name myvm -it -- /bin/sh
# 内部: sl, ls, uname -a — 'exit' と入力して終了
smolvm machine stop --name myvm

秘密鍵をゲストにコピーせずに git と SSH を使用。 ホストの SSH エージェントを VM に転送します。ソケットが利用可能な間、ゲストはエージェントに転送された任意の鍵での署名を要求できます。信頼するワークロードにのみ転送してください。ホストで SSH エージェントが実行されている必要があります（確認は ssh-add -l）。

smolvm machine run --ssh-agent --net --image alpine -- sh -c "apk add -q openssh-client && ssh-add -l"
# ホストの鍵を一覧表示します。秘密鍵の素材はホストのエージェントに残ります

smolvm machine exec --name myvm -- git clone [email protected]:org/private-repo.git

ファイルで環境を宣言 — 再現可能なマシン設定については上記の Smolfile を参照してください。また、Dockerfile を書かずに設定済みマシンを再利用可能な .smolmachine イメージにスナップショットする方法も参照してください。

仕組み

各ワークロードは、Hypervisor.framework（macOS）、KVM（Linux）、または Windows Hypervisor Platform（Windows）上で独自のゲストカーネルを持つハードウェア仮想化VMで実行されます。libkrun がVMMであり、libkrunfw がゲストカーネルを提供します。.smolmachine にパックすれば、ホストアーキテクチャが一致する場所ならどこでも、依存関係ゼロで実行できます。

イメージは OCI 形式を使用します — Docker が使用するのと同じオープン標準です。Docker Hub、ghcr.io、その他の OCI レジストリ上の任意のイメージをプルしてマイクロVMとして起動できます。Docker デーモンは不要です。

デフォルト：4 vCPU、8 GiB RAM。メモリは virtio balloon により弾力的です — ホストはゲストが実際に使用する分のみをコミットし、残りは自動的に回収します。vCPU スレッドはアイドル時にハイパーバイザー内でスリープするため、オーバープロビジョニングのコストはほぼゼロです。--cpus と --mem で上書きできます。

セキュリティモデル

smolvm は、各ワークロードに個別のVMとゲストカーネルを提供することで、ゲスト/ホスト境界を強化します。それ自体は、堅牢化されたマルチユーザー制御プレーンではありません：

• smolvm CLI および VMM プロセスは、呼び出し元のホストユーザーの権限で実行されます。そのユーザーアカウント、ホストOS、ハイパーバイザーバックエンド、libkrun、および smolvm は信頼済みコンピューティングベースに含まれます。
• --volume で渡されたホストディレクトリは、要求されたアクセス権でゲストに意図的に公開されます。信頼できないワークロードに秘密情報や機密パスをマウントしないでください。
• --ssh-agent は秘密鍵の素材をゲストにコピーしませんが、ゲストに転送されたエージェントソケットへのアクセスを許可し、したがってVM実行中に署名を要求する能力を付与します。
• ネットワーキングはデフォルトで無効です。--net、ポート転送、またはホストサービスの有効化は、ワークロードの到達可能な表面を拡大します。
• スタンドアロンのローカル使用では、smolvm の状態と制御エンドポイントは呼び出し元ユーザーの環境に限定されます。悪意のあるローカル共同テナントに対しては、VMM プロセス周辺にホストレベルのアカウント分離とOSコンファインメントを追加してください。このセクションは、別個の smolmachines クラウド制御プレーンやそのテナント分離保証については説明していません。
• リリースアーカイブは SHA-256 チェックサムを公開し、インストーラーはチェックサムファイルが利用可能な場合に不一致を拒否します。リリースは現在署名されておらず、来歴証明も付随していません。また、インストーラーはチェックサムファイルをダウンロードできない場合でもインストールを許可します。

ゲスト内の root は信頼できないものとして扱ってください。VM境界はホストへの直接アクセスを制限しますが、マウント、ネットワークアクセス、ポート、SSHエージェントアクセスなど、明示的に転送されたすべての機能はワークロードの権限の一部になります。

比較

プラットフォームサポート

既知の制限事項

• ネットワークはオプトインです（machine create の --net）。TCP/UDPのみ、ICMPは不可。
• ボリュームマウント：ディレクトリのみ（単一ファイルは不可）。/workspace へのマウント（-v /host/dir:/workspace）はデフォルトのストレージディスクワークスペースより優先されます — 代わりにホストディレクトリが使用されます。
• macOS：バイナリは Hypervisor.framework の entitlement（com.apple.security.hypervisor）で署名されている必要があります。配布リリースは署名済みです。再署名または新規ビルドしたバイナリは静かにそれを失い、すべてのVM起動が krun_start_enter returned: -22 (EINVAL) で失敗します。再署名してください（アドホックで問題ありません）：codesign --force --sign - --entitlements hv.entitlements <smolvm-bin>。ここで hv.entitlements は <key>com.apple.security.hypervisor</key><true/> を含む plist です。
• --ssh-agent はホストで SSH エージェントが実行されている必要があります（SSH_AUTH_SOCK が設定されている必要があります）。
• GPU アクセラレーションには、GPU=1 でビルドされた libkrun と、ホスト上の virglrenderer + Vulkan ドライバーが必要です（下記の GPU アクセラレーション を参照）。
• Windows：--net は他のプラットフォームと同じように動作します（インバウンドポート転送付き virtio-net、アウトバウンド専用VM用のTSI）。machine exec / 対話型セッション、machine stats も同様です。Windows ではまだ利用不可：GPU アクセラレーションと machine fork / スナップショット。Pack create には smolvm.exe の隣に storage-template.ext4 / overlay-template.ext4 が必要です（Windows にはホストの mkfs.ext4 がありません）。

GPU アクセラレーション

smolvm は virtio-gpu / Venus（Vulkan-over-virtio）を介してホストGPUをゲストに公開します。ゲストのワークロードは実際の Vulkan デバイスを認識します。Linux + Intel では次のようにレンダリングされます：

ANGLE (Intel, Vulkan 1.4 (Virtio-GPU Venus (Intel(R) UHD Graphics ...)), venus)

ホストの要件

macOS — virglrenderer と MoltenVK は smolvm ディストリビューションに同梱されています。追加インストールは不要です。

Linux — virglrenderer とホストの Vulkan ドライバーをシステムパッケージマネージャーからインストールする必要があります：

virglrenderer はホストGPUドライバースタックの libEGL と libdrm に依存します — これらはハードウェア固有であり、同梱できません。GPU対応のLinuxホストには、GPUドライバー経由で既にインストールされています。

使用方法

# CLI
smolvm machine run --gpu --image alpine -- vulkaninfo --summary

# Smolfile
# gpu = true
# gpu_vram = 2048   # MiB、デフォルト 4096

ゲストの Vulkan ローダーは virtio ICD を指す必要があります：

export VK_ICD_FILENAMES=/usr/share/vulkan/icd.d/virtio_icd.x86_64.json

ヘッドレスブラウザの例

examples/headless-browser/ を参照してください。ANGLE + Venus を使用して、ヘッドレスVM内でハードウェアアクセラレーションされた WebGL を実現する動作する Chromium セットアップがあります。

CUDA API リモーティング

--gpu と --cuda は異なるインターフェースを提供します。--gpu は virtio-gpu / Venus を介して Vulkan を公開します。CUDA は提供しません。--cuda は CUDA API リモーティングを有効にします：ドライバーレスのゲストシムが CUDA 呼び出しを vsock 経由でホストプロセスに転送し、ホストプロセスがホストの NVIDIA ドライバーを通じて実行します。

CUDA リモーティングには、ホストに NVIDIA GPU と動作する NVIDIA ドライバーが必要です。GPU パススルーではありません：ゲストは物理デバイスも NVIDIA ドライバーも受け取りません。

フォークが多い Linux ホストは、アップストリームの KVM 修正 916b7f4 を含むカーネルを使用する必要があります。 影響を受けるカーネルは、ホストメモリが十分にある場合でも、最初の KVM_RUN で断続的に ENOMEM を報告することがあります。smolvm は露出を減らし、失敗したワーカーを置き換えますが、カーネルの更新が決定的な修正です。

VM境界は依然としてワークロードのCPU、メモリ、ファイルシステムを分離します。GPU アクセスはホストプロセスと共有ホストGPUによって仲介されるため、GPU 分離はハードウェアやVM境界ではなくプロセスレベルに留まります。CUDA リモーティングを堅牢化されたマルチテナントGPU分離境界として扱わないでください。

設計、トレードオフ、パススルーとの比較については、GPU access by API remoting: how a driverless microVM runs CUDA を参照してください。

開発

docs/DEVELOPMENT.md を参照してください。

Apache-2.0 · @binsquare 作 · twitter · github