agentbox

Agentbox

Docker-sandboxed AI coding agent CLI with Ralph loop support.

Features

• Isolated Execution: Run AI coding agents (Claude Code, Amp, Aider) in Docker containers
• Ralph Pattern: Iterative task completion with persistent state across iterations
• Multi-Agent Support: Plugin architecture for different AI agents
• Security First: Network isolation by default, controlled API access

Prerequisites

• Docker — must be installed and running
• Go 1.24.0+ — required to build from source
• API keys — see Environment Variables for your agent

Installation

# From source
go install github.com/swamp-dev/agentbox/cmd/agentbox@latest

# Or build locally
git clone https://github.com/swamp-dev/agentbox.git
cd agentbox
make build

Quick Start

# Build Docker images (first time only)
make docker-build-full

# Initialize a project
agentbox init

# Run a single agent session
agentbox run --agent claude-cli --project . --prompt "Fix the bug in auth.ts"

# Run Ralph loop until PRD complete
agentbox ralph --agent claude-cli --max-iterations 10 --prd prd.json

# Check progress
agentbox status
agentbox status --tasks          # show individual task list
agentbox dashboard --watch       # live-refresh TUI

MCP Integration (Claude Code)

Add to your Claude Code MCP config to use agentbox as tools:

agentbox mcp start

Then Claude Code can call agentbox_ralph_start, agentbox_run, etc. Use the returned wait_command with Bash run_in_background to get notified on completion without polling.

Commands

See docs/cli-reference.md for complete flag reference.

Configuration

Create agentbox.yaml in your project root:

version: "1.0"
project:
  name: "my-project"

agent:
  name: claude  # claude, claude-cli, amp, aider

docker:
  image: full   # node, python, go, rust, full
  resources:
    memory: "4g"
    cpus: "2"
  network: none  # isolated by default

ralph:
  max_iterations: 10
  prd_file: prd.json
  progress_file: progress.txt
  auto_commit: true
  quality_checks:
    - name: typecheck
      command: npm run typecheck
    - name: test
      command: npm test
  stop_signal: "<promise>COMPLETE</promise>"

Ralph Pattern

See docs/prd-guide.md for the PRD schema reference and guide for writing effective PRDs.

The Ralph pattern enables iterative AI agent execution with memory persistence:

1. Spawn fresh container with agent
2. Load PRD, find next incomplete task
3. Run agent with task-specific prompt
4. Check for completion signal
5. Run quality checks
6. Commit changes to git
7. Update prd.json
8. Append learnings to progress.txt
9. Repeat until complete

State persists via:

• Git history (code changes)
• prd.json (task status)
• progress.txt (learnings)
• AGENTS.md (patterns discovered)

Docker Images

Build images locally:

make docker-build

Security

Isolated by default:

• Filesystem: Only mounted /workspace accessible
• Network: No outbound (opt-in with --allow-network)
• Processes: Container PID namespace
• Docker: No access to host docker.sock

Shared (read-only):

• SSH keys (~/.ssh)
• Git config (~/.gitconfig)
• API keys (via environment)

Environment Variables

Development

# Run tests
make test

# Build binary
make build

# Format code
make fmt

# Run linters
make lint

Documentation

• CLI Reference — Complete flag reference for all commands
• PRD Guide — PRD schema and guide for writing effective task definitions
• Troubleshooting — Solutions for common issues
• Contributing — Development setup and contributor guide
• Security — Security model and policies

License

MIT