{"name":"Agent Sandbox: Secure Local Development for AI Coding Agents","description":"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","url":"https://osrepos.com/repo/mattolson-agent-sandbox","source":"osrepos.com","sourceDescription":"This repository profile is provided by osrepos.com, an open source repository discovery platform.","repositoryProfile":"https://osrepos.com/repo/mattolson-agent-sandbox","generatedFor":"open source discovery and AI-assisted research","markdown":"https://osrepos.com/repo/mattolson-agent-sandbox.md","json":"https://osrepos.com/repo/mattolson-agent-sandbox.json","topics":["agent-harness","agent-sandbox","agents","coding-agents","Python","AI","Development","Security"],"keywords":["agent-harness","agent-sandbox","agents","coding-agents","Python","AI","Development","Security"],"stars":null,"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.","content":"## Introduction\n\nAgent 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.\n\nKey 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.\n\n## Installation\n\nGetting started with Agent Sandbox, especially on macOS with Colima, is straightforward. The project is designed to work with any Docker-compatible runtime.\n\n### 1. Install Prerequisites\n\nFirst, ensure you have a VM and Docker installed. Colima, Podman, OrbStack, Docker Desktop, or Rancher Desktop are all viable options. For Colima, use Homebrew:\n\nbash\nbrew install colima docker docker-compose docker-buildx\ncolima start\n\n\n### 2. Install agentbox CLI\n\nThe `agentbox` command-line interface is central to managing your sandboxes. You can install it quickly via a `curl` command:\n\nbash\ncurl -fsSL https://github.com/mattolson/agent-sandbox/releases/latest/download/install.sh | sh\n\n\nFor more detailed installation options, refer to the [GitHub Releases](https://github.com/mattolson/agent-sandbox/releases \"Agent Sandbox Releases\" target=\"_blank\").\n\n### 3. Initialize the Sandbox\n\nNavigate to your project directory and initialize the sandbox:\n\nbash\nagentbox init\n\n\nThis 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.\n\n### 4. Start the Sandbox\n\n**CLI Mode:**\n\nbash\nagentbox exec\n# Inside the container, start your agent, e.g., claude --dangerously-skip-permissions\n\n\n**Devcontainer Mode (VS Code / JetBrains):**\n\nFor 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.\n\n## Examples\n\nAgent Sandbox simplifies the management and execution of various AI coding agents within its secure environment. Here are some common use cases:\n\n### Running an Agent\n\nAfter initializing and starting the sandbox, you can execute your chosen agent. For example, if you've configured Claude Code:\n\nbash\nagentbox exec\n# Now, inside the container, you can run:\nclaude --dangerously-skip-permissions\n\n\n### Switching Agents\n\nAgent Sandbox allows you to switch between different agents without reinitializing your entire project, preserving agent-specific state and user overrides:\n\nbash\nagentbox switch --agent codex\n\n\n### Customizing Network Policy\n\nThe network policy is highly customizable. You can edit the policy file to allow specific domains or services:\n\nbash\nagentbox edit policy\n\n\nThis opens `.agent-sandbox/policy/user.policy.yaml`, where you can add rules like:\n\nyaml\ndomains:\n  - registry.npmjs.org\n  - host: api.example.com\n    rules:\n      - schemes: [https]\n        methods: [GET]\n        path:\n          prefix: /v1/public/\n\n\nFor 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\").\n\n## Why Use Agent Sandbox?\n\nAgent Sandbox offers significant advantages for developers working with AI coding agents:\n\n*   **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.\n*   **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.\n*   **Reproducible Environments:** Agents run in consistent Debian containers with pinned dependencies, ensuring reproducible results across different setups.\n*   **Agent Flexibility:** Easily switch between various supported agents (e.g., Claude Code, Codex, Gemini) without losing state or reconfiguring your project from scratch.\n*   **IDE Integration:** Seamlessly integrates with popular IDEs like VS Code and JetBrains via devcontainers, offering a familiar development workflow while maintaining security.\n*   **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.\n\n## Links\n\n*   **GitHub Repository:** [https://github.com/mattolson/agent-sandbox](https://github.com/mattolson/agent-sandbox \"Agent Sandbox GitHub\" target=\"_blank\")\n*   **Releases:** [https://github.com/mattolson/agent-sandbox/releases](https://github.com/mattolson/agent-sandbox/releases \"Agent Sandbox Releases\" target=\"_blank\")\n*   **Documentation:** [https://github.com/mattolson/agent-sandbox/tree/main/docs](https://github.com/mattolson/agent-sandbox/tree/main/docs \"Agent Sandbox Documentation\" target=\"_blank\")","metrics":{"detailViews":2,"githubClicks":1},"dates":{"published":null,"modified":"2026-08-16T23:10:48.000Z"}}