# shuru: a local-first microVM sandbox for AI agents on macOS

> Shuru boots disposable Linux microVMs on Apple Silicon, with an experimental KVM backend for Linux ARM64. It is aimed at developers who want agent code execution isolated from the host, and the macOS path is the one that is ready.

**superhq-ai/shuru** — A local-first microVM sandbox for running AI agents safely on macOS & Linux

- Repository: https://github.com/superhq-ai/shuru
- Website: http://shuru.run/
- Stars: 860 · Forks: 30
- Language: Rust
- License: Apache-2.0
- Published: 2026-09-10 · Updated: 2026-09-10 · Language: en
- Canonical page: https://hysenlabs.com/projects/superhq-ai-shuru

## What shuru isolates, and who needs that

An agent that can run shell commands can also delete your files, read your SSH keys and install whatever it likes. Shuru's answer is to put that execution inside a lightweight Linux VM that boots per run and resets its rootfs every time. The README describes the sandbox as "ephemeral": the agent gets a disposable environment to execute code, install packages and run tools without touching the host. The audience is narrow but real: developers running coding agents or tool-using agents on a Mac who want the agent to have a real Linux userspace (apt, gcc, python3, npm) rather than a container or a chroot. Requirements are macOS 14 (Sonoma) or later on Apple Silicon, or Linux ARM64 with KVM access at /dev/kvm for experimental testing only. If you are on Intel macOS or on x86 Linux, the README gives you no supported path.

## Apple Virtualization.framework on macOS, KVM on Linux ARM64

The workspace layout shows how the platform split is handled. Cargo.toml lists shuru-darwin and shuru-linux as members but excludes them from default-members, with the comment that they are pulled in transitively through shuru-vm's cfg'd dependencies so that cargo check does not fail on the wrong OS. Around them sit shuru-cli, shuru-proto, shuru-proxy, shuru-sdk, shuru-vm, shuru-store and shuru-guest. The guest side is a Rust init binary cross-compiled to aarch64-unknown-linux-musl, which the justfile builds with cargo build -p shuru-guest --target aarch64-unknown-linux-musl --release. On macOS the VM runs on Apple's Virtualization.framework, which is why the CLI binary has to be codesigned with the virtualization entitlement before it will work; the justfile's install recipe does exactly that. Data flow for mounts goes through VirtioFS, and port forwarding goes over vsock, which the README notes works without --allow-net because the guest needs no network device. Secrets do not enter the VM at all: the guest sees a random placeholder token and a proxy substitutes the real value only on HTTPS requests to the hosts you named.

## Installing shuru with Homebrew and running a first sandboxed command

The README gives two install routes. Homebrew is macOS-only and is the one to prefer there. The install script additionally covers experimental Linux ARM64, and Linux users can also pull the linux-aarch64 release tarball from GitHub Releases by hand.

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

After that, a first command is a single invocation. Everything after the double dash runs inside the guest, and the guest cannot reach the network unless you ask for it.

```bash
shuru run -- echo hello
```

When the agent needs to fetch packages or call an API, add --allow-net. To keep that reach narrow, repeat --allow-host for each host you want to permit.

```bash
shuru run --allow-net --allow-host api.openai.com --allow-host registry.npmjs.org -- sh
```

Resource ceilings are flags too. The README's example sets 4 CPUs, 4096 MB of memory and an 8192 MB disk before running make with four jobs. Anything you install or write in that VM disappears when it exits.

## Checkpoints, mounts and the read-only default that surprises people

A checkpoint saves disk state so an environment survives across runs. The README's pattern is to create one with network access, install what you need, then run from it repeatedly.

```bash
shuru checkpoint create myenv --allow-net -- sh -c 'apt-get install -y python3 gcc'
shuru run --from myenv -- python3 script.py
```

Checkpoints can also branch: shuru checkpoint create myenv2 --from myenv --allow-net -- sh -c 'pip install numpy' builds on an existing one. Directory mounts are where the design gets opinionated. A mount without a suffix is read-only from the host's point of view, and guest writes land in a tmpfs overlay that is discarded when the VM exits. The README demonstrates this with a touch inside /workspace followed by an ls on the host that finds nothing. To let guest writes reach the host you need both the :rw suffix and --allow-host-writes. That two-key requirement is deliberate, and it is the part most likely to trip up someone who expects a normal bind mount. There is also a version constraint the README flags: directory mounts require checkpoints created on v0.1.11 or later, so older checkpoints need shuru upgrade before mounts will work.

## Secrets stay on the host, but the host list is your responsibility

