shuru

Local-first microVM sandbox for AI agents on macOS.

Shuru boots lightweight Linux VMs using Apple's Virtualization.framework. Each sandbox is ephemeral: the rootfs resets on every run, giving agents a disposable environment to execute code, install packages, and run tools without touching your host.

Requirements

• macOS on Apple Silicon

Install

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

Usage

# Interactive shell
shuru run

# Run a command
shuru run -- echo hello

# With network access
shuru run --allow-net

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

Port forwarding

Forward host ports to guest ports over vsock. Works without --allow-net — the guest needs no network device.

# Install python3 into a checkpoint, then serve with port forwarding
shuru checkpoint create py --allow-net -- apk add python3
shuru run --from py -p 8080:8000 -- python3 -m http.server 8000

# From the host (in another terminal)
curl http://127.0.0.1:8080/

# Multiple ports
shuru run -p 8080:80 -p 8443:443 -- nginx

Port forwards can also be set in shuru.json (see Config file).

Checkpoints

Checkpoints save the disk state so you can reuse an environment across runs.

# Set up an environment and save it
shuru checkpoint create myenv --allow-net -- sh -c 'apk add python3 gcc'

# Run from a checkpoint (ephemeral -- changes are discarded)
shuru run --from myenv -- python3 script.py

# Branch from an existing checkpoint
shuru checkpoint create myenv2 --from myenv --allow-net -- sh -c 'pip install numpy'

# List and delete
shuru checkpoint list
shuru checkpoint delete myenv

Config file

Shuru loads shuru.json from the current directory (or --config PATH). All fields are optional; CLI flags take precedence.

{
  "cpus": 4,
  "memory": 4096,
  "disk_size": 8192,
  "allow_net": true,
  "ports": ["8080:80"],
  "command": ["python", "script.py"]
}

Architecture

┌─────────────────────────────────────────────┐
│  macOS Host                                 │
│                                             │
│  shuru-cli ──► shuru-vm ──► shuru-darwin    │
│                   │      (Virtualization.framework)
│                   │                         │
│         ┌────────┼─────────┐                │
│         │ vsock :1024 exec │                │
│         │ vsock :1025 fwd  │                │
│         └────────┼─────────┘                │
├──────────────────┼──────────────────────────┤
│  Linux Guest     │                          │
│         ┌────────┴─────────┐                │
│         │   shuru-guest    │                │
│         │   (PID 1 init)   │                │
│         └──────────────────┘                │
│  Alpine Linux 3.21 / linux-virt 6.12        │
└─────────────────────────────────────────────┘

Bugs

File issues at github.com/superhq-ai/shuru/issues.