A local-first microVM sandbox designed for safely executing AI agents on macOS. It addresses the need for isolated, disposable execution environments, preventing code or tool execution from impacting the host system, thereby enhancing security and reproducibility for AI development workflows.

How It Works

Shuru leverages Apple's Virtualization.framework to boot ephemeral Linux microVMs. Each VM's root filesystem resets upon termination, ensuring a clean slate for every execution. It supports host directory mounting via VirtioFS with guest writes isolated to a temporary overlay, and enables port forwarding over vsock, allowing communication without exposing the VM to the network. Checkpoints allow saving and reusing VM states.

Quick Start & Requirements

• Requirements: macOS 14 (Sonoma) or later, Apple Silicon.
• Install: Via Homebrew (brew tap superhq-ai/tap && brew install shuru) or a curl-based install script (curl -fsSL https://raw.githubusercontent.com/superhq-ai/shuru/main/install.sh | sh).
• Usage: Interactive shell (shuru run), command execution (shuru run -- echo hello), network access (shuru run --allow-net), resource allocation (shuru run --cpus 4 --memory 4096), directory mounts (shuru run --mount ./src:/workspace), and port forwarding (shuru run -p 8080:80).
• Links: Install script: https://raw.githubusercontent.com/superhq-ai/shuru/main/install.sh.

Highlighted Details

• Agent Skill Integration: Designed to be automatically invoked by AI agents (e.g., Claude Code, Cursor, Copilot) when sandboxed execution is required, installable via npx skills add superhq-ai/shuru.
• Ephemeral Environments: Default behavior resets the root filesystem on each run for maximum isolation.
• VirtioFS Mounts: Allows host directories to be mounted read-only into the VM, with guest writes captured in a temporary, discardable overlay.
• Vsock Port Forwarding: Enables host-guest port communication without requiring a network interface within the VM.
• Checkpoints: Facilitates saving and restoring VM states for reproducible environments.

Maintenance & Community

The project relies on GitHub Issues for bug reporting. No specific community channels (like Discord/Slack) or roadmap details are provided in the README.

Licensing & Compatibility

The license type is not explicitly stated in the README. Compatibility is restricted to macOS on Apple Silicon hardware, requiring macOS 14 (Sonoma) or newer.

Limitations & Caveats

The tool is exclusively for macOS and requires Apple Silicon hardware and a recent macOS version (14+). Directory mounting functionality requires specific checkpoint versions (v0.1.11+) and may necessitate running shuru upgrade. The absence of a stated license poses a potential adoption blocker for commercial or derivative works.