shuru: a local microVM sandbox for AI agents, with a macOS-first stance
A local-first microVM sandbox for running AI agents safely on macOS & Linux
At a glance
- What is it?
- shuru boots ephemeral Linux microVMs so an agent can run code without touching the host. On macOS it rides Apple's Virtualization.framework; on Linux the KVM backend is explicitly labelled experimental. The design choices around mounts, secrets and checkpoints are the interesting part, and so are the limits.
- Who is it for?
- Adopt shuru if you are on Apple Silicon macOS 14 or later and want agent code execution to stay on your machine with a disposable rootfs, host-side secret substitution and read-only mounts by default. Do not adopt it if you need x86_64 Linux, Windows, or a Linux deployment you would call production-ready; the README itself says the Linux builds are not ready for that.
- Can I use it commercially?
- Yes. Apache-2.0 is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 42 days ago.
- What is it written in?
- Mainly Rust, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The problem shuru targets: agent code execution without host contamination
An agent that writes and runs code needs a filesystem it can wreck. Running that code directly on a developer laptop means a stray `rm -rf`, a package install that mutates the global toolchain, or a script that reads an SSH key. Container-based sandboxes solve part of this, but they share the host kernel, and on macOS the container runtime is itself a Linux VM with extra layers on top. shuru takes the other route: one microVM per run, booted through Apple's Virtualization.framework on macOS, with a rootfs that resets every time. The README states the intent plainly: every sandbox is ephemeral, giving agents a disposable environment to execute code, install packages and run tools without touching the host. The audience is narrow and identifiable. It is a developer on Apple Silicon who already runs an agent loop locally and wants the execution step isolated without a cloud round trip. The Linux story is a testing preview, not a second supported platform, and the README says so twice.
How a shuru run actually works: microVM, overlay, proxy
Three mechanisms carry the design. The first is the hypervisor layer. On macOS, shuru uses Virtualization.framework, which means no third-party hypervisor binary and no kernel extension. On Linux ARM64 it uses a KVM backend that requires `/dev/kvm`. The second is the disk model. The rootfs resets on each run, so anything written inside the guest disappears when the VM exits unless you save it as a checkpoint. Directory mounts behave with the same instinct: the README says the host directory is read-only by default and guest writes go to a tmpfs overlay layer that is discarded at exit. Its own example shows the consequence, where `touch /workspace/test.txt` inside the guest leaves no `test.txt` on the host. Making a mount read-write requires appending `:rw` and also passing `--allow-host-writes`, so the two flags are separate gates rather than one. The third is the network path. Secrets do not enter the VM. The guest receives a random placeholder token, and a proxy substitutes the real value only on HTTPS requests to the hosts named in the secret definition. Port forwarding runs over vsock and, per the README, works without `--allow-net` because the guest needs no network device. That is a real architectural distinction: inbound reachability and outbound egress are separate concerns here.
Install paths and the macOS-only Homebrew caveat
The documented install is `brew tap superhq-ai/tap && brew install shuru`. The alternative is the install script, `curl -fsSL https://raw.githubusercontent.com/superhq-ai/shuru/main/install.sh | sh`, which the README says supports macOS on Apple Silicon and experimental Linux ARM64. Linux users who prefer not to pipe a script into a shell can download the `linux-aarch64` release tarball from GitHub Releases. There is a note attached to this that matters more than it looks: Homebrew remains macOS-only, and Linux installs via the script are still experimental. So the two install routes are not equivalent, and a Linux user is on the script or the tarball permanently, at least for now. Requirements are macOS 14 (Sonoma) or later on Apple Silicon, or Linux ARM64 with KVM access. Intel Macs are not in the requirements list, and neither is x86_64 Linux. The README also points at `shuru upgrade` for getting the latest version, which is how it tells users to pick up the checkpoint format change described below.
Checkpoints, and the version constraint hiding in the mounts section
Checkpoints are how shuru reconciles ephemerality with the fact that installing `python3` and `gcc` takes minutes. `shuru checkpoint create myenv --allow-net -- sh -c 'apt-get install -y python3 gcc'` runs a setup command and saves the resulting disk state. A later `shuru run --from myenv -- python3 script.py` starts from that state but stays ephemeral, so changes made during the run are discarded. Checkpoints can also branch: `shuru checkpoint create myenv2 --from myenv --allow-net -- sh -c 'pip install numpy'` layers a new environment on an existing one. `shuru checkpoint list` and `shuru checkpoint delete myenv` handle housekeeping. The constraint worth flagging is buried in a note: directory mounts require checkpoints created on v0.1.11 or later, and existing checkpoints work normally for all other features. That is a quiet migration hazard. If you have a checkpoint from before that version and you try to mount a directory into it, the mount is the part that breaks, not the rest of the environment, which makes the failure harder to attribute. The README's answer is `shuru upgrade`, but upgrading the binary does not recreate an old checkpoint, and the README does not say what to do with one that predates the change.
shuru.json, and where CLI flags stop being enough
The config file is `shuru.json` in the current directory, or a path passed with `--config`. Every field is optional and CLI flags take precedence, so the file is a defaults layer rather than a replacement for flags. The documented keys are `cpus`, `memory`, `disk_size`, `allow_net`, `ports`, `mounts`, `command`, `secrets` and `network`. The `secrets` block is an object keyed by the name the guest sees, with `from` pointing at the host environment variable and `hosts` listing where substitution is permitted. The `network` block holds an `allow` array of hostnames, and the README notes that omitting it allows all hosts. That default deserves attention. Setting `allow_net: true` without a `network.allow` list gives the guest unrestricted egress, and the restriction only exists if you write the list. The CLI equivalent, `--allow-net --allow-host api.openai.com --allow-host registry.npmjs.org`, has the same shape: `--allow-net` opens the door, `--allow-host` narrows it. A separate flag, `--dns-resolver 1.1.1.1`, lets you point resolution at a specific server, which matters when the host allowlist is enforced by name rather than by IP. The README does not explain how that interaction is resolved, and it is the kind of detail worth confirming before you rely on the allowlist as a security boundary.
The TypeScript SDK and the agent skill are two different integration bets
shuru is not only a CLI. The `@superhq/shuru` package, installed with `bun add @superhq/shuru`, exposes a `Sandbox` class. The README's example calls `Sandbox.start({ from: "python-env" })`, then `sb.exec("python3 -c 'print(1+1)'")` and reads `result.stdout`, then `sb.checkpoint("after-run")`, which the README says saves disk state and stops the VM. The SDK README under `packages/sdk/` is where fuller API documentation lives; the top-level README does not enumerate the rest of the surface. The second integration path is the agent skill, installed with `npx skills add superhq-ai/shuru` or by copying `skills/shuru` into `.claude/skills/shuru`. The README says that once installed, agents will use `shuru run` whenever they need sandboxed execution. These are different bets. The SDK gives you programmatic control and a checkpoint call you can place deliberately. The skill hands the decision to the agent, which means the flags your agent chooses are the flags your sandbox gets. If you care about the host allowlist or the mount mode, the skill path is the one where you have to check what the agent actually passed.
Where shuru is the wrong tool, and what it is not competing with
The clearest boundary is the platform one. macOS 14 or later on Apple Silicon, or Linux ARM64 with KVM. An x86_64 Linux CI runner is out. Windows is not mentioned at all. A team standardising on Linux containers for agent execution is also out, because shuru's Linux backend is described in the README as experimental, with rough edges, missing polish and compatibility gaps, and the note repeats that script-based Linux installs are not ready for production. The second boundary is the one that separates shuru from a hosted sandbox API. A service like E2B runs the sandbox on someone else's infrastructure: you send code, they execute it in their cloud, and you get results back. shuru runs the VM on your machine. That means no per-second billing and no data leaving the laptop, but it also means your laptop's CPU and memory are the ceiling, and the sandbox is unavailable when the machine is asleep. The third boundary is subtler. Because the rootfs resets every run, shuru is a poor fit for any workload that needs durable state inside the guest across runs unless you route it through a checkpoint or a read-write mount. A long-lived agent that accumulates files over days will fight the design. The README gives no indication that persistence is planned, and the ephemerality reads as a deliberate choice rather than a gap.
Maintenance, versioning and the Apache-2.0 terms
Release cadence is visible in the repository metadata: v0.7.0 on 2026-08-05, v0.6.5 on 2026-07-28, v0.6.4 on 2026-07-24. That is a project moving quickly at the 0.x stage, and the README points at CHANGELOG.md for release notes and breaking changes rather than restating them. The practical cost of that cadence is the checkpoint compatibility note described earlier: a format change at v0.1.11 still constrains what you can mount today, and the prescribed remedy is `shuru upgrade`. Budget for reading the changelog before upgrading, particularly if you keep checkpoints around for a long time. On licensing, shuru is Apache-2.0, which is a permissive licence with an explicit patent grant and a requirement to preserve notices. That is a normal choice for infrastructure tooling and imposes little on internal use. It is not legal advice, and if you plan to redistribute shuru inside a product, or to modify and ship it, read the licence text and the NOTICE handling rather than relying on a summary. The README's support section links to a Buy Me A Coffee page, which tells you something about how the project is funded: it is not obviously backed by a commercial entity with a support contract behind it. That is a real consideration when the sandbox is on the critical path of your agent loop.
Editorial conclusion
Adopt shuru if you are on Apple Silicon macOS 14 or later and want agent code execution to stay on your machine with a disposable rootfs, host-side secret substitution and read-only mounts by default. Do not adopt it if you need x86_64 Linux, Windows, or a Linux deployment you would call production-ready; the README itself says the Linux builds are not ready for that. Verify two things before committing: that your existing checkpoints were created on v0.1.11 or later, since directory mounts need them, and that the network.allow host list in shuru.json actually covers every endpoint your agent calls, because the proxy substitutes secrets only for the hosts you name.
Community notes