smolvm

面向 AI 智能体的可分支 microVM。 将轻量级虚拟机嵌入你的软件、便携式开发环境和本地沙箱中。

安装

brew install smol-machines/tap/smolvm                  # macOS (Homebrew)
curl -sSL https://smolmachines.com/install.sh | bash   # macOS + Linux

Windows：解压 windows-x86_64 release 并运行 smolvm.exe（需要 Windows Hypervisor Platform）。编码代理：安装后运行 smolvm --help 以了解所有命令。

面向人类和代理的文档位于 docs/，每个任务一个文件夹：一个包含事实的 README.md 和一个代理可以遵循的 SKILL.md，以及其脚本，紧邻每个功能的参考页面。

快速开始

smolvm machine run --net --image alpine -- uname -a          # one-off VM, removed on exit
smolvm machine run --net -it --image alpine -- /bin/sh       # interactive shell

本地

真正的虚拟机，拥有自己的内核，可在你的笔记本电脑或你自己的服务器上免费使用。它们在一秒内启动，内存是弹性的，因此宿主机只提交客户机实际使用的部分。机器在重启后仍然保留，任何 OCI 镜像都可以使用，包括你在本地构建的镜像。

smolvm machine create --net --name dev && smolvm machine start --name dev
smolvm machine exec --name dev -- apk add git
docker save myapp | smolvm machine run --image - -- ./app    # local image, no registry

在 Smolfile 中声明一台机器：将镜像、资源、端口、挂载和网络策略放在一个已检入的文件中。

可嵌入

使用一个 Machine API 从你自己的代码中驱动机器。这些 SDK 在你的进程中运行，无需守护进程，既可在本地运行，也可在 smol cloud 上运行。

npm install smolmachines     # Node / TypeScript
pip install smolmachines     # Python
cargo add smolmachines       # Rust

import { Machine } from 'smolmachines';

const m = await Machine.create({ image: 'python:3.12-alpine', network: true });
const r = await m.exec(['python3', '-c', 'print(2 ** 10)']);
console.log(r.stdout); // 1024
await m.delete();

源码与文档：smol-machines/smol · smolmachines.com/docs/sdk

Branchable

在执行过程中保存正在运行的机器、将其回退，或将其分支为从同一时间点继续运行的多个副本。检查点会捕获 RAM、CPU 状态和磁盘；分支是活动机器的写时复制子级。

smolvm machine create --net --name agent --image alpine
smolvm machine start --name agent --branchable
smolvm machine branch --from agent --name try-1                   # live copy-on-write child
smolvm machine checkpoint --name agent -o agent.checkpoint        # save it, processes and all
smolvm machine create --name agent2 --from agent.checkpoint       # resume later or elsewhere

使用 --from <checkpoint> --at '~N' 回退到更早的世代（参见 machine checkpoint-log），并通过暂停与恢复在不丢失执行状态的情况下停止。在 arm64 Mac 上创建的检查点可在 arm64 Linux 上恢复，参见将运行中的机器从 Mac 迁移到 Linux。更多内容见分支和增量检查点。

可移植

无论你如何配置一台机器，都可以将其打包为单个 .smolmachine 文件。将其推送到任意 OCI 仓库，或将其作为自包含可执行文件运行，无需安装任何东西即可在 200 毫秒内启动。

smolvm machine stop --name dev && smolvm pack create --from-vm dev -o dev
smolvm pack push --file dev.smolmachine ghcr.io/you/dev:v1
smolvm pack create --image python:3.12-alpine -o ./python312
./python312 run -- python3 --version

检查点同样可移植：可在另一台主机或 smol 云上恢复。

安全

每个工作负载都会获得一个硬件隔离的 VM，并拥有自己的内核。网络默认关闭，出站流量可限制为仅允许指定的主机，代码可以使用凭据而无需读取凭据本身。

安全是共同的责任。smolvm 提供边界：每个工作负载都有独立的 VM 和内核，除非你允许，否则任何内容都无法到达宿主机。由你决定什么可以跨越该边界。你挂载的每个文件夹、打开的每个端口、允许的每个主机，以及转发的每个密钥或 SSH agent，都会成为工作负载可以使用的东西，因此对于不受信任的工作负载，只应提供它所需的内容。

smolvm machine run --net --image alpine --allow-host registry.npmjs.org -- wget -qO- https://google.com   # blocked
smolvm machine run --net --image alpine --allow-host-pattern registry.npmjs.org -- wget -qO- https://registry.npmjs.org   # exact host only
NOTION_API_KEY=secret_… smolvm machine run --net --image alpine \
  --credential [email protected] -- sh -c 'echo $NOTION_API_KEY'   # a placeholder

参见凭据替换和安全模型。 使用 --allow-host-pattern '*.example.com' 仅允许子域名；--allow-host example.com 允许顶级域名及其 子域名。smolvm machine update 可添加（--allow-host、--allow-host-pattern、--allow-cidr）和移除 （--remove-allow-host，按添加时的原样指定主机或模式；--remove-allow-cidr）条目，对以允许列表启动的 运行中机器同样适用：授权在下次连接或查询时生效，被移除主机的已学习地址也会随之移除。

工作原理

每个工作负载都在硬件虚拟化的 VM 中运行，拥有自己的客户机内核，基于 Hypervisor.framework（macOS）、KVM（Linux）或 Windows Hypervisor Platform（Windows）。libkrun 是 VMM，libkrunfw 提供客户机内核。镜像使用 OCI 格式，因此 Docker Hub、ghcr.io 或其他注册表上的任何内容都能作为 microVM 启动，无需 Docker 守护进程。

默认值：4 个 vCPU，8 GiB 内存。内存通过 virtio balloon 弹性伸缩，空闲 vCPU 在 hypervisor 中休眠，因此超额配置几乎不产生开销。可通过 --cpus 和 --mem 覆盖。

对比

	smolvm	容器	Colima	QEMU	Firecracker	Kata
工作负载边界	VM + 客户机内核	命名空间 + 共享内核	共享 VM 内的命名空间	VM + 客户机内核	VM + 客户机内核	每容器一个 VM
启动时间	<200ms 至 agent 就绪	~100ms	~数秒	~15-30s	<125ms	~500ms
架构	库（libkrun）	守护进程	守护进程（在 VM 内）	进程	进程	运行时栈
每工作负载 VM	是	否	否（共享）	是	是	是
macOS 原生	是	通过 Docker VM	是（krunkit）	是	否	否
可嵌入 SDK	是	否	否	否	否	否
可移植产物	.smolmachine	镜像（需要守护进程）	否	否	否	否

平台支持

主机	客户机	要求
macOS Apple Silicon	arm64 Linux	macOS 11+
macOS Intel	x86_64 Linux	未发布构建版本；未测试
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）

Windows 支持可移植检查点、暂停/恢复，以及使用 --freeze-source 的分支。GPU 加速仍不可用；参见已知限制。

更多

• Kubernetes：通过 RuntimeClass 将 Pod 作为 microVM 运行。
• GPU 与 CUDA：通过 virtio-gpu / Venus 使用 Vulkan，以及 CUDA API 远程调用。
• 示例：python、node、docker-in-vm、local-llm、headless-browser、doom。
• 开发 · 用户文档位于 smolmachines.com/docs，以 smol-machines/docs 编写（欢迎在那里提交更正；运行时缺陷请留在此处）。