{"id":45411370,"url":"https://github.com/superhq-ai/shuru","last_synced_at":"2026-04-02T14:54:44.745Z","repository":{"id":339469287,"uuid":"1160327105","full_name":"superhq-ai/shuru","owner":"superhq-ai","description":"A local-first microVM sandbox for running AI agents safely on macOS","archived":false,"fork":false,"pushed_at":"2026-03-29T18:33:32.000Z","size":423,"stargazers_count":582,"open_issues_count":5,"forks_count":14,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-03-29T20:38:52.301Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"http://shuru.run/","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/superhq-ai.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-02-17T20:09:15.000Z","updated_at":"2026-03-29T19:58:31.000Z","dependencies_parsed_at":"2026-03-04T01:02:58.670Z","dependency_job_id":null,"html_url":"https://github.com/superhq-ai/shuru","commit_stats":null,"previous_names":["superhq-ai/shuru"],"tags_count":30,"template":false,"template_full_name":null,"purl":"pkg:github/superhq-ai/shuru","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/superhq-ai%2Fshuru","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/superhq-ai%2Fshuru/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/superhq-ai%2Fshuru/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/superhq-ai%2Fshuru/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/superhq-ai","download_url":"https://codeload.github.com/superhq-ai/shuru/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/superhq-ai%2Fshuru/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31308448,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-02T12:59:32.332Z","status":"ssl_error","status_checked_at":"2026-04-02T12:54:48.875Z","response_time":89,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-02-21T23:08:10.253Z","updated_at":"2026-04-02T14:54:44.738Z","avatar_url":"https://github.com/superhq-ai.png","language":"Rust","funding_links":[],"categories":["Rust","Sandboxing \u0026 Isolation"],"sub_categories":[],"readme":"# shuru\n\nLocal-first microVM sandbox for AI agents on macOS.\n\nShuru 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.\n\n## Requirements\n\n- macOS 14 (Sonoma) or later on Apple Silicon\n\n## Install\n\n```sh\nbrew tap superhq-ai/tap \u0026\u0026 brew install shuru\n```\n\nOr via the install script:\n\n```sh\ncurl -fsSL https://raw.githubusercontent.com/superhq-ai/shuru/main/install.sh | sh\n```\n\n## Usage\n\n```sh\n# Interactive shell\nshuru run\n\n# Run a command\nshuru run -- echo hello\n\n# With network access\nshuru run --allow-net\n\n# Restrict to specific hosts\nshuru run --allow-net --allow-host api.openai.com --allow-host registry.npmjs.org\n\n# Custom resources\nshuru run --cpus 4 --memory 4096 --disk-size 8192 -- make -j4\n```\n\n### Directory mounts\n\nShare host directories into the VM using VirtioFS. By default the host directory is read-only; guest writes go to a tmpfs overlay layer (discarded when the VM exits). Append `:rw` to make the mount read-write — guest writes go directly to the host filesystem.\n\n```sh\n# Mount a directory (guest can read, writes go to overlay — host is untouched)\nshuru run --mount ./src:/workspace -- touch /workspace/test.txt\nls ./src/test.txt   # not found — write stayed in the overlay\n\n# Read-write mount (guest writes land on host, requires --allow-host-writes)\nshuru run --allow-host-writes --mount ./src:/workspace:rw -- touch /workspace/test.txt\nls ./src/test.txt   # found — write went to host\n\n# Multiple mounts\nshuru run --mount ./src:/workspace --mount ./data:/data -- sh\n```\n\nMounts can also be set in `shuru.json` (see [Config file](#config-file)).\n\n\u003e **Note:** Directory mounts require checkpoints created on v0.1.11+. Existing checkpoints work normally for all other features. Run `shuru upgrade` to get the latest version.\n\n### Port forwarding\n\nForward host ports to guest ports over vsock. Works without `--allow-net` — the guest needs no network device.\n\n```sh\n# Install python3 into a checkpoint, then serve with port forwarding\nshuru checkpoint create py --allow-net -- apt-get install -y python3\nshuru run --from py -p 8080:8000 -- python3 -m http.server 8000\n\n# From the host (in another terminal)\ncurl http://127.0.0.1:8080/\n\n# Multiple ports\nshuru run -p 8080:80 -p 8443:443 -- nginx\n```\n\nPort forwards can also be set in `shuru.json` (see [Config file](#config-file)).\n\n### Checkpoints\n\nCheckpoints save the disk state so you can reuse an environment across runs.\n\n```sh\n# Set up an environment and save it\nshuru checkpoint create myenv --allow-net -- sh -c 'apt-get install -y python3 gcc'\n\n# Run from a checkpoint (ephemeral -- changes are discarded)\nshuru run --from myenv -- python3 script.py\n\n# Branch from an existing checkpoint\nshuru checkpoint create myenv2 --from myenv --allow-net -- sh -c 'pip install numpy'\n\n# List and delete\nshuru checkpoint list\nshuru checkpoint delete myenv\n```\n\n### Secrets\n\nSecrets keep API keys on the host. The guest receives a random placeholder token; the proxy substitutes the real value only on HTTPS requests to the specified hosts. The real secret never enters the VM.\n\n```sh\n# Inject a secret via CLI\nshuru run --allow-net --secret API_KEY=OPENAI_API_KEY@api.openai.com -- curl https://api.openai.com/v1/models\n\n# Multiple secrets\nshuru run --allow-net \\\n  --secret API_KEY=OPENAI_API_KEY@api.openai.com \\\n  --secret GH_TOKEN=GITHUB_TOKEN@api.github.com \\\n  -- sh\n```\n\nFormat: `NAME=ENV_VAR@host1,host2` — `NAME` is the env var the guest sees, `ENV_VAR` is the host env var with the real value, and hosts are where the proxy substitutes it.\n\nSecrets can also be set in `shuru.json` (see [Config file](#config-file)).\n\n### Config file\n\nShuru loads `shuru.json` from the current directory (or `--config PATH`). All fields are optional; CLI flags take precedence.\n\n```json\n{\n  \"cpus\": 4,\n  \"memory\": 4096,\n  \"disk_size\": 8192,\n  \"allow_net\": true,\n  \"ports\": [\"8080:80\"],\n  \"mounts\": [\"./src:/workspace\", \"./data:/data\"],\n  \"command\": [\"python\", \"script.py\"],\n  \"secrets\": {\n    \"API_KEY\": {\n      \"from\": \"OPENAI_API_KEY\",\n      \"hosts\": [\"api.openai.com\"]\n    }\n  },\n  \"network\": {\n    \"allow\": [\"api.openai.com\", \"registry.npmjs.org\"]\n  }\n}\n```\n\nThe `network.allow` list restricts which hosts the guest can reach. Omit it to allow all hosts.\n\n## SDK\n\nUse shuru programmatically from TypeScript with the [`@superhq/shuru`](https://www.npmjs.com/package/@superhq/shuru) package.\n\n```sh\nbun add @superhq/shuru\n```\n\n```ts\nimport { Sandbox } from \"@superhq/shuru\";\n\nconst sb = await Sandbox.start({ from: \"python-env\" });\n\nconst result = await sb.exec(\"python3 -c 'print(1+1)'\");\nconsole.log(result.stdout); // \"2\\n\"\n\nawait sb.checkpoint(\"after-run\"); // saves disk state and stops the VM\n```\n\nSee the [SDK README](packages/sdk/README.md) for full API docs.\n\n## Agent Skill\n\nShuru ships as an [agent skill](https://agentskills.io) so AI agents (Claude Code, Cursor, Copilot, etc.) can use it automatically.\n\n```sh\n# Install via Vercel's skills CLI\nnpx skills add superhq-ai/shuru\n\n# Or manually copy into your project\ncp -r skills/shuru .claude/skills/shuru\n```\n\nOnce installed, agents will use `shuru run` whenever they need sandboxed execution.\n\n## Changelog\n\nSee [CHANGELOG.md](CHANGELOG.md) for release notes and breaking changes.\n\n## Bugs\n\nFile issues at [github.com/superhq-ai/shuru/issues](https://github.com/superhq-ai/shuru/issues).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsuperhq-ai%2Fshuru","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsuperhq-ai%2Fshuru","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsuperhq-ai%2Fshuru/lists"}