Microsandbox：本地 microVM 沙箱运行时

Microsandbox 用于在快速启动的本地 microVM 中运行不可信工作负载，覆盖 AI 代理、用户代码、插件、CI 任务、隔离开发环境、爬虫与自动化脚本等场景。

核心特性

• 硬件级隔离：基于 microVM 技术提供强隔离。
• 跨平台支持：可在 Linux、macOS 与 Windows 上运行。
• OCI 兼容：直接拉取 Docker Hub、GHCR 或任意 OCI 注册表的标准镜像。
• 类 Docker 工作流：复用熟悉的 image、command、shell、volume 模型。
• 极速启动：平均启动时间低于 100 毫秒。
• 可嵌入式调用：在应用进程内直接派生 VM，无需搭建服务器或长驻守护进程。
• 不可泄露的密钥：密钥仅在宿主机侧注入，VM 内部无法获取明文。
• 常驻与分离模式：支持 detached 模式运行长时间会话。
• 面向代理：提供 Agent Skills 与 MCP Server，便于 AI 代理自主创建沙箱。

环境要求

• macOS：Apple Silicon。
• Linux：需启用 KVM。
• Windows：Windows 10 及以上（x64 或 ARM64），需启用 WHP。

项目仍处于 Beta 阶段，接口可能发生破坏性变更。

SDK 安装

cargo add microsandbox                                   # Rust
uv add microsandbox                                      # Python
npm i microsandbox                                       # TypeScript
go get github.com/superradcompany/microsandbox/sdk/go    # Go

基本用法：在沙箱中执行代码

use microsandbox::Sandbox;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let sandbox = Sandbox::builder("my-sandbox")
        .image("python")
        .cpus(1)
        .memory(512)
        .create()
        .await?;

    let output = sandbox
        .exec("python", ["-c", "print('Hello from a microVM!')"])
        .await?;

    println!("{}", output.stdout()?);

    sandbox.stop().await?;

    Ok(())
}

Python、Ruby、TypeScript、Go 版本保持相同调用范式：Sandbox.create() 拉取并启动 VM，exec() 在内部执行命令，stop() 关闭沙箱。Ruby 示例额外展示了通过 network.allowed_hosts 与 secrets 配置出口白名单与受保护密钥。

首次调用会拉取镜像并写入本地缓存，后续启动复用缓存以保证毫秒级响应。

CLI 用法

CLI 提供 msb 命令，涵盖沙箱生命周期、镜像与卷管理。

npx microsandbox run debian          # 临时运行 debian 沙箱
msb run python -- python3 -c "print('Hello from a microVM!')"

安装与生命周期

msb create --name app python         # 创建具名沙箱
msb exec app -- python -c "import this"
msb stop app
msb start app
msb rm app

镜像与配置

msb pull python
msb image ls
msb image rm python

可通过 YAML 配置文件声明网络白名单与启动脚本：

# sandbox.yaml
image: python:3.12
network:
  allow:
    - api.github.com
scripts:
  octocat: |
    python - <<'PY'
    import urllib.request
    ...
    PY

执行：msb run --conf sandbox.yaml -- octocat。

安装沙箱为系统命令

msb install ubuntu
ubuntu                               # 像打开本地终端一样进入 ubuntu 沙箱
msb uninstall ubuntu

状态查看

msb ls
msb ps app
msb inspect app
msb metrics app                      # 实时 CPU/内存/网络指标

辅助命令：msb --help 查看速查菜单，msb --tree 输出完整命令树。

典型应用场景

• 在沙箱中运行 Docker，避免污染宿主机守护进程。
• 为编码代理提供隔离的项目工作空间。
• 运行 Playwright 无头浏览器任务。
• 通过快照预热工具链，快速派生干净 Worker。
• 在隔离环境中演练数据库迁移后回滚基线。
• 将自托管 GitHub Actions Runner 的每个任务放入临时 microVM。
• 使用 LibreOffice 在离线 Worker 中转换不可信文档为 PDF。

AI 代理集成

• Agent Skills：通过 npx skills add superradcompany/skills 为 Claude Code、Cursor、Codex、Gemini CLI、GitHub Copilot 等代理注入 microsandbox 使用能力。
• MCP Server：提供沙箱生命周期、命令执行、文件系统、卷管理与监控的结构化工具调用。

claude mcp add --transport stdio microsandbox -- npx -y microsandbox-mcp

文档与许可

完整指南、API 参考与更多示例见官方文档站点。本项目基于 Apache License 2.0 开源。