{"id":47719012,"url":"https://github.com/x-mckay/abox","last_synced_at":"2026-04-18T05:04:26.835Z","repository":{"id":345437382,"uuid":"1185890444","full_name":"X-McKay/abox","owner":"X-McKay","description":"Secure, parallel AI agent sandboxing using microVMs, git worktrees, and a policy-enforcing credential proxy — written in Rust.","archived":false,"fork":false,"pushed_at":"2026-04-18T01:21:28.000Z","size":1208,"stargazers_count":0,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-18T01:23:37.649Z","etag":null,"topics":["ai-agents","cloud-hypervisor","devtools","git-worktrees","microvm","rust","sandbox","security","tls-proxy","virtiofs"],"latest_commit_sha":null,"homepage":null,"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/X-McKay.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","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":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-03-19T03:28:23.000Z","updated_at":"2026-04-17T23:29:28.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/X-McKay/abox","commit_stats":null,"previous_names":["x-mckay/abox"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/X-McKay/abox","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/X-McKay%2Fabox","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/X-McKay%2Fabox/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/X-McKay%2Fabox/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/X-McKay%2Fabox/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/X-McKay","download_url":"https://codeload.github.com/X-McKay/abox/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/X-McKay%2Fabox/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31957158,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-18T00:39:45.007Z","status":"online","status_checked_at":"2026-04-18T02:00:07.018Z","response_time":103,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":["ai-agents","cloud-hypervisor","devtools","git-worktrees","microvm","rust","sandbox","security","tls-proxy","virtiofs"],"created_at":"2026-04-02T19:13:34.869Z","updated_at":"2026-04-18T05:04:26.804Z","avatar_url":"https://github.com/X-McKay.png","language":"Rust","readme":"# abox — Parallel AI Agent Sandboxing\n\n`abox` is a lightweight, secure tool for running multiple AI coding agents in parallel, isolated sandboxes. It combines **git worktrees** with **microVMs** (Cloud Hypervisor) to provide agents with independent workspaces, while securely proxying credentials via a dual-layer interception architecture.\n\n## Why `abox`?\n\nWhen running multiple autonomous agents on a single codebase, you face three problems:\n1. **Workspace collisions:** Agents stepping on each other's git branches and files.\n2. **Credential leaks:** Giving agents direct access to your AWS or GitHub tokens is dangerous.\n3. **Host system risk:** Agents running `rm -rf /` or installing malware.\n\n`abox` solves this by:\n- Isolating each agent in a fast-booting **Cloud Hypervisor microVM**.\n- Mounting independent **git worktrees** into the VM via `virtiofs`.\n- Proxying commands and HTTP requests out of the VM through a **strict, TOML-configured policy engine**.\n- Injecting API credentials into outbound HTTPS requests via a **TLS-terminating MITM proxy**, so secrets never enter the VM.\n\n## Architecture\n\n`abox` is built in Rust using a Hexagonal (Ports \u0026 Adapters) architecture.\n\n1. **`abox-core`**: Domain logic (Workspace manager, VM lifecycle, Policy engine).\n2. **`abox-cli`**: The user interface (CLI commands and TUI dashboard).\n3. **`abox-proxyd`**: The host-side daemon that evaluates policies and executes allowed commands.\n4. **`abox-shim`**: A static musl binary injected into the guest VM that intercepts commands (via symlinks) and forwards them to `proxyd`.\n\n![Architecture](.plans/architecture-diagram.png)\n\n## Getting Started\n\n### Prerequisites\n\n- Linux host with `/dev/kvm` accessible to your user\n- Rust toolchain (`cargo`)\n- `just` command runner (`cargo install just`)\n\n### Installation\n\n\u003e **Note:** abox is currently pre-release. The recommended install path is\n\u003e from source (below). A one-command installer will be available once the\n\u003e first release is published.\n\n**From source** (recommended):\n\n```bash\n# Prerequisites: Rust (https://rustup.rs), just (cargo install just)\ngit clone https://github.com/X-McKay/abox.git\ncd abox\ncargo build --release\n\n# Add the compiled binary to your PATH (or copy it to ~/.local/bin)\nexport PATH=\"$PWD/target/release:$PATH\"\n\nabox init             # guided first-run setup: downloads VM stack,\n                      # writes config, installs default policy\n```\n\nOr run the steps individually:\n\n```bash\njust bootstrap-vm     # downloads the VMM, kernel, builds the rootfs,\n                      # and symlinks the binaries into ~/.local/bin\nabox doctor           # verify the environment before first use\n```\n\n`bootstrap-vm` is idempotent and uses checksummed cached downloads, so\nre-running it is fast (seconds, not minutes). Currently supports **x86_64**\nhosts only — aarch64 support is in progress. See\n[`docs/vm-setup.md`](docs/vm-setup.md) for the full setup walkthrough.\n\n**One-command install** (once a release is published):\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/X-McKay/abox/main/scripts/install.sh | bash\n```\n\n### Documentation\n\n- [`docs/tutorial.md`](docs/tutorial.md) — 10-minute walkthrough from\n  `git clone` to your first sandbox\n- [`docs/explainer.md`](docs/explainer.md) — architecture deep dive:\n  what every component does and why\n- [`docs/vm-setup.md`](docs/vm-setup.md) — VM stack installation +\n  troubleshooting\n- [`docs/decisions/`](docs/decisions/) — architecture decision records\n- [`docs/future-work.md`](docs/future-work.md) — forward-looking\n  roadmap; what's next and why\n\n### Configuration\n\nThe easiest way to configure abox is to run `abox init`, which writes\n`~/.abox/config.toml` with all paths pre-filled and installs the default\npolicy automatically.\n\nTo configure manually:\n\n```bash\nmkdir -p ~/.abox/policies\ncp templates/config.example.toml ~/.abox/config.toml\ncp policies/default.toml ~/.abox/policies/default.toml\n# Then edit ~/.abox/config.toml to set image_path and kernel_path\n# to the output of 'just bootstrap-vm' (~/.abox/vm/rootfs.raw and\n# ~/.abox/vm/vmlinux).\n```\n\nBy default, abox stores all state under `~/.abox/` (worktrees, templates,\nlogs, and the runtime socket directory). No root access required.\n\nRun `abox doctor` at any time to check your environment for common setup\nproblems.\n\n### Usage\n\n1. **Start an agent sandbox:**\n   ```bash\n   abox run --task fix-auth --base main -- claude\n   ```\n\n2. **Start with runtime controls:**\n   ```bash\n   abox run --task fix-auth --timeout 300 --ephemeral -- claude\n   # --timeout N: kill after N seconds (exit code 124)\n   # --ephemeral: auto-remove sandbox after exit\n   ```\n\n3. **Fast start from a template (snapshot restore, ~100ms):**\n   ```bash\n   abox template create --name base --from running-sandbox\n   abox run --template base --task fix-auth -- claude\n   ```\n\n4. **List running sandboxes:**\n   ```bash\n   abox list\n   ```\n\n5. **Check divergence across agents:**\n   ```bash\n   abox divergence\n   ```\n\n6. **Merge a completed task:**\n   ```bash\n   abox merge fix-auth\n   ```\n\n7. **Manage the CA (for HTTPS credential injection):**\n   ```bash\n   abox ca show      # fingerprint + expiry\n   abox ca rotate    # regenerate CA + rebuild rootfs\n   abox ca path      # print CA directory\n   ```\n\n8. **Configure credential forwarding (for Claude Code, Codex, etc.):**\n   ```bash\n   # Edit ~/.abox/config.toml and add:\n   # [guest]\n   # [[guest.credential_files]]\n   # host = \"~/.claude/.credentials.json\"\n   # guest = \"~/.claude/.credentials.json\"\n   # [guest.credential_files.stub.claudeAiOauth]\n   # accessToken = \"abox-proxy-managed\"\n   # ...\n   # See docs/explainer.md Section 8 for full details.\n   ```\n\n## Development\n\nWe use `just` as our command runner. Install it with `cargo install just`.\n\n- `just check`: Run formatting, lints, and tests.\n- `just lint`: Run clippy with strict warnings.\n- `just build-shim`: Build the guest shim (requires the musl target for your host architecture).\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for detailed development guidelines.\n\n## Performance\n\nMeasured on x86_64, 32 cores, kernel 6.14.0-37-generic. VM benchmarks averaged over 5 runs.\nUpdated at release v0.1.0 (2026-04-17).\n\n| Metric | Value | What it measures |\n|---|---|---|\n| VM boot | 186 ms | Cloud Hypervisor start to first proxied request |\n| Proxy round-trip | 186 ms | Bridge ready to `git status` response |\n| Full `abox run` | 478 ms | Total wall time for trivial guest command |\n| Sandbox cleanup | 17 ms | `abox stop --clean` teardown |\n| Policy evaluation | ~47.897 ns | `evaluate_cli` for `git status` (allowed) |\n| Request serialization | ~53.448 ns | JSON encode of `ProxyRequest` |\n| Boot meta generation | ~183.50 ns | `BootMeta::to_json()` |\n| Release binary | 9.4 MB | `target/release/abox` (LTO + strip) |\n\nRun `just bench` (criterion, no VM) or `just bench-vm-n 5` (VM latency) to reproduce.\n\n## License\n\nApache 2.0\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fx-mckay%2Fabox","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fx-mckay%2Fabox","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fx-mckay%2Fabox/lists"}