# Agent Sandbox: Secure Local Development for AI Coding Agents This repository profile is provided by osrepos.com, an open source repository discovery platform. Source: osrepos.com Repository profile: https://osrepos.com/repo/mattolson-agent-sandbox Generated for open source discovery and AI-assisted research. Agent Sandbox provides a robust and secure local development environment specifically designed for collaborating with AI coding agents. It ensures minimal filesystem access, configurable network egress policies, and secure secret injection, protecting your local machine from potentially risky agent operations. This project supports various AI agents and integrates seamlessly with both CLI and popular IDE devcontainer setups. GitHub: https://github.com/mattolson/agent-sandbox OSRepos URL: https://osrepos.com/repo/mattolson-agent-sandbox ## Summary Agent Sandbox provides a robust and secure local development environment specifically designed for collaborating with AI coding agents. It ensures minimal filesystem access, configurable network egress policies, and secure secret injection, protecting your local machine from potentially risky agent operations. This project supports various AI agents and integrates seamlessly with both CLI and popular IDE devcontainer setups. ## Topics - agent-harness - agent-sandbox - agents - coding-agents - Python - AI - Development - Security ## Repository Information Last analyzed by OSRepos: Mon Aug 17 2026 00:10:48 GMT+0100 (Western European Summer Time) Detail views: 2 GitHub clicks: 1 ## Safety Notice OSRepos shares public repositories for knowledge and discovery only. Review source code, dependencies, licenses, and security implications before running or installing anything. ## Content ## Introduction Agent Sandbox is an innovative project that creates a secure, isolated local development environment for interacting with AI coding agents. In an era where AI agents are becoming powerful development partners, ensuring their operations are contained and safe is paramount. Agent Sandbox addresses this by providing a locked-down containerized environment with strict controls over filesystem access, network communication, and secret management. Key features include minimal filesystem access, allowing agents to read/write only within their repository directory, and a configurable network egress policy enforced by a sidecar proxy. This proxy restricts network traffic by hostname, scheme, method, path, and query string. Furthermore, secrets like API keys are injected by the proxy, ensuring the agent container never directly accesses sensitive credentials. An `iptables` firewall prevents direct outbound traffic, guaranteeing all communication passes through the proxy, enhancing security. ## Installation Getting started with Agent Sandbox, especially on macOS with Colima, is straightforward. The project is designed to work with any Docker-compatible runtime. ### 1. Install Prerequisites First, ensure you have a VM and Docker installed. Colima, Podman, OrbStack, Docker Desktop, or Rancher Desktop are all viable options. For Colima, use Homebrew: bash brew install colima docker docker-compose docker-buildx colima start ### 2. Install agentbox CLI The `agentbox` command-line interface is central to managing your sandboxes. You can install it quickly via a `curl` command: bash curl -fsSL https://github.com/mattolson/agent-sandbox/releases/latest/download/install.sh | sh For more detailed installation options, refer to the [GitHub Releases](https://github.com/mattolson/agent-sandbox/releases "Agent Sandbox Releases" target="_blank"). ### 3. Initialize the Sandbox Navigate to your project directory and initialize the sandbox: bash agentbox init This command interactively guides you through setting up the project name, agent, mode (CLI or Devcontainer), and IDE, generating the necessary Docker Compose and network policy files. ### 4. Start the Sandbox **CLI Mode:** bash agentbox exec # Inside the container, start your agent, e.g., claude --dangerously-skip-permissions **Devcontainer Mode (VS Code / JetBrains):** For VS Code, install the Dev Containers extension and use the "Dev Containers: Reopen in Container" command. For JetBrains IDEs, open your project and select the devcontainer configuration from the Remote Development menu. ## Examples Agent Sandbox simplifies the management and execution of various AI coding agents within its secure environment. Here are some common use cases: ### Running an Agent After initializing and starting the sandbox, you can execute your chosen agent. For example, if you've configured Claude Code: bash agentbox exec # Now, inside the container, you can run: claude --dangerously-skip-permissions ### Switching Agents Agent Sandbox allows you to switch between different agents without reinitializing your entire project, preserving agent-specific state and user overrides: bash agentbox switch --agent codex ### Customizing Network Policy The network policy is highly customizable. You can edit the policy file to allow specific domains or services: bash agentbox edit policy This opens `.agent-sandbox/policy/user.policy.yaml`, where you can add rules like: yaml domains: - registry.npmjs.org - host: api.example.com rules: - schemes: [https] methods: [GET] path: prefix: /v1/public/ For detailed policy configuration, including GitHub Git integration with proxy-side credential injection, refer to the [official documentation](https://github.com/mattolson/agent-sandbox/tree/main/docs "Agent Sandbox Documentation" target="_blank"). ## Why Use Agent Sandbox? Agent Sandbox offers significant advantages for developers working with AI coding agents: * **Enhanced Security:** It provides a robust sandboxed environment, minimizing risks associated with running AI agents locally. Features like minimal filesystem access, a strict network egress policy, and `iptables` firewall prevent unauthorized operations and data exfiltration. * **Secure Secret Management:** API keys and other sensitive credentials are never exposed directly to the agent container. The sidecar proxy handles secret injection, keeping your tokens safe on the host machine. * **Reproducible Environments:** Agents run in consistent Debian containers with pinned dependencies, ensuring reproducible results across different setups. * **Agent Flexibility:** Easily switch between various supported agents (e.g., Claude Code, Codex, Gemini) without losing state or reconfiguring your project from scratch. * **IDE Integration:** Seamlessly integrates with popular IDEs like VS Code and JetBrains via devcontainers, offering a familiar development workflow while maintaining security. * **Clear Guidance:** The sandbox includes an `operating-in-agent-sandbox` skill that guides agents on how to interact with the environment, explaining network policies and where to find the effective allowlist. ## Links * **GitHub Repository:** [https://github.com/mattolson/agent-sandbox](https://github.com/mattolson/agent-sandbox "Agent Sandbox GitHub" target="_blank") * **Releases:** [https://github.com/mattolson/agent-sandbox/releases](https://github.com/mattolson/agent-sandbox/releases "Agent Sandbox Releases" target="_blank") * **Documentation:** [https://github.com/mattolson/agent-sandbox/tree/main/docs](https://github.com/mattolson/agent-sandbox/tree/main/docs "Agent Sandbox Documentation" target="_blank")