agentbox (mattolson) — Summary

agentbox is a Go CLI + Docker image toolkit that runs AI coding agents (Claude Code, Codex, Gemini CLI, OpenCode, Pi, Factory, Copilot) inside locked-down local Docker sandboxes with multi-layer network enforcement. The security model has two layers: a mitmproxy sidecar that enforces a host allowlist with fine-grained per-route rules (scheme, method, path, query), plus an iptables firewall that blocks all direct outbound — traffic must transit the proxy. Credentials are injected by the proxy into HTTP headers from host-side secret files; the agent container never sees the actual token. The CLI binary agentbox handles init, exec, switch (change agent while preserving state), policy editing, and compose management. DevContainer mode enables VS Code and JetBrains IDE integration. The project is described as early-stage with the primary author using Claude Code as the primary supported agent.

Differs from seeds: No seed has two-layer network isolation (mitmproxy allowlist + iptables firewall). The closest seed is agent-os (personal harness for one user) but agentbox is provider-agnostic (7 supported agents) and adds real network-level enforcement. Unlike nanoclaw (per-session container + messaging channels), agentbox is a pure code-execution sandbox for development tasks, not a messaging assistant.

agentbox (mattolson) — Overview

Origin

agentbox is a personal project by Matt Olson (mattolson). Written in Go. The project targets Apple Silicon macOS (primary), with Colima as the recommended VM backend, though any Docker-compatible runtime works.

Philosophy

From README:

"Run AI coding agents in a locked-down local sandbox with:

• Minimal filesystem access (read/write access to only your repository directory)
• Configurable network egress policy enforced by a sidecar proxy (restrict by hostname, as well as fine-grained attributes, like scheme, method, path, and query string)
• Secret injection conducted in the proxy, so the agent container never sees secrets such as API keys
• Iptables firewall preventing direct outbound (all traffic must go through the proxy)
• Reproducible environments (Debian container with pinned dependencies)"

Key Design Principles

1. Network enforcement happens at two independent layers — both must be bypassed to exfiltrate data
2. Credentials stay on the host; never enter the agent container
3. One binary (agentbox) manages the full sandbox lifecycle
4. User-owned policy files persist across agent switches; managed files are regenerated

Repo Facts

• GitHub: https://github.com/mattolson/agent-sandbox
• Stars: 174 (2026-05-26)
• Language: Go + Python (proxy enforcement)
• License: MIT
• Last commit: 2026-05-26
• Status: Early-stage development (README warning)

agentbox (mattolson) — Architecture

Distribution

• Binary: downloaded from GitHub Releases
• Quick install: curl -fsSL .../install.sh | sh (installs to ~/.local/bin)
• Platform: macOS (Apple Silicon primary), Linux

Security Architecture (Two-Layer)

Agent Container (Debian)
    ↓ all outbound blocked by iptables
Proxy Sidecar (mitmproxy)
    ↓ host policy + route rules
    ↓ credential injection (HTTP header from host secret file)
Internet

Layer 1 — Proxy (mitmproxy sidecar):

• Enforces hostname allowlist
• Optional per-route rules: scheme, method, path prefix, query string
• Credential injection: HTTP header from host-side secret file
• Default policy: BLOCKS ALL traffic
• Non-matching requests get 403 response
• Hot-reload: agentbox reloads proxy policy on save

Layer 2 — Firewall (iptables):

• Blocks all direct outbound from agent container
• Only Docker bridge network (proxy) reachable
• Even if agent ignores HTTP_PROXY/HTTPS_PROXY env vars, direct outbound is blocked

Network Policy Architecture

.agent-sandbox/policy/
├── user.policy.yaml              # Shared user-owned (survives agent switches)
├── user.agent.<agent>.policy.yaml # Per-agent user-owned
├── base.yml                      # Managed base policy (regenerated)
└── policy.devcontainer.yaml      # DevContainer-specific

Directory Structure

agent-sandbox/
├── cmd/agentbox/     # Go CLI commands
├── internal/
│   ├── cli/          # Cobra commands + user behavior
│   ├── runtime/      # Path discovery, agent state, lifecycle
│   ├── scaffold/     # File generation (init, switch)
│   ├── docker/       # Docker + Compose invocation
│   └── embeddata/    # Embedded templates
├── images/
│   ├── base/         # Debian base image
│   ├── agents/       # Per-agent images (claude, codex, gemini, etc.)
│   ├── proxy/        # mitmproxy + enforcer.py
│   └── build.sh
├── .agent-sandbox/   # Generated runtime files (this repo's local sandbox)
└── docs/             # CLI reference, policy schema, agent setup guides

