agent-sandbox

Deploy AI coding agents in Docker containers with transparent egress proxy, credential injection, and messaging channels.

Philosophy: One config file, one command. All infrastructure details hidden from the user.

Features

• Data-driven plugins — runtime presets (codex, claude-code, pi) and feature plugins configured via YAML
• Transparent gateway — all agent traffic routes through a proxy for credential injection and MITM
• Secret isolation — real credentials never enter the agent container
• Multi-agent — run multiple agents from a single fleet.yaml with shared config
• Security audit — verify the sandbox contract with agent-sandbox audit
• One command — agent-sandbox generate && agent-sandbox compose up --build

Quickstart

# Install
curl -fsSL https://raw.githubusercontent.com/donbader/agent-sandbox/main/scripts/install.sh | sh

# Add to PATH (add to your shell profile)
export PATH="$HOME/.agent-sandbox/bin:$PATH"

# Scaffold a project
mkdir my-agent && cd my-agent
agent-sandbox init

# Or write config manually
cat > agent.yaml << 'EOF'
name: coder
core_version: latest

runtime:
  image: "@builtin/codex"

gateway:
  services:
    - url: https://api.openai.com
      headers:
        Authorization: Bearer ${OPENAI_API_KEY}

installations:
  - plugin: "@builtin/github-pat"
    options:
      token: "${GITHUB_PAT}"
  - plugin: "@builtin/home-override"
    options:
      home_directory: "./home"
      volume: true
EOF

# Add secrets
echo "OPENAI_API_KEY=sk-..." > .env
echo "GITHUB_PAT=ghp_..." >> .env

# Generate and run
agent-sandbox generate
agent-sandbox compose up --build -d

Commands

agent-sandbox init              # interactive project scaffold
agent-sandbox generate          # agent.yaml → .build/ (Dockerfile, docker-compose.yml, gateway)
agent-sandbox compose ...       # docker compose passthrough (auto-injects -f and --env-file)
agent-sandbox audit             # verify running sandbox meets security contract
agent-sandbox gateway-url       # print gateway's public URL
agent-sandbox upgrade           # update the shim to latest version
agent-sandbox version           # print shim + core versions

Use -C to target a different project directory without switching to it:

agent-sandbox -C examples/multi-agent generate
agent-sandbox -C examples/multi-agent compose up --build

Architecture

┌────────────────────────────────────────────────────────────────┐
│ Host                                                           │
│                                                                │
│  agent-sandbox (shim)                                          │
│  - Resolves core_version from agent.yaml                       │
│  - Downloads/caches core binary                                │
│  - Execs into agent-sandbox-core                               │
│                                                                │
│  agent-sandbox-core                                            │
│  - Reads agent.yaml / fleet.yaml                               │
│  - Resolves plugins (@builtin/ and local)                      │
│  - Generates .build/ (Dockerfile, compose, gateway)            │
│  - Runs: docker compose up                                     │
│                                                                │
│  ┌──────────────────┐       ┌────────────────────────────────┐ │
│  │ Gateway          │◄──────│ Agent Container                │ │
│  │  TCP proxy       │ DNAT  │  iptables → gateway:8443       │ │
│  │  DNS (port 53)   │       │  CA cert trusted               │ │
│  │  TLS MITM        │       │  Runs as unprivileged user     │ │
│  │  Cred injection  │       │  Agent runtime (codex, etc.)   │ │
│  │  Log redaction   │       │  Optional: agent-manager + ACP │ │
│  │                  │       │  Optional: channel sidecars    │ │
│  │  Real credentials│       │                                │ │
│  │  stay HERE only  │       │  Dummy tokens only             │ │
│  └──────────────────┘       └────────────────────────────────┘ │
└────────────────────────────────────────────────────────────────┘

Key security property: The agent container cannot read real credentials. All secrets live in the gateway container. The agent uses dummy tokens; the gateway intercepts requests and swaps in real credentials.

Documentation

Doc	Description
Getting Started	Install, configure, and run your first agent
Configuration	agent.yaml, fleet.yaml, and .env reference
Plugins	Available plugins and their options
Security	Isolation model, threat mitigations
Troubleshooting	Common issues and fixes

Guides:

Guide	Description
Fleet Mode	Multi-agent setup with shared credentials
Creating Plugins	Build your own plugin (plugin.yaml, middleware, templates)

Reference:

Doc	Description
CLI	Commands, flags, environment variables
Migration	Upgrading from legacy CLI
Audit	Security contract verification checks
ACP Protocol	Agent Client Protocol specification
Docker API Proxy	Docker API validation design
ADRs	Architecture Decision Records

Internals (Contributors):

Doc	Description
CLI/Core Split	Shim + core architecture, version resolution, layout
Build Pipeline	Generate flow, Dockerfile templates, core fetching
Gateway	Proxy architecture, MITM pipeline, DNS, middleware SDK
Plugin System	Resolution, rendering, compilation, fleet merging
Logging	Structured logging standards (Go + TypeScript)
Decisions	Key decisions, comparison with agent-fleet
Roadmap	Phased implementation plan

See examples/ for working setups.

License

MIT