Sandboxed Execution with Shuru

使用 Shuru 实现沙箱执行

Shuru boots an ephemeral Linux microVM (Alpine, ARM64) on macOS. Each

shuru run

gets a fresh disk clone - all changes are discarded on exit. Use it whenever you need to run commands in isolation from the host.

Shuru 可在 macOS 上启动临时 Linux 微虚拟机（Alpine、ARM64 架构）。每次

shuru run

都会获得一个全新的磁盘克隆——所有修改都会在退出时被丢弃。当你需要在与主机隔离的环境中运行命令时都可以使用它。

Core Workflow

核心工作流

The pattern is: run in sandbox, mount to share files, checkpoint to persist state.

bash

undefined

使用模式为：在沙箱中运行，挂载共享文件，创建检查点持久化状态。

bash

undefined

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 -- apk add curl && curl https://example.com

4. If setup is expensive, save a checkpoint and reuse it

shuru checkpoint create node-env --allow-net -- apk add nodejs npm shuru run --from node-env --mount .:/workspace -- node /workspace/app.js

undefined

shuru checkpoint create node-env --allow-net -- apk add nodejs npm shuru run --from node-env --mount .:/workspace -- node /workspace/app.js

undefined

Command Chaining

命令链

Chain commands with

sh -c

when you need multiple steps:

bash

shuru run --allow-net -- sh -c 'apk add python3 py3-pip && python3 -c "print(1+1)"'

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

当需要执行多步操作时，可以通过

sh -c

串联命令：

bash

shuru run --allow-net -- sh -c 'apk add python3 py3-pip && python3 -c "print(1+1)"'

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

Essential Commands

核心命令

Run

运行

bash

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

bash

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

undefined

shuru run --from myenv -- npm test

undefined

Checkpoints

检查点

bash

undefined

bash

undefined

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

List all checkpoints (shows actual disk usage)

shuru checkpoint list

Delete

shuru checkpoint delete <name>


Checkpoint names must be unique - delete the old one before re-creating with the same name.

shuru checkpoint delete <name>


检查点名称必须唯一——在复用相同名称创建前，请先删除旧的检查点。

Other Commands

其他命令

bash

undefined

bash

undefined

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

undefined

shuru prune

undefined

Common Patterns

常见使用场景

Dev Environment Setup

开发环境配置

Create a checkpoint with all dependencies pre-installed, then use it for fast runs:

bash

undefined

提前创建预装所有依赖的检查点，后续可以快速启动运行：

bash

undefined

One-time setup

shuru checkpoint create python-dev --allow-net -- sh -c 'apk add python3 py3-pip && pip install pytest requests'

Fast subsequent runs

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

undefined

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

undefined

Testing Untrusted Code

测试不可信代码

Run untrusted scripts with no network access and no host filesystem access:

bash

undefined

在无网络权限、无主机文件系统访问权限的环境中运行不可信脚本：

bash

undefined

Fully isolated — no --allow-net, no --mount

shuru run -- sh -c 'echo "malicious script here" && rm -rf / 2>/dev/null; echo "host is safe"'

undefined

shuru run -- sh -c 'echo "malicious script here" && rm -rf / 2>/dev/null; echo "host is safe"'

undefined

Build and Test

构建与测试

Mount source, build inside the VM, results appear on host via the mount:

bash

shuru run --mount .:/workspace --cpus 4 --memory 4096 -- sh -c '
  cd /workspace
  apk add build-base
  make -j4
  make test
'

挂载源码目录，在虚拟机内部构建，构建结果会通过挂载目录同步到主机：

bash

shuru run --mount .:/workspace --cpus 4 --memory 4096 -- sh -c '
  cd /workspace
  apk add build-base
  make -j4
  make test
'

Port Forwarding for Web Servers

Web 服务器端口转发

bash

shuru run --allow-net --from node-env -p 3000:3000 --mount .:/app -- sh -c '
  cd /app && node server.js
'

bash

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

undefined

undefined

Stacking Checkpoints

检查点堆叠

Build environments incrementally:

bash

shuru checkpoint create base --allow-net -- apk add build-base git curl
shuru checkpoint create node --from base --allow-net -- sh -c 'apk add nodejs npm'
shuru checkpoint create project --from node --allow-net --mount .:/app -- sh -c 'cd /app && npm install'

增量构建环境：

bash

shuru checkpoint create base --allow-net -- apk add build-base git curl
shuru checkpoint create node --from base --allow-net -- sh -c 'apk add 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'

undefined

shuru run --from project --mount .:/app -- sh -c 'cd /app && npm test'

undefined

Project Config (shuru.json)

项目配置（shuru.json）

Place

shuru.json

