Local Development

git clone https://github.com/agentbreeder/agentbreeder.git
cd agentbreeder

# Python environment
python -m venv venv
source venv/bin/activate
pip install -e ".[dev]"

# Copy environment config
cp .env.example .env

# Start PostgreSQL and Redis
docker compose -f deploy/docker-compose.yml up -d postgres redis

docker compose -f deploy/docker-compose.yml ps

alembic upgrade head

uvicorn api.main:app --reload --port 8000

cd dashboard
npm install
npm run dev

agentbreeder --help
agentbreeder list agents

# 1. Register an account (first time only)
curl -X POST http://localhost:8000/api/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{"email":"you@company.com","password":"…","name":"You"}'

# 2. Login → JWT
curl -X POST http://localhost:8000/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"you@company.com","password":"…"}'
# → {"access_token": "eyJ…", "token_type": "bearer"}

# 3. Export — the CLI picks this up automatically
export AGENTBREEDER_API_TOKEN=eyJ…

# Prompts
agentbreeder registry prompt push <file.md> [--name --version --team --description]
agentbreeder registry prompt list [--team]
agentbreeder registry prompt try <name> --input "..." [--model gemini-2.5-flash]

# Tools — auto-detects .py → python:<abs>, .ts/.js → node:<abs>, module path → as-is
agentbreeder registry tool push <module-or-file> [--description]
agentbreeder registry tool list
agentbreeder registry tool run <name> [--args '{"key":"value"}']

# Agents
agentbreeder registry agent push agent.yaml
agentbreeder registry agent list [--team]
agentbreeder registry agent invoke <name> --input "..." [--endpoint URL --token T --session SID]

cd microlearning-ebook-agent/
./scripts/e2e_test.sh
# 7/7 pass

docker compose -f deploy/docker-compose.yml up -d

pytest tests/unit/                        # All unit tests
pytest tests/unit/test_api_routes.py      # Specific file
pytest tests/unit/ -k "test_deploy"       # Pattern match
pytest tests/unit/ --cov=api --cov-report=html  # With coverage

cd dashboard

# Install browsers (first time only)
npx playwright install --with-deps chromium

# Run tests
npx playwright test                    # Headless
npx playwright test --headed           # Watch in browser
npx playwright test --ui               # Interactive UI mode
npx playwright test tests/e2e/agents   # Specific directory

# Start the stack first
docker compose -f deploy/docker-compose.yml up -d

# Run all 97 live E2E tests
cd dashboard && npm run test:e2e:live

# Watch tests run in a browser (recommended for development)
npm run test:e2e:live:ui

# Debug a single failing test
npm run test:e2e:live:debug -- --grep "provider"

pytest tests/unit/ tests/integration/ \
  --cov=api --cov=engine --cov=cli --cov=registry --cov=connectors --cov=sdk \
  --cov-report=html

# Open htmlcov/index.html in your browser
# Current baseline: 95% source coverage (3,666 tests)

# Lint
ruff check .

# Auto-fix
ruff check --fix .

# Format
ruff format .

# Type check
mypy api/ engine/ cli/ registry/ connectors/

cd dashboard

# Lint
npm run lint

# Type check
npx tsc -b --noEmit

# Apply all pending migrations
alembic upgrade head

# Create a new migration from model changes
alembic revision --autogenerate -m "add new column to agents"

# Downgrade one version
alembic downgrade -1

# View migration history
alembic history

agentbreeder/
├── api/                    # FastAPI backend
│   ├── main.py             # App entry, middleware, routers
│   ├── routes/             # REST endpoints
│   │   ├── agents.py       # Agent CRUD
│   │   ├── deploys.py      # Deploy from Studio (POST /api/v1/deploys)
│   │   ├── prompts.py      # Prompts + test panel (POST /api/v1/prompts/test)
│   │   ├── sandbox.py      # Tool sandbox execution (POST /api/v1/tools/sandbox/execute)
│   │   ├── rag.py          # RAG indexes, file ingestion, hybrid search
│   │   ├── memory.py       # Memory configs, conversation storage
│   │   ├── git.py          # Git workflow + PR review backend
│   │   ├── providers.py    # Provider config endpoints
│   │   └── ...
│   ├── services/           # Business logic
│   │   ├── git_service.py  # Git operations
│   │   └── pr_service.py   # Pull request workflow
│   ├── models/             # SQLAlchemy models + Pydantic schemas
│   └── auth.py             # Auth dependencies
├── cli/                    # CLI (Typer + Rich)
│   ├── main.py             # App entry, command registration
│   └── commands/           # One file per command
├── engine/                 # Deploy pipeline
│   ├── config_parser.py    # YAML parsing + validation
│   ├── builder.py          # Container image builder
│   ├── providers/          # Provider abstraction (OpenAI, Ollama, fallback chains)
│   ├── runtimes/           # Framework-specific builders (LangGraph, OpenAI Agents)
│   ├── deployers/          # Cloud-specific deployers (Docker Compose, GCP Cloud Run)
│   └── schema/             # JSON Schema for agent.yaml
├── registry/               # Catalog services (CRUD + search)
├── connectors/             # Integration plugins
├── dashboard/              # React frontend
│   ├── src/pages/          # Page components (see list below)
│   ├── src/components/     # Shared UI components
│   ├── src/hooks/          # React Query hooks
│   ├── src/lib/            # API client, utilities
│   └── tests/e2e/          # Playwright tests
├── deploy/                 # Docker Compose config
├── tests/unit/             # Python unit tests
└── alembic/                # Database migrations

# Required
DATABASE_URL=postgresql+asyncpg://agentbreeder:agentbreeder@localhost:5432/agentbreeder
REDIS_URL=redis://localhost:6379
SECRET_KEY=dev-secret-key
AGENTBREEDER_ENV=development

# Auth
JWT_SECRET_KEY=dev-jwt-secret
JWT_ALGORITHM=HS256
ACCESS_TOKEN_EXPIRE_MINUTES=1440

# Optional integrations
LITELLM_BASE_URL=http://localhost:4000

lsof -i :8000    # Find what's using the port
kill -9 <PID>    # Kill it

docker compose -f deploy/docker-compose.yml ps    # Check if postgres is running
docker compose -f deploy/docker-compose.yml up -d postgres

alembic downgrade base && alembic upgrade head    # Reset DB

cd dashboard && rm -rf node_modules && npm install