The --secret flag takes the form NAME=ENV_VAR@host1,host2. NAME is the variable the guest sees, ENV_VAR is the host environment variable holding the real value, and the hosts are where the proxy is allowed to substitute it. The README's example injects API_KEY from OPENAI_API_KEY for api.openai.com, and a second example does the same for GITHUB_TOKEN against api.github.com. The substitution happens only on HTTPS requests to those hosts, and per the README the real secret never enters the VM. That is a stronger position than passing keys in as environment variables, because a compromised process inside the guest cannot read what was never there. The limitation is scope: substitution is tied to HTTPS and to the named hosts, so a request to an unlisted host, or a non-HTTPS one, does not get the real value. The same structure can be expressed in shuru.json under a secrets object with from and hosts keys, and CLI flags take precedence over the file.

## Where shuru is the wrong tool

The Linux backend is the clearest boundary. The README carries a warning that Linux builds are available for testing but are not ready for production, and says to expect rough edges, missing polish and compatibility gaps; Homebrew remains macOS-only. If your agents run on Linux servers, that is the wrong backend today. There is a second, quieter limitation: shuru is not a security boundary for hostile multi-tenant workloads. It is a sandbox for agents you already trust to some degree, and the mounts and network flags are the controls. A third constraint is the codesigning requirement on macOS. Building from source means the CLI must be signed with the virtualization entitlement, which the justfile handles via codesign --entitlements shuru.entitlements --force -s - target/debug/shuru. Skip that and the VM will not start. Finally, the README does not document rollback or downgrade behaviour for checkpoints, so treat a checkpoint as forward-only state.

## shuru compared with running agents in Docker

The obvious alternative is a container runtime such as Docker, and the difference is in the isolation boundary rather than the interface. A container shares the host kernel; shuru boots a separate Linux kernel inside a microVM through Virtualization.framework on macOS, so a kernel-level escape is a VM escape rather than a container escape. The cost is startup and the fact that you cannot reuse your existing Dockerfiles directly. Shuru's own answer to that is checkpoints: build the environment once with apt-get and pip, save it, then start from it. The other practical difference is the macOS story. Docker on Apple Silicon runs a Linux VM underneath and your containers inside it; shuru is the VM, and it exposes mount, network and secret controls as first-class CLI flags rather than compose configuration. If your team already has container images and orchestration, shuru is an extra layer, not a replacement. If your problem is specifically "let this agent run on my laptop without touching my home directory", the narrower tool fits better.

## Licence, upgrade cost and the SDK surface

Shuru is Apache-2.0, which permits commercial use, modification and redistribution provided you keep the licence and notice files and state significant changes. That is a permissive licence with an explicit patent grant; it is not legal advice, and if you ship a modified binary you should read the patent termination clause yourself. Upgrading is a single command, shuru upgrade, and the README ties at least one feature to a version floor: mounts need checkpoints created on v0.1.11 or later. Release cadence has been steady, with v0.7.0 on 2026-08-05, v0.6.5 on 2026-07-28 and v0.6.4 on 2026-07-24; the last push to the repository was on 2026-08-05. The changelog is the place to check before upgrading, since the README points at CHANGELOG.md for breaking changes. There is also a TypeScript SDK, @superhq/shuru, installed with bun add @superhq/shuru, which exposes Sandbox.start, sandbox.exec and sandbox.checkpoint. The SDK README under packages/sdk is where the full API lives; the main README only shows the three calls. A skills/ directory and an agentskills.io reference mean the CLI can also be installed as an agent skill via npx skills add superhq-ai/shuru or by copying skills/shuru into .claude/skills/shuru.

## Conclusion

Adopt shuru if you run AI agents on Apple Silicon macOS and want their shell commands, package installs and file writes confined to a VM that resets each run, with the host filesystem reachable only through explicit mounts. Do not adopt it for production Linux workloads: the README labels that backend experimental and says it is not ready for production. Verify first that you are on macOS 14 or later on Apple Silicon, that any checkpoint you reuse was created on v0.1.11 or later if you need directory mounts, and that every secret you inject is bound to a specific host in the --secret hosts list rather than left open.

## FAQ

### What is shuru?

Shuru is a local-first microVM sandbox for AI agents. It boots lightweight Linux VMs so agents can execute code, install packages and run tools in an environment whose rootfs resets on every run.

### How do I use shuru to run a command in a sandbox?

Install it, then pass the command after a double dash, for example shuru run -- echo hello. Add --allow-net for network access, or --allow-net with repeated --allow-host flags to restrict which hosts the guest can reach.

### How do I access or install shuru on macOS?

The README gives two routes: brew tap superhq-ai/tap && brew install shuru, or the install script at https://raw.githubusercontent.com/superhq-ai/shuru/main/install.sh. macOS 14 or later on Apple Silicon is required, and Homebrew remains macOS-only.

## Sources

- [License: Apache-2.0](https://github.com/superhq-ai/shuru/blob/main/LICENSE)
- [Project website](http://shuru.run/)
- [README](https://github.com/superhq-ai/shuru/blob/main/README.md)
- [Releases](https://github.com/superhq-ai/shuru/releases)
- [superhq-ai/shuru on GitHub](https://github.com/superhq-ai/shuru)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/superhq-ai-shuru