in the project root to avoid repeating flags:

json

{
  "cpus": 2,
  "memory": 2048,
  "disk_size": 4096,
  "allow_net": false,
  "ports": ["8080:80"],
  "mounts": ["./src:/workspace"],
  "command": ["/bin/sh", "-c", "cd /workspace && sh"]
}

CLI flags override config values. See references/config.md for all fields.

在项目根目录下放置

shuru.json

可避免重复输入参数：

json

{
  "cpus": 2,
  "memory": 2048,
  "disk_size": 4096,
  "allow_net": false,
  "ports": ["8080:80"],
  "mounts": ["./src:/workspace"],
  "command": ["/bin/sh", "-c", "cd /workspace && sh"]
}

CLI 参数优先级高于配置文件。所有配置字段可参考 references/config.md。

Important Constraints

重要约束

Networking is off by default. You must pass
```
--allow-net
```
to install packages or make HTTP requests.
The guest is Alpine Linux (aarch64). Use
```
apk add
```
for packages, not apt or yum.
Ephemeral by default. Everything is discarded on exit unless you checkpoint.
Mounts are read-write. Changes to mounted directories are visible on the host immediately.
macOS only (Apple Silicon). Uses Apple Virtualization.framework.
Default resources: 2 CPUs, 2048 MB RAM, 4096 MB disk. Override with
```
--cpus
```
,
```
--memory
```
,
```
--disk-size
```
.

网络默认关闭。你必须传入
```
--allow-net
```
参数才能安装软件包或发起 HTTP 请求。
虚拟机系统为 Alpine Linux（aarch64 架构）。使用
```
apk add
```
安装软件包，不要用 apt 或 yum。
默认临时环境。除非你创建检查点，否则所有修改都会在退出时被丢弃。
挂载目录默认可读写。对挂载目录的修改会立刻同步到主机。
仅支持 macOS（Apple 芯片）。基于 Apple Virtualization.framework 实现。
默认资源配置：2 核 CPU，2048 MB 内存，4096 MB 磁盘。可通过
```
--cpus
```
、
```
--memory
```
、
```
--disk-size
```
参数覆盖。

Deep-Dive Documentation

深入文档

references/checkpoints.md — checkpoint lifecycle, stacking, disk usage
references/config.md — shuru.json fields and resolution order
references/networking.md — allow-net, port forwarding, proxy behavior

references/checkpoints.md —— 检查点生命周期、堆叠、磁盘占用说明
references/config.md —— shuru.json 字段与配置优先级说明
references/networking.md —— allow-net、端口转发、代理行为说明

shuru

Original

Translation

Sandboxed Execution with Shuru

使用 Shuru 实现沙箱执行

Core Workflow

核心工作流

1. Run a command in a fresh VM

1. Run a command in a fresh VM

2. Mount the project directory so the VM can access host files

2. Mount the project directory so the VM can access host files

3. If the command needs network access (install packages, fetch data)

3. If the command needs network access (install packages, fetch data)

4. If setup is expensive, save a checkpoint and reuse it

4. If setup is expensive, save a checkpoint and reuse it

Command Chaining

命令链

Essential Commands

核心命令

Run

运行

Interactive shell (default when no command given)

Interactive shell (default when no command given)

Run a single command

Run a single command

With resources

With resources

With networking + port forwarding

With networking + port forwarding

Multiple mounts

Multiple mounts

From a checkpoint

From a checkpoint

Checkpoints

检查点

Create: boots VM, runs command, saves disk on exit

Create: boots VM, runs command, saves disk on exit

Stack: create from an existing checkpoint

Stack: create from an existing checkpoint

List all checkpoints (shows actual disk usage)

List all checkpoints (shows actual disk usage)

Delete

Delete

Other Commands

其他命令

Download/update OS image

Download/update OS image

Upgrade CLI + OS image

Upgrade CLI + OS image

Clean up leftover data from crashed VMs

Clean up leftover data from crashed VMs

Common Patterns

常见使用场景

Dev Environment Setup

开发环境配置

One-time setup

One-time setup

Fast subsequent runs

Fast subsequent runs

Testing Untrusted Code

测试不可信代码

Fully isolated — no --allow-net, no --mount

Fully isolated — no --allow-net, no --mount

Build and Test

构建与测试

Port Forwarding for Web Servers

Web 服务器端口转发

Access at http://localhost:3000 on the host

Access at http://localhost:3000 on the host

Stacking Checkpoints

检查点堆叠

Now "project" has OS deps + Node + node_modules baked in

Now "project" has OS deps + Node + node_modules baked in

Project Config (shuru.json)

项目配置（shuru.json）

Important Constraints

重要约束

Deep-Dive Documentation

深入文档