shuru

使用 Shuru 进行沙盒执行

Shuru 会在 macOS 上启动一个临时 Linux 微型虚拟机（Debian，ARM64），并实验性支持 Linux ARM64 主机。每次运行 shuru run 都会创建一个全新的磁盘克隆，退出时会丢弃所有更改。需要与主机隔离地运行命令时，请使用它。

核心工作流

其模式是：在沙盒中运行，挂载以共享文件，创建检查点以持久化状态，使用配方获得现成环境。

# 1. Run a command in a fresh VM
shuru run -- echo "hello from the sandbox"

# 2. Mount the project directory so the VM can access host files
shuru run --mount ./src:/workspace -- ls /workspace

# 3. If the command needs network access (install packages, fetch data)
shuru run --allow-net -- sh -c 'apt-get install -y curl && curl https://example.com'

# 4. If setup is expensive, save a checkpoint and reuse it
shuru checkpoint create node-env --allow-net -- apt-get install -y nodejs npm
shuru run --from node-env --mount .:/workspace -- node /workspace/app.js

# 5. For Docker or a browser, use a recipe from the official catalog
shuru run --recipe docker -- docker run --rm hello-world
shuru run --recipe browser -p 9222:9222 -- sleep infinity

命令串联

需要执行多个步骤时，使用 sh -c 串联命令：

shuru run --allow-net -- sh -c 'apt-get install -y python3 python3-pip && python3 -c "print(1+1)"'

shuru run --mount .:/workspace -- sh -c 'cd /workspace && ls -la && cat README.md'

基本命令

运行

shuru run [flags] [-- command...]

# Interactive shell (default when no command given)
shuru run

# Run a single command
shuru run -- whoami

# With resources
shuru run --cpus 4 --memory 4096 --disk-size 8192 -- make -j4

# With networking + port forwarding
shuru run --allow-net -p 8080:80 -- nginx -g 'daemon off;'

# Multiple mounts
shuru run --mount ./src:/src --mount ./data:/data -- ls /src /data

# From a checkpoint
shuru run --from myenv -- npm test

# From a recipe: builds the checkpoint on first use, reuses it after
shuru run --recipe docker -- docker ps

检查点

# Create: boots VM, runs command, saves disk on exit
shuru checkpoint create <name> [flags] [-- command...]

# Stack: create from an existing checkpoint
shuru checkpoint create with-deps --from base-env --allow-net -- npm install

# Update: rebuild in place; the old checkpoint stays until the new build succeeds
shuru checkpoint update base-env --allow-net -- apt-get install -y build-essential git

# Layer onto the existing checkpoint instead of starting over
shuru checkpoint update base-env --from base-env --allow-net -- apt-get install -y jq

# Build a checkpoint from a recipe
shuru checkpoint create docker --recipe docker

# List all checkpoints (shows actual disk usage and recipe source)
shuru checkpoint list

# Delete
shuru checkpoint delete <name>

create 不会覆盖已有名称。使用 update 替换检查点；它会先以暂存名称构建，只有命令以 0 退出时才会替换原检查点，因此更新失败不会影响原检查点。

配方

配方是对检查点进行版本化描述：包含一个 recipe.json 和 shell 步骤，可从 GitHub 的指定提交获取，也可从本地目录读取。官方目录为 superhq-ai/recipes，目前提供 docker 和 browser。

shuru recipe list                                   # the official catalog
shuru recipe show docker                            # metadata, services and every step, without booting
shuru run --recipe docker -- docker ps              # build on first use, reuse after
shuru checkpoint create docker --recipe docker      # build explicitly under that name
shuru run --recipe docker --checkpoint ci -- ...    # pick the checkpoint name
shuru checkpoint update docker --recipe docker      # force a rebuild at the current revision
shuru run --recipe owner/repo/path@v1 --yes -- ...  # third-party, pinned to a tag
shuru run --recipe ./my-recipe -- ...               # local directory while developing one

编写脚本时需注意以下规则：

• 像 docker 这样的裸名称始终表示官方目录中的配方。本地目录必须写成路径（./dir、../dir、/abs、~/dir）。
• 官方和本地配方无需提示即可构建。第三方 GitHub 配方会要求确认，因此在非交互式运行中请传入 --yes。
• 引用会解析为一个提交 SHA，并记录在检查点旁。配方更改后，下次运行 run --recipe 时会重新构建；配方未更改时，则会在数秒内启动现有检查点。
• 构建使用配方声明的网络允许列表，而非项目的 shuru.json。首次构建 docker 或 browser 需要几分钟。

有关 recipe.json 格式和客户机服务，请参阅 references/recipes.md。

其他命令

# Download/update OS image
shuru init
shuru init --force    # re-download even if up to date

# Upgrade CLI + OS image
shuru upgrade

# Clean up leftover data from crashed VMs
shuru prune

常见模式

开发环境设置

创建一个预装所有依赖项的检查点，然后用它快速运行：

# One-time setup
shuru checkpoint create python-dev --allow-net -- sh -c 'apt-get install -y python3 python3-pip && pip install pytest requests'

# Fast subsequent runs
shuru run --from python-dev --mount .:/workspace -- sh -c 'cd /workspace && pytest'

在虚拟机内使用 Docker

