agent-sandbox: Secure AI Coding Agents with Docker

Overview

Agent Sandbox is a local development sandbox for AI coding agents, built around Docker-compatible containers and a mitmproxy sidecar. It limits filesystem access to the repository, routes network traffic through an enforceable policy, and injects secrets in the proxy so they are not exposed inside the agent container. The documented target is Colima and Docker Engine on Apple Silicon, though the project says other Docker-compatible runtimes should work.

It is aimed at developers and teams who want agents to work on real repositories with tighter limits on filesystem and network access. You can run agents through the agentbox CLI or use a devcontainer in VS Code or JetBrains, and switch between supported agents while preserving their state.

Key Features

• Restricts the agent container's filesystem mounts to the repository and project-scoped agent state.
• Enforces network egress through a mitmproxy sidecar, with a default-deny policy and request rules for hosts, schemes, methods, paths, and queries.
• Uses an iptables firewall to block direct outbound traffic that would bypass the proxy.
• Injects configured secrets at the proxy, keeping raw secret files out of the agent container.
• Preserves agent authentication and configuration in persistent state volumes, including when switching agents.
• Supports CLI and devcontainer workflows, with documented integrations for Claude Code, Codex, Gemini, OpenCode, Pi, Factory, Copilot, and Hermes.

Use Cases

• A developer wants to try an AI coding agent on a repository while limiting the agent's access to other local files and unrestricted internet access.
• A team needs agents to reach selected services, such as a repository-scoped GitHub API, without placing the corresponding token in the container.
• Developers who prefer a terminal can run an agent in the sandbox with agentbox exec, while IDE users can work through a supported devcontainer.
• Someone evaluating multiple coding agents wants to switch between them without reinitializing the project or losing per-agent state.

Getting Started

On macOS with Colima and the Docker CLI installed, install agentbox, initialize a project, and start a shell in the sandbox:

curl -fsSL https://github.com/mattolson/agent-sandbox/releases/latest/download/install.sh | sh
agentbox init
agentbox exec

See the README for prerequisites, devcontainer setup, agent-specific instructions, and policy configuration.

Alternatives

• OpenShell: OpenShell applies policies to agent file, process, and network access, while agent-sandbox focuses on local containers with a mitmproxy sidecar for network and secret control.
• gh-aw-firewall: gh-aw-firewall targets agentic workflow commands in Docker with domain allowlists and sidecar-held credentials, while agent-sandbox supports local CLI and IDE workflows.

Considerations

The README warns that the project is in early-stage development and may introduce breaking changes. Activity is recent, with regular commits and releases, but the measured contributor base is small and highly concentrated; issue closures have been limited in the measured period. The security model is explicitly best-effort, not a guarantee against escapes. In devcontainer mode, IDE features and extensions create a separate control channel that is not fully removed by the proxy and firewall, so the project recommends CLI mode for the tightest boundary. The README also cautions that storing broad Git credentials inside the container can expose access to repositories beyond the current project; proxy-side injection and narrowly scoped tokens reduce that exposure.