agents-sandbox
agents-sandbox allows you to isolate your coding agents from the rest of your dev environment. You are put in control over what parts of your host machine and network environment are available to each agent. agents-sandbox acts as a launcher for opencode, opencode2,
pi, Claude Code, Codex, and Hermes Agent. It builds or reuses a dedicated microsandbox VM per
project and agent, then attaches the selected agent inside that VM. A system-wide microsandbox installation is not
required: agents-sandbox provisions its own isolated runtime under its data directory, never uses ~/.microsandbox as
its runtime, and never writes to it (the one-time migration reads it only to copy your old volumes).
On top of that, agents-sandbox utilizes the robust secrets management of microsandbox, which significantly reduces the exposure of secrets to the agent. This way, your helpful assistant (or even a rogue agent) won't be able to accidentally publish dev secrets to a public wiki page ;)
At the same time, agents-sandbox moves out of the way as much as possible, so that you don't have to adapt to a completely new workflow.
Comparison
The table compares local execution models, not hosted services. Bubblewrap/Seatbelt and Docker are policy-dependent building
blocks, so the entries summarize their usual mechanisms rather than assigning a security score.
| Category | Direct host execution | Bubblewrap / Seatbelt | Docker containers | Docker Sandboxes | agents-sandbox |
|---|
| Isolation boundary | ❌ No boundary; host kernel and user permissions. | ⚠️ Shared host kernel; policy-defined OS sandbox. | ⚠️ Shared host kernel; policy-defined OS sandbox. | ✅ Separate microVM and Linux kernel. | ✅ Separate microVM and Linux kernel. |
| Secrets handling | ❌ Host environment, files, and agent credentials are available. | ⚠️ No host-only broker; supplied values are visible. | ⚠️ No host-only broker; supplied values are visible. | ✅ Host proxy injects credentials; VM sees a sentinel. | ✅ Host proxy injects credentials; VM sees a sentinel. |
| Filesystem isolation | ❌ Host user files are accessible. | ⚠️ Private sandbox view; configured host mounts are shared. | ⚠️ Private sandbox view; configured host mounts are shared. | ✅ Private VM; workspace sharing depends on direct/clone/mountless mode. | ✅ Private VM; only workspace directory is read-write by default; |
| Network isolation | ❌ Host network stack. | ⚠️ Manual firewalling. | ⚠️ Manual firewalling. | ✅ Policy-defined network isolation. | ✅ Policy-defined network isolation. |
| Platform/OS Support | Any OS supported by the agent. | Linux (bubblewrap); macOS (Seatbelt/App Sandbox). | Linux Engine; Docker Desktop on macOS/Windows. | macOS Apple silicon, Windows 11, Ubuntu 24.04+ with KVM. | Linux with KVM, macOS Apple Silicon. |
| Access restrictions | None. | None. | None. | ⚠️ Docker account sign-in required. | None. |
Sources: bubblewrap, Apple App Sandbox,
Docker, and Docker Sandboxes. Platform requirements change; check upstream docs.
Legend for the first four rows: ✅ = stronger isolation or host-side handling; ⚠️ = policy-dependent or deliberately shared; ❌ = no isolation in that category. The platform and access rows are descriptive.
Boundary and tradeoffs
| Surface | Behavior |
|---|
| VM kernel and root filesystem | Separate from the host, using the microsandbox VM boundary. |
| Agent home | Stored in a persistent /home/dev volume scoped to the project and agent. Recreating the VM does not remove this volume unless you reset or prune it. |
/workspace | The host project directory, mounted read-write in a normal session. Some agents allow you to optionally use a worktree-session for a VM-internal worktree instead. |
| Other host files | Not visible unless they are copied, provisioned with home:, or exposed through an explicit host mount. |
| Network | Egress uses the public profile by default; the composable private and host profiles extend it, and the allowlist-only none profile replaces it, with allow/deny rules refining either. none is deny-by-default egress, not a complete air gap. |
| Links | A link the agent opens in the VM is handed to the attached launcher through the home volume and opened in the host's browser, if its scheme is allowlisted (http, https, mailto, editor/app links; never file:). While a browser login is open, the launcher listens on its callback port on the host's loopback and passes the callback into the VM. Turn it off with open-links: false; see Opening links. |
| Raw credentials | env.secret and env.secret.yaml keep the real value on the host and expose a placeholder to the guest. This is separate from ordinary file provisioning. |
Credential warning: The convenience setup copies the active agent's host configuration into the VM by default. For
opencode, that can include ~/.local/share/opencode/auth.json. If credentials must not be stored in the VM, set
provision-host-config: false, use the secret mechanism, and keep credentials out of /workspace, home:, env, and
writable mounts. See the Secrets and Agent configuration
documentation.
Why this model?
The useful distinction is not that an agent becomes safe. It is that the agent process no longer runs in the host's kernel or
root filesystem. A VM boundary limits what the agent can see and modify to the guest and to the host paths you deliberately
share. That is a stronger boundary than running the agent directly on the host or relying only on a shared-kernel container,
while preserving the practical workflow of editing the current checkout.
Use agents-sandbox when you already use a supported coding agent and want:
- a separate VM kernel and root filesystem around agent execution;
- direct read-write access to the current project, or an isolated VM-internal worktree;
- persistent agent state without exposing your whole host home directory; and
- a runner image and network policy that you can configure for the project.
Quick start
Install agents-sandbox using the Get started guide, then
start the configured agent:
agents-sandbox
The default path uses the agent configuration already present on the host. For a self-contained setup with explicit secret
handling, start with Manage config in the sandbox instead.
Agent selection
You can use the --agent <name> flag (available on run, shell, build, volume, stop, and kill) to
select the coding-agent to run, provision, or manage. This is also available as a setting in the configuration file.
--agent-version pins the version agents-sandbox installs into the runner image; it does not replace an agent already
provided by a custom base or project Dockerfile.
Six agents ship as built-in profiles:
opencode — a daemon-based agent with serve/attach, worktree sessions, and GitHub-release upgrade checks.opencode2 (default) — opencode 2 (beta), installed from its native installer; daemon-based with serve/attach, worktree
sessions, and upgrade checks via the opencode update API's latest channel. It owns its own launcher config dir (~/.config/agents-sandbox/opencode2/,
project equivalent .agents-sandbox/opencode2/), while its VM config path and host drop-in stay ~/.config/opencode/.
While no opencode2/ dir exists it falls back to the shared opencode/ dir with a warning (see the agent docs).pi — the pi coding agent (@earendil-works/pi-coding-agent, an npm-installed node bundle — the only agent that
needs node), run interactively, with upgrade checks via pi.dev.claude-code — Anthropic's Claude Code, installed from its native installer, run interactively, with upgrade
checks via the npm registry.codex — OpenAI's Codex CLI, installed from its GitHub release package, run interactively, with upgrade checks via
GitHub releases.hermes — Hermes Agent, installed from its official installer at a
pinned release tag, run interactively, with upgrade checks via its GitHub releases.
Documentation
There's dedicated documentation per topic. You can also browse the documentation on GitHub Pages.
| Topic | Description |
|---|
| Why? | Motivation, isolation boundary, shared data, and limitations. |
| How it works | Architecture: host to VM, /workspace, home volume, secrets, and multi-client attach. |
| Get started | Installation, system requirements, and first run. |
| 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 |
Contributing