docker 配方会安装 Docker Engine，将 dockerd 作为客户机服务运行，并预先拉取 nginxinc/nginx-unprivileged:1.31.7-alpine-slim。只有在 docker info 返回响应后才会启动命令。

# Build once (a few minutes), then every run boots in seconds
shuru checkpoint create docker --recipe docker

# Serve the pre-pulled image on host port 8080; no --allow-net needed
shuru run --from docker -p 8080:8080 -- \
  docker run --rm -p 8080:8080 nginxinc/nginx-unprivileged:1.31.7-alpine-slim

# Pulling other images needs network
shuru run --from docker --allow-net -- docker run --rm python:3.12-alpine python3 -c 'print(1)'

# Build an image from a mounted project
shuru run --from docker --mount .:/app -- sh -c 'cd /app && docker build -t app . && docker run --rm app'

容器与任何客户机进程享有相同的隔离边界：未指定 --allow-net 时无法访问外网，主机允许列表仍然适用，只有通过 -p 才会开放主机端口。请在虚拟机内保留 Docker 的默认设置；不要使用 --privileged，也不要挂载 Docker 套接字。

无头浏览器（CDP）

browser 配方会以非特权用户身份在虚拟机内运行无头 Chromium，并在端口 9222 上启用 DevTools 协议。转发该端口，并将任意 CDP 客户端（Playwright、Puppeteer、browser-use）指向 http://127.0.0.1:9222。

# Keep the VM alive while a client on the host drives the browser
shuru run --recipe browser -p 9222:9222 -- sleep infinity

# In another terminal
curl -s http://127.0.0.1:9222/json/version

Chromium 始终运行在微型虚拟机内，只有其 CDP 端口能连接到主机。浏览器需要加载真实网站时，请添加 --allow-net；使用 --allow-host 可限制可访问的网站。DevTools HTTP 端点会忽略 HTTP/1.0 请求，因此请使用常规 HTTP/1.1 客户端。

测试不可信代码

运行不可信脚本时，不授予其网络访问权限或主机文件系统访问权限：

# Fully isolated: no --allow-net, no --mount
shuru run -- sh -c 'echo "malicious script here" && rm -rf / 2>/dev/null; echo "host is safe"'

构建和测试

挂载源代码，在虚拟机内构建，结果会通过挂载目录出现在主机上：

shuru run --mount .:/workspace --cpus 4 --memory 4096 -- sh -c '
  cd /workspace
  apt-get install -y build-essential
  make -j4
  make test
'

为 Web 服务器转发端口

shuru run --allow-net --from node-env -p 3000:3000 --mount .:/app -- sh -c '
  cd /app && node server.js
'
# Access at http://localhost:3000 on the host

叠加检查点

逐步构建环境：

shuru checkpoint create base --allow-net -- apt-get install -y build-essential git curl
shuru checkpoint create node --from base --allow-net -- apt-get install -y nodejs npm
shuru checkpoint create project --from node --allow-net --mount .:/app -- sh -c 'cd /app && npm install'
# Now "project" has OS deps + Node + node_modules baked in
shuru run --from project --mount .:/app -- sh -c 'cd /app && npm test'

项目配置（shuru.json）

在项目根目录中放置 shuru.json，避免重复指定标志：

{
  "cpus": 2,
  "memory": 2048,
  "disk_size": 4096,
  "allow_net": true,
  "ports": ["8080:80"],
  "mounts": ["./src:/workspace"],
  "command": ["/bin/sh", "-c", "cd /workspace && sh"],
  "secrets": {
    "API_KEY": {
      "from": "OPENAI_API_KEY",
      "hosts": ["api.openai.com"]
    }
  },
  "network": {
    "allow": ["api.openai.com", "registry.npmjs.org"]
  }
}

CLI 标志会覆盖配置值。配置 secrets 后，客户机会收到占位令牌，代理会在向允许的主机发送 HTTPS 请求时将其替换为真实值。也可以通过 command 生成密钥，并在密钥过期前刷新。有关所有字段，请参阅 references/config.md。

重要限制

• 默认关闭网络。 安装软件包或发送 HTTP 请求时，必须传入 --allow-net。使用 -p 进行端口转发无需此选项。
• 虚拟机使用 Debian Linux（aarch64）。 使用 apt-get install 安装软件包。
• 默认情况下，环境是临时的。 退出时会丢弃所有内容，除非创建检查点。
• 默认情况下，挂载为只读。 虚拟机中的写入会保存到 tmpfs 覆盖层，并在退出时丢弃。使用 :rw 后缀和 --allow-host-writes 可写入主机。
• 虚拟机中没有 systemd。 长时间运行的守护进程需声明为虚拟机服务（参见 references/recipes.md）；systemctl 不存在。
• 适用于 Apple Silicon macOS，以及带有 /dev/kvm 的实验性 Linux ARM64 主机。
• 默认资源： 2 个 CPU、2048 MB 内存、4096 MB 磁盘。使用 --cpus、--memory、--disk-size 覆盖。

深入文档

• references/checkpoints.md：检查点生命周期、更新、堆叠、磁盘用量
• references/recipes.md：recipe.json 格式、引用、信任、虚拟机服务
• references/config.md：shuru.json 字段和解析顺序
• references/networking.md：allow-net、端口转发、代理行为