inoio/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. 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.

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.

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.

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.

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.

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 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.

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