Supported Agents

agentbox (mattolson) — Components

CLI Binary (agentbox)

Key subcommands:

• agentbox init — Interactive: project name, agent, mode, IDE; generates compose + policy files
• agentbox exec — Open shell in agent container; start agent CLI inside
• agentbox switch --agent <agent> — Switch agent while preserving state volumes and user overrides
• agentbox policy config — Output effective network policy
• agentbox compose config — Output fully combined Docker compose stack
• agentbox edit policy — Edit user policy file in $EDITOR (hot-reload triggers on save)

Docker Images

• base/ — Debian bookworm, non-root dev user (uid/gid 500), zsh
• agents/<agent>/ — Per-agent images (claude, codex, gemini, opencode, pi, factory, copilot)
• proxy/ — mitmproxy + Python enforcer addon (enforcer.py)

proxy/enforcer.py

• Python addon for mitmproxy
• Checks HTTPS CONNECT tunnels against hostname policy
• Checks decrypted HTTP/HTTPS requests against scheme, method, path, query rules
• Non-matching: 403 response
• Credential injection: reads host secret file, injects as HTTP header into matched requests

Network Policy (YAML)

services:
  - github                    # pre-defined service allowlist entry
  
domains:
  - registry.npmjs.org        # plain hostname allow
  - host: api.example.com     # hostname with per-route rules
    rules:
      - schemes: [https]
        methods: [GET]
        path:
          prefix: /v1/public/

Generated Runtime Files (.agent-sandbox/)

• active-target.env — Active agent + runtime metadata
• compose/base.yml — Managed shared compose layer
• compose/agent.<agent>.yml — Managed per-agent compose
• compose/user.override.yml — User-owned shared overrides (preserved across switches)
• compose/user.agent.<agent>.override.yml — Per-agent user overrides
• policy/user.policy.yaml — Shared user policy (preserved)
• policy/user.agent.<agent>.policy.yaml — Per-agent user policy

DevContainer Support

• .devcontainer/devcontainer.json — Generated by agentbox
• VS Code: "Dev Containers: Reopen in Container"
• JetBrains: Remote Development → Dev Containers

agentbox (mattolson) — Uniqueness & Positioning

differs_from_seeds

agentbox has no close seed equivalent. agent-os is the nearest in "personal local harness" philosophy but agent-os does no isolation (in-place bash scripts). agentbox's two-layer network enforcement (mitmproxy allowlist + iptables firewall) is unique in this corpus — no seed framework attempts to enforce network egress. Unlike nanoclaw (which uses Docker containers for messaging assistant sessions), agentbox is a code-development sandbox with no messaging functionality. Unlike IronClaw (WASM sandbox), agentbox uses Docker + iptables.

Distinctive Positioning

1. Dual-layer network enforcement: mitmproxy allowlist (application layer) + iptables (kernel layer). Two independent systems must be bypassed to exfiltrate data. No other framework in this corpus implements this.

2. Credential injection at proxy layer: Agent container has HTTP_PROXY env pointing to sidecar; proxy reads host secret file, injects as HTTP header. Agent sees the auth header in responses; never sees the token file. More secure than NanoClaw's OneCLI (which is host-side, not container-layer).

3. Multi-agent switch with state preservation: agentbox switch --agent codex preserves per-agent Docker volumes (auth, history) while regenerating managed config files. User policy files survive all switches.

4. Meta-recursive development: The repo itself is developed inside its own sandbox — the AGENTS.md explicitly describes the network restrictions the contributing agent will encounter. Self-hosting of the tool.

5. DevContainer-first IDE integration: Not a Claude Code plugin or VS Code extension, but integrates with ANY IDE supporting devcontainer spec.

Observable Failure Modes

• Early-stage warning in README — expect breaking changes
• 174 stars — small community, limited documentation depth
• Requires Colima or other Docker VM (non-trivial setup on macOS)
• Default policy blocks all traffic — substantial policy configuration required per project
• No AI memory or context enhancement — purely a security sandbox
• No multi-agent or parallel execution
• SSH disabled (git HTTPS-only) — may conflict with some workflows