> [!NOTE] > 本文档由 WeHub 基于上游 README 翻译整理，属于社区翻译，非官方中文文档。 > [English](./README.en.md) · [原始项目](https://github.com/smol-machines/smolvm) · [上游 README](https://github.com/smol-machines/smolvm/blob/HEAD/README.md) > 原作者、版权与许可证归属以原始项目及本仓库 LICENSE 文件为准。

smol machines

Discord Release License

smolvm ====== 默认以隔离方式交付并运行软件。 这是一款 CLI 工具，可让你： 1. 在本地管理与运行自定义 Linux 虚拟机，具备：亚秒级冷启动、跨平台（macOS、Linux、Windows）、弹性内存占用。 2. 将有状态的虚拟机打包为单个文件（.smolmachine），以便在任何受支持的平台上重新恢复运行。 安装 ------- ```bash # 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](https://github.com/smol-machines/smolvm/releases), 下载，并将其放入 `~/.local/share/`。 **Windows：** 下载 `windows-x86_64` 版本（捆绑 `krun.dll` + `libkrunfw.dll`），解压后运行 `smolvm.exe`。需要启用 [Windows Hypervisor Platform](https://learn.microsoft.com/en-us/virtualization/api/)（WHP）功能。 快速开始 ----------- ```bash # 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）边界隔开。 ```bash # 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。 ```bash 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 只负责启动结果。 ```bash # 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 ``` **用于开发的持久化机器** — 创建、停止、启动。已安装的软件包在重启后仍然保留。 ```bash 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` 检查）。 ```bash 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 配置。 ```toml 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 ``` ```bash smolvm machine create --name myvm -s Smolfile smolvm machine start --name myvm ``` 更多示例：[python](https://github.com/smol-machines/smolvm/tree/main/examples/python-app) · [node](https://github.com/smol-machines/smolvm/tree/main/examples/node-app) · [doom](https://github.com/smol-machines/smolvm/tree/main/examples/doom-web) 工作原理 ------------ 每个工作负载在硬件虚拟化 VM 中运行，拥有独立的客户机内核，底层为 [Hypervisor.framework](https://developer.apple.com/documentation/hypervisor)（macOS）、KVM（Linux）或 [Windows Hypervisor Platform](https://learn.microsoft.com/en-us/virtualization/api/)（Windows）。[libkrun](https://github.com/containers/libkrun) 充当 VMM，[libkrunfw](https://github.com/smol-machines/libkrunfw) 提供客户机内核。将其打包为 `.smolmachine` 后，只要宿主机架构匹配即可零依赖运行。 镜像采用 [OCI](https://opencontainers.org/) 格式 — 与 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 加速](#gpu-acceleration)）。 * 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 驱动安装它们。 ### 用法 ```bash # CLI smolvm machine run --gpu --image alpine -- vulkaninfo --summary # Smolfile # gpu = true # gpu_vram = 2048 # MiB, default 4096 ``` 客户机 Vulkan loader 必须指向 virtio ICD： ```bash export VK_ICD_FILENAMES=/usr/share/vulkan/icd.d/virtio_icd.x86_64.json ``` ### 无头浏览器示例 参见 [`examples/headless-browser/`](examples/headless-browser/)，了解使用 ANGLE + Venus 在无头 VM 内实现硬件加速 WebGL 的可用 Chromium 配置。 开发 ----------- 参见 [docs/DEVELOPMENT.md](docs/DEVELOPMENT.md)。 [Apache-2.0](LICENSE) · made by [@binsquare](https://github.com/BinSquare) · [twitter](https://x.com/binsquares) · [github](https://github.com/smol-machines/smolvm)