agents-sandbox

coding agents, supercharged — safely. Run claude, opencode and pi in a near-instant, hardware-isolated VM — your project at /workspace, your secrets safe, your agent free to do its best work.

agents-sandbox provides coding agents (opencode, pi, claude code) in a real, hardware-isolated machine to work on — full agent permissions inside a boundary that can't reach your host, and secrets the agent never gets to see.

Docker, bubblewrap, seatbelt, and bare coding agents all share your kernel — a kernel bug or sudo is enough for an agent to reach your machine. agents-sandbox runs a separate kernel under hypervisor isolation (KVM on Linux, Apple Silicon on macOS), so escaping takes a hypervisor-level bug: a much higher bar.

Your project is mounted at /workspace, read-write, so the agent works on the same files you do and edits round-trip. Everything else on your machine — other projects, your home directory, your keys — simply isn't there, except for what you explicitly provision into the VM's home (via yaml-based configuration). Secrets are injected at runtime through the secret mechanism as environment variables and never written into the VM, so an agent can't leak what it never possessed. Worst case, a session is a disposable VM: wipe it, and the host is untouched.

It's also yours to shape: the VM's root is defined by a plain Dockerfile, you bring your own base image and tooling like any OCI image you already use — and it's purpose-built for the agent, with support for functionalities like worktree sessions (in opencode). Egress and ingress stay under your control with simple profiles and allow/deny lists, from full network access to complete lockdown.

	Bare agent	Bubblewrap / Seatbelt	Docker (containers)	Docker Sandboxes	agents-sandbox
Isolation boundary	❌ none	⚠️ shared kernel	⚠️ shared kernel	✅ full VM (microVM)	✅ full VM (hypervisor)
How hard to hide secrets?	❌ nearly impossible	⚠️ complex per-project rules	⚠️ manual per-project tweaking	✅ built-in (proxy; login-required)	✅ built-in mechanism
Agent edits appear in your local files instantly	✅	✅	✅	✅ rw mount (clone mode is read-only)	✅
Failure cost vs. recovery	❌ high damage, hard to restore	⚠️ potential host damage	⚠️ potential host damage	✅ disposable	✅ disposable, home can persist
Ease of use	✅ just run it	⚠️ craft rules	⚠️ image + mounts	✅ one command (Docker account login)	✅ one command

Cells give the typical story for each approach. ✅ = yes / good, ⚠️ = possible but partial / in-between, ❌ = no / poor. "Failure cost vs. recovery" weighs how much damage a rogue agent can cause against how easily you can throw the environment away and start over.

❓ Why not just use Docker Sandboxes?

Its microVM isolation is genuinely strong. But it's a trade: a mandatory Docker account login for a tool that runs locally, a closed-source core (VMM + policy proxy + credential injection) you're trusting as your security boundary, org-wide controls behind a paid sales tier, and narrower reach (Ubuntu 24.04+ / Apple silicon / Windows 11 only).

agents-sandbox, by contrast, is open and account-free, runs on any Linux (KVM) and Apple Silicon, and gives you one-command disposal — without the telemetry, login, or vendor lock-in.

Agents

agents-sandbox is agent-aware. A --agent <name> flag on run, shell, build, volume, stop, and kill selects the coding-agent profile to run, provision, or manage; --agent-version pins the agent version baked into the runner image. Four agents ship as built-in profiles:

• opencode (default) — a daemon-based agent with serve/attach, worktree sessions, and GitHub-release upgrade checks.
• opencode2 — opencode 2 (beta), installed from @opencode-ai/cli@beta on npm; daemon-based with serve/attach, worktree sessions, and npm beta-tag upgrade checks. It shares the opencode config directory (v2 reads the same files as v1).
• pi — the pi coding agent (@earendil-works/pi-coding-agent), run interactively, with upgrade checks via pi.dev.
• claude-code — Anthropic's Claude Code (@anthropic-ai/claude-code), run interactively, with upgrade checks via the npm registry.

--worktree and --serve-only are rejected for agents that have no daemon (pi, claude-code); they run through the interactive TUI instead.

By default the launcher copies the active agent's config + credential files from the host into the VM. Security note: this might include credentials (e.g. opencode's auth.json). If you prefer to deliver credentials via the env-secret mechanism (which never writes them into the VM), see the Configuration docs to opt out of the file copy.

Documentation

There's dedicated documentation per topic. You can also browse the documentation on GitHub Pages.

Topic	Description
Why?	Why agents-sandbox: motivation and threat model.
How it works	Architecture: host ↔ VM, /workspace, home volume, secrets, multi-client attach.
Install	Installation, prerequisites
Switch from your existing agent	Use agents-sandbox with your existing agent config and credentials (host-config drop-in).
Manage config in the sandbox	Declarative, self-contained config: secrets, provisioning, agent snippets.
Commands	Complete CLI reference
Configuration	Split into subpages: Configuration files & Environment variables, secrets, networking, host mounts, home provisioning & startup hooks, agent configuration, notifications, self-upgrade
Runner Image	Base image, custom tooling
Worktree Sessions	Isolated worktree sessions for per-feature development
Recipes	Hands-on workflows
Sandboxes	VM lifecycle, volumes, pruning
Troubleshooting	Common issues and fixes
Roadmap	Public, forward-looking project roadmap

Contributing

Topic	Description
Contributing	Guidelines for contributing to agents-sandbox
Code of conduct	Our code of conduct
Security	Rules for submitting security issues
Roadmap	Public, forward-looking project roadmap