🧠 Agent Sandbox Runtime

The Self-Correcting AI Agent with Swarm Intelligence

An open-source, production-grade AI agent platform that writes code, executes it safely, learns from failures, and self-corrects until it works.

🎬 See it in action

Swarm Intelligence Activating	Parallel Code Generation

Generated Solution	Mission Accomplished 🏆

📺 Video Demo

📖 Documentation · 🚀 Quick Start · 🏗️ Architecture · 🤝 Contributing

⚡ One-Click Deploy

🎯 Why This Exists

Most AI coding assistants generate code and hope it works. Agent Sandbox Runtime takes a fundamentally different approach:

You describe what you want → Agent writes code → Executes in Docker sandbox → 
If it fails → Analyzes the error → Rewrites with improvements → Repeats until success

This is Reflexion - the same self-improvement loop that makes humans good at coding. Combined with Swarm Intelligence (5 specialist AI agents reviewing each solution), you get code that actually works.

Real-world problems this solves:

• 🔄 "The AI gave me broken code" — Self-correction fixes bugs automatically
• 🔒 "I can't run untrusted code" — Docker isolation makes it safe
• 🐌 "AI suggestions are slow" — Groq inference at 743ms average
• 💸 "AI APIs are expensive" — Free tier models supported (Ollama, OpenRouter)

🏗️ System Architecture

The Reflexion Loop

This is the core innovation. Instead of generating code once, we generate → test → improve:

                    ┌─────────────────────────────────────────────────┐
                    │           REFLEXION LOOP (LangGraph)            │
                    │                                                 │
     Your Task ───► │  ┌──────────┐    ┌─────────┐    ┌─────────┐   │
                    │  │ GENERATE │───►│ EXECUTE │───►│ SUCCESS │───┼──► Result
                    │  │  (LLM)   │    │(Docker) │    │    ?    │   │
                    │  └──────────┘    └─────────┘    └────┬────┘   │
                    │       ▲                              │        │
                    │       │         ┌───────────┐        │ No     │
                    │       │         │  CRITIQUE │◄───────┘        │
                    │       │         │  (LLM)    │                 │
                    │       │         └─────┬─────┘                 │
                    │       │               │                       │
                    │       │         ┌─────▼─────┐                 │
                    │       └─────────┤   RETRY   │                 │
                    │                 │ (≤3 times)│                 │
                    │                 └───────────┘                 │
                    └─────────────────────────────────────────────────┘

Component Overview

Data Flow (Peer-to-Peer)

┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│   CLI/API   │────►│   Runtime   │────►│ Orchestrator│
│   (Input)   │     │  (Entry)    │     │ (LangGraph) │
└─────────────┘     └─────────────┘     └──────┬──────┘
                                               │
                    ┌──────────────────────────┼──────────────────────────┐
                    │                          ▼                          │
                    │  ┌─────────────┐   ┌─────────────┐   ┌───────────┐ │
                    │  │  Generator  │◄─►│   Critic    │◄─►│  Sandbox  │ │
                    │  │   (LLM)     │   │   (LLM)     │   │  (Docker) │ │
                    │  └──────┬──────┘   └─────────────┘   └───────────┘ │
                    │         │                                          │
                    │         ▼                                          │
                    │  ┌─────────────────────────────────────┐          │
                    │  │         SWARM INTELLIGENCE          │          │
                    │  │  ┌────────┐ ┌──────┐ ┌───────────┐  │          │
                    │  │  │Architect│ │Critic│ │ Security  │  │          │
                    │  │  └────────┘ └──────┘ └───────────┘  │          │
                    │  │  ┌────────┐ ┌──────────┐            │          │
                    │  │  │ Coder  │ │Optimizer │            │          │
                    │  │  └────────┘ └──────────┘            │          │
                    │  └─────────────────────────────────────┘          │
                    │                    NODE POOL                       │
                    └────────────────────────────────────────────────────┘

✨ Features

🏆 Benchmark Results

Charts

Success by Difficulty	Response Time

vs Competitors

🚀 Quick Start

Option 1: One-Click Deploy

Click the Railway or Render button above ☝️

Option 2: Docker

docker run -e GROQ_API_KEY=your_key ghcr.io/ixchio/agent-sandbox-runtime

Option 3: Local Installation

# Clone the repository
git clone https://github.com/ixchio/agent-sandbox-runtime.git
cd agent-sandbox-runtime

# Create virtual environment
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install dependencies
pip install -e .

# Configure environment
cp .env.example .env
# Edit .env and add your GROQ_API_KEY (get free key at https://console.groq.com)

# Run your first task
agent-sandbox run "Calculate fibonacci(10)"

Option 4: API Server

# Start the API server
agent-sandbox serve

# POST a request
curl -X POST http://localhost:8000/execute \
  -H "Content-Type: application/json" \
  -d '{"task": "Write a function to check if a number is prime"}'

⚙️ Configuration

Environment Variables

*Only one provider API key is required

Recommended Models by Provider

📂 Project Structure

agent-sandbox-runtime/
├── src/agent_sandbox/
│   ├── api/              # FastAPI endpoints
│   ├── cli.py            # Command-line interface
│   ├── config.py         # Settings & environment
│   ├── orchestrator/     # LangGraph workflow
│   │   ├── graph.py      # Main state machine
│   │   ├── nodes/        # Generate, Execute, Critique, Retry
│   │   └── state.py      # Workflow state model
│   ├── providers/        # LLM provider adapters
│   ├── sandbox/          # Docker execution engine
│   │   ├── manager.py    # Container lifecycle
│   │   ├── executor.py   # Code execution
│   │   └── models.py     # Request/Response types
│   ├── swarm/            # Multi-agent intelligence
│   └── runtime.py        # Main entry point
├── docs/                 # Documentation
├── tests/                # Test suite
├── Dockerfile            # Container build
├── docker-compose.yml    # Local development stack
└── pyproject.toml        # Dependencies & config

📚 Documentation

🤝 Contributing

We welcome contributions! See CONTRIBUTING.md for:

• 🔧 Development setup
• 📝 Code style guidelines
• 🧪 Testing requirements
• 📬 Pull request process
• 💡 Feature request guidelines

Quick Contribution Steps

# Fork & clone
git clone https://github.com/YOUR_USERNAME/agent-sandbox-runtime.git

# Create branch
git checkout -b feature/your-feature

# Install dev dependencies
pip install -e ".[dev]"

# Make changes, run tests
pytest tests/unit/ -v

# Submit PR

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.