shuru

macOS 上专为 AI Agent 设计的本地优先（Local-first）microVM 沙箱。

Shuru 使用 Apple 的 Virtualization.framework 启动轻量级 Linux 虚拟机。每个沙箱都是瞬态的：根文件系统（rootfs）在每次运行时都会重置，为 Agent 提供一个可丢弃的环境来执行代码、安装软件包和运行工具，而无需触及宿主机。

系统要求

• macOS 14 (Sonoma) 或更高版本，且须为 Apple Silicon 芯片

安装

brew tap superhq-ai/tap && brew install shuru

或者使用安装脚本：

curl -fsSL https://raw.githubusercontent.com/superhq-ai/shuru/main/install.sh | sh

使用方法

# 交互式 shell
shuru run

# 运行特定命令
shuru run -- echo hello

# 允许网络访问
shuru run --allow-net

# 限制特定主机访问
shuru run --allow-net --allow-host api.openai.com --allow-host registry.npmjs.org

# 自定义资源限制
shuru run --cpus 4 --memory 4096 --disk-size 8192 -- make -j4

目录挂载

通过 VirtioFS 将宿主机目录共享到虚拟机中。默认情况下，宿主机目录为只读；访客机的写入操作会进入 tmpfs 覆盖层（VM 退出时会被丢弃）。添加 :rw 后缀可设置为读写挂载——访客机的写入将直接作用于宿主机文件系统。

# 挂载目录（访客机可读取，写入操作进入覆盖层——宿主机保持不变）
shuru run --mount ./src:/workspace -- touch /workspace/test.txt
ls ./src/test.txt   # 未找到 —— 写入内容保留在覆盖层中

# 读写挂载（访客机写入直接作用于宿主机，需要 --allow-host-writes）
shuru run --allow-host-writes --mount ./src:/workspace:rw -- touch /workspace/test.txt
ls ./src/test.txt   # 已找到 —— 写入已同步至宿主机

# 多目录挂载
shuru run --mount ./src:/workspace --mount ./data:/data -- sh

挂载配置也可以在 shuru.json 中设置（详见 配置文件）。

注意： 目录挂载功能需要 v0.1.11+ 版本创建的检查点（Checkpoint）。现有的检查点对其他功能均可正常工作。运行 shuru upgrade 以获取最新版本。

端口转发

通过 vsock 将宿主机端口转发到访客机端口。无需 --allow-net 即可工作——访客机无需网络设备。

# 在检查点中安装 python3，然后通过端口转发提供服务
shuru checkpoint create py --allow-net -- apt-get install -y python3
shuru run --from py -p 8080:8000 -- python3 -m http.server 8000

# 在宿主机（另一个终端）中访问
curl http://127.0.0.1:8080/

# 多端口转发
shuru run -p 8080:80 -p 8443:443 -- nginx

端口转发也可以在 shuru.json 中设置（详见 配置文件）。

检查点 (Checkpoints)

检查点保存磁盘状态，以便在多次运行中复用环境。

# 设置环境并保存
shuru checkpoint create myenv --allow-net -- sh -c 'apt-get install -y python3 gcc'

# 从检查点运行（瞬态模式 -- 更改会被丢弃）
shuru run --from myenv -- python3 script.py

# 基于现有检查点创建分支
shuru checkpoint create myenv2 --from myenv --allow-net -- sh -c 'pip install numpy'

# 列出和删除
shuru checkpoint list
shuru checkpoint delete myenv

密钥 (Secrets)

Secrets 将 API 密钥保留在宿主机上。访客机仅会接收到一个随机占位符令牌；代理服务器仅在向指定主机发起 HTTPS 请求时才替换为真实值。真实的密钥绝不会进入虚拟机内部。

# 通过 CLI 注入密钥
shuru run --allow-net --secret API_KEY=OPENAI_API_KEY@api.openai.com -- curl https://api.openai.com/v1/models

# 多密钥注入
shuru run --allow-net \
  --secret API_KEY=OPENAI_API_KEY@api.openai.com \
  --secret GH_TOKEN=GITHUB_TOKEN@api.github.com \
  -- sh

格式：NAME=ENV_VAR@host1,host2 —— NAME 是访客机看到的环境变量名，ENV_VAR 是宿主机中存储真实值的环境变量名，host 列表是代理进行替换的目标主机。

密钥也可以在 shuru.json 中设置（详见 配置文件）。

配置文件

Shuru 会自动加载当前目录下的 shuru.json（或通过 --config PATH 指定）。所有字段均为可选；CLI 标志的优先级高于配置文件。

{
  "cpus": 4,
  "memory": 4096,
  "disk_size": 8192,
  "allow_net": true,
  "ports": ["8080:80"],
  "mounts": ["./src:/workspace", "./data:/data"],
  "command": ["python", "script.py"],
  "secrets": {
    "API_KEY": {
      "from": "OPENAI_API_KEY",
      "hosts": ["api.openai.com"]
    }
  },
  "network": {
    "allow": ["api.openai.com", "registry.npmjs.org"]
  }
}

network.allow 列表用于限制访客机可访问的主机。如果省略，则默认允许访问所有主机。

SDK

您可以通过 TypeScript 使用 @superhq/shuru 包以编程方式调用 Shuru。

bun add @superhq/shuru

import { Sandbox } from "@superhq/shuru";

const sb = await Sandbox.start({ from: "python-env" });

const result = await sb.exec("python3 -c 'print(1+1)'");
console.log(result.stdout); // "2\n"

await sb.checkpoint("after-run"); // 保存磁盘状态并停止 VM

完整的 API 文档请参阅 SDK README。

Agent Skill

Shuru 作为一个 Agent Skill 提供。