项目文件夹

# install (macOS + Linux)
curl -sSL https://smolmachines.com/install.sh | bash

# for coding agents — install + discover all commands
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）功能。

快速开始

# run a command in an ephemeral VM (cleaned up after exit)
smolvm machine run --net --image alpine -- sh -c "echo 'Hello world from a microVM' && uname -a"

# interactive shell
smolvm machine run --net -it --image alpine -- /bin/sh
# inside the VM: apk add sl && sl && exit

适用场景

沙箱隔离不可信代码 — 在硬件隔离的 VM 中运行不可信程序。宿主机文件系统、网络与凭据由虚拟机管理程序（hypervisor）边界隔开。

# network is off by default — untrusted code can't phone home
smolvm machine run --image alpine -- nslookup example.com
# fails — no network access

# lock down egress — only allow specific hosts
smolvm machine run --net --image alpine --allow-host registry.npmjs.org -- wget -q -O /dev/null https://registry.npmjs.org
# works — allowed host

smolvm machine run --net --image alpine --allow-host registry.npmjs.org -- wget -q -O /dev/null https://google.com
# fails — not in allow list

打包为便携式可执行文件 — 将任何工作负载转为自包含二进制文件。所有依赖均已预置 — 无需安装步骤、无需运行时下载，启动时间 <200ms。

smolvm pack create --image python:3.12-alpine -o ./python312
./python312 run -- python3 --version
# Python 3.12.x — isolated, no pyenv/venv/conda needed

使用本地容器镜像 — 适用于 CI、离线（air-gapped）主机与快速迭代。向 --image 提供 docker save / podman save 归档，通过 stdin 管道传入，或指向已解压的 rootfs 目录。镜像相关工作交由你的容器工具链处理；smolvm 只负责启动结果。

# build locally, run in the VM with no push/pull
docker build -t myapp .
docker save myapp | smolvm machine run --image - -- ./app

# from an archive file (boots with no network)
smolvm machine run --image ./myapp.tar -- ./app

# from an already-unpacked rootfs directory
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
# inside: sl, ls, uname -a — type 'exit' to leave
smolvm machine stop --name myvm

使用 git 与 SSH，而无需将私钥复制到客户机。 将宿主机 SSH agent 转发到 VM。在 socket 可用期间，客户机可请求 agent 使用任意已转发的密钥进行签名，因此仅向你信任的工作负载转发。要求宿主机上运行 SSH agent（可用 ssh-add -l 检查）。

smolvm machine run --ssh-agent --net --image alpine -- sh -c "apk add -q openssh-client && ssh-add -l"
# lists your host keys; private key material remains in the host agent

smolvm machine exec --name myvm -- git clone git@github.com:org/private-repo.git

用 Smolfile 声明环境 — 以简单的 TOML 文件实现可复现的 VM 配置。

image = "python:3.12-alpine"
net = true

[network]
allow_hosts = ["api.stripe.com", "db.example.com"]

[dev]
init = ["pip install -r requirements.txt"]
volumes = ["./src:/app"]

[auth]
ssh_agent = true

smolvm machine create --name myvm -s Smolfile
smolvm machine start --name myvm

更多示例：python · node · doom

工作原理

每个工作负载在硬件虚拟化 VM 中运行，拥有独立的客户机内核，底层为 Hypervisor.framework（macOS）、KVM（Linux）或 Windows Hypervisor Platform（Windows）。libkrun 充当 VMM，libkrunfw 提供客户机内核。将其打包为 .smolmachine 后，只要宿主机架构匹配即可零依赖运行。

镜像采用 OCI 格式 — 与 Docker 使用的同一开放标准。Docker Hub、ghcr.io 或其他 OCI registry 上的任意镜像均可拉取并以 microVM 形式启动。无需 Docker daemon。

默认：4 个 vCPU、8 GiB RAM。内存通过 virtio balloon 实现弹性 — 宿主机仅提交客户机实际占用的部分，其余自动回收。空闲时 vCPU 线程在 hypervisor 中休眠，因此过度分配几乎无成本。可用 --cpus 与 --mem 覆盖。

安全模型

smolvm 为每个工作负载分配独立的 VM 与客户机内核，从而强化客户机/宿主机边界。它本身并非经过加固的多用户控制平面：

smolvm CLI 与 VMM 进程以调用宿主机用户的权限运行。该用户账户、宿主机操作系统、hypervisor 后端、libkrun 与 smolvm 均属于可信计算基（TCB）。
通过 --volume 传入的宿主机目录会按请求的访问权限有意暴露给客户机。请勿将机密或敏感路径挂载到不可信工作负载。
--ssh-agent 不会将私钥材料复制到客户机，但会授予客户机访问已转发 agent socket 的权限，因而在 VM 运行期间可请求签名。
默认禁用网络。启用 --net、端口转发或宿主机服务会扩大工作负载的可达攻击面。
在独立本地使用时，smolvm 的状态与控制端点限定于调用用户的环境。若存在敌意的本地共租户，应在 VMM 进程外围增加宿主机级账户隔离与操作系统级限制。本节不描述独立的 smolmachines 云控制平面及其租户隔离保证。
发布包提供 SHA-256 校验和，在校验文件可用时，安装程序会拒绝不匹配的安装包。当前发布版本未经签名，也未附带来源证明（provenance attestation），且在校验文件无法下载时安装程序仍允许安装。

将客户机中的 root 视为不可信。VM 边界限制其对宿主机的直接访问，而每一项显式转发的能力（包括挂载、网络访问、端口与 SSH agent 访问）都会成为工作负载权限的一部分。

对比

	smolvm	Containers	Colima	QEMU	Firecracker	Kata
工作负载边界	VM + guest kernel	Namespace + shared kernel	Namespace inside shared VM	VM + guest kernel	VM + guest kernel	VM per container
启动时间	<200ms	~100ms	~seconds	~15-30s	<125ms	~500ms
架构	Library (libkrun)	Daemon	Daemon (in VM)	Process	Process	Runtime stack
每工作负载独立 VM	Yes	No	No (shared)	Yes	Yes	Yes
macOS 原生支持	Yes	Via Docker VM	Yes (krunkit)	Yes	No	No
可嵌入 SDK	Yes	No	No	No	No	No
便携式制品	`.smolmachine`	Images (need daemon)	No	No	No	No

平台支持

主机	客户机	要求
macOS Apple Silicon	arm64 Linux	macOS 11+
macOS Intel	x86_64 Linux	macOS 11+（未经测试）
Linux x86_64	x86_64 Linux	KVM（`/dev/kvm`）
Linux aarch64	aarch64 Linux	KVM（`/dev/kvm`）
Windows x86_64	x86_64 Linux	已启用 Windows Hypervisor Platform（WHP）

已知限制

网络为可选启用（在 machine create 上使用 --net）。仅支持 TCP/UDP，不支持 ICMP。
卷挂载：仅支持目录（不支持单个文件）。挂载到 /workspace（-v /host/dir:/workspace）优先于默认 storage-disk 工作区——将改用你的主机目录。
macOS：二进制文件必须使用 Hypervisor.framework 权限进行签名。
--ssh-agent 要求主机上运行 SSH agent（必须设置 SSH_AUTH_SOCK）。
GPU 加速需要 libkrun 使用 GPU=1 构建，且主机上需安装 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 驱动：

发行版	软件包
Alpine	`apk add virglrenderer mesa-vulkan-intel`（AMD 可使用 `mesa-vulkan-ati`）
Debian/Ubuntu	`apt install virglrenderer0 mesa-vulkan-drivers`

virglrenderer 依赖主机 GPU 驱动栈中的 libEGL 与 libdrm——这些与硬件相关，无法捆绑。任何具备 GPU 能力的 Linux 主机都会通过其 GPU 驱动安装它们。

用法

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

# Smolfile
# gpu = true
# gpu_vram = 2048   # MiB, default 4096

客户机 Vulkan loader 必须指向 virtio ICD：

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

无头浏览器示例

参见 examples/headless-browser/，了解使用 ANGLE + Venus 在无头 VM 内实现硬件加速 WebGL 的可用 Chromium 配置。

开发

参见 docs/DEVELOPMENT.md。

Apache-2.0 · made by @binsquare · twitter · github