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, and Claude Code. It builds or reuses a dedicated microsandbox VM per
project and agent, then attaches the selected agent inside that VM.

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.

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

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 installation guide, then
check the host prerequisites and start the configured agent:

agents-sandbox doctor
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.

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.

Documentation

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

Contributing