agents-sandbox CLI
agents-sandbox runs a coding agent inside a separate microVM, hiding the rest of your system and secrets from it.
- 87 ★ on the repository
- Last commit
- GPL-3.0
Extended access
Why this level
- The project folder is mounted read-write and the agent changes its files.
- By default the agent configuration from the host is copied into the virtual machine.
Install
- Works in
Manual install
Install the tool following the Get started guide on the project website and run `agents-sandbox`. Choose the agent with `--agent <name>`. Set secrets through `env.secret` and do not copy them from the host.
Access and checks
How we reviewExtended accessThe tool runs code or makes network calls and only reads external data.
- The project folder is mounted read-write and the agent changes its files.
- By default the agent configuration from the host is copied into the virtual machine.
This is third-party code. Review the repository files before installing.
What it does
agents-sandbox is a launcher for coding agents. It builds or reuses a dedicated microsandbox virtual machine for each project and agent and attaches the chosen agent inside it. A separate system-wide microsandbox install is not needed: the tool prepares its own environment in its data directory. The virtual machine has its own kernel and root filesystem. The project folder is mounted as `/workspace` read-write, other host files stay invisible until copied or explicitly exposed. Network access is set by profiles: `public` by default, `private`, `host` and `none` with an allowlist. Secrets from `env.secret` stay on the host and the agent receives only a placeholder. Built-in profiles cover opencode, opencode2, pi, Claude Code, Codex, Hermes and Oh My Pi.
Who it is for. Developers who want to run autonomous agents on a work machine without opening the whole home folder and network to them.
Good fit when
- An agent must work on a project but not see other files and keys on the laptop.
- The agent outbound network must be limited to an allowlist of addresses.
- The same project runs with Claude Code, Codex and opencode, each in its own isolated environment.
- Development keys must not reach a public wiki or repository through an agent mistake.
Not a fit when
- You work on a system without Linux with KVM or macOS on Apple Silicon.
- You need full network isolation: the `none` profile denies egress by default but is not a complete air gap.
- Stable behavior with experimental agents matters: only opencode and opencode2 are tested.
Example request
Start Claude Code for this project through agents-sandbox with the `none` network profile and secrets in `env.secret`.Limitations
Platforms: Linux with KVM and macOS on Apple Silicon. The opencode and opencode2 agents (default) are tested and the other five profiles are experimental. The default setup copies the agent configuration from the host into the virtual machine, and for opencode that can include `auth.json`. If credentials must not reach the machine, set `provision-host-config: false` and use the secrets mechanism. The project folder is mounted read-write and the agent changes its files. License GPL-3.0.
How to disable. Stop the machine with `agents-sandbox stop`, remove volumes with `volume prune` or `prune --purge` for a whole project, then remove the tool.
FAQ
How do I run an agent in the sandbox?
Install the tool following the guide on the website and run `agents-sandbox`: OpenCode 2 starts by default. Choose another agent with the `--agent <name>` flag.
Which agents are supported?
Built in are opencode, opencode2, pi, claude-code, codex, hermes and oh-my-pi. The opencode and opencode2 agents are tested and the rest are experimental.
What does the agent see on my machine?
Only `/workspace` with the project and the `/home/dev` volume. Other host files are invisible until you copy them, provision through `home:` or expose with a mount.
How do I protect secrets?
Put them in `env.secret` or `env.secret.yaml`: the real value stays on the host and the guest gets a placeholder. Keep keys out of `/workspace` and `env`.
What does the none network profile do?
It denies egress by default and passes only allowed rules. It is not a complete air gap.
Discussion
No questions or reviews yet.
Related
CLI toolsThe safehouse command runs Claude Code, Codex and other agents in a macOS sandbox: files are closed by default and you open folders with flags
An isolated box for coding agents on your own machine: access only to chosen projects and credentials, secured registry
A Go CLI that runs a coding agent in an OS sandbox with skills and secrets behind a bridge and isolated files and network.
A single binary runs coding agents inside an isolated sandbox: a microVM, network policies and secrets hidden from the agent.
Container-free sandbox for AI agents on Linux and macOS: files, network and syscalls stay closed until you open them explicitly
agent-secrets lends keys to an AI agent for a limited time: age encryption, TTL leases, an access log and an emergency revoke.
Comparison with similar tools
Cards that share the main search query, and how they differ.
| Tool | Official | Authentication | Repository stars | Main difference |
|---|---|---|---|---|
| agents-sandbox (this card) | no | 87 | ||
| Agent-Sandbox | no | key is optional | 232 | an MCP sandbox for running agent code; agents-sandbox runs the agent itself in a microVM |
| LLM-in-Sandbox | no | 248 | another sandbox for models; here coding agents run with secret substitution |
README in short
The README compares against direct execution, bubblewrap and Seatbelt, Docker and Docker Sandboxes. Details live on inoio.github.io/agents-sandbox.