Local Development Guide

This guide covers setting up AgentBreeder for local development and contributing.

Prerequisites

Tool	Version	Purpose
Python	3.11+	Backend, CLI, engine
Node.js	22+	Dashboard frontend
Docker & Compose	Latest	Local services, container builds
Git	Latest	Version control

Setup

1. Clone and install

git clone https://github.com/rajitsaha/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

2. Start local services

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

Wait for services to be healthy:

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

3. Run database migrations

alembic upgrade head

4. Start the API server

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

API is available at http://localhost:8000. OpenAPI docs at http://localhost:8000/docs.

5. Start the dashboard

cd dashboard
npm install
npm run dev

Dashboard is available at http://localhost:5173. It proxies API requests to port 8000 via Vite config.

6. Verify the CLI

agentbreeder --help
agentbreeder list agents

Full Stack (Docker Compose)

To run everything in Docker (API + Dashboard + Postgres + Redis + migrations):

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

Service	URL
Dashboard	http://localhost:3001
API	http://localhost:8000
API Docs	http://localhost:8000/docs
PostgreSQL	localhost:5432
Redis	localhost:6379

Default credentials for local dev:

DB: agentbreeder / agentbreeder / database agentbreeder
App login: admin@agentbreeder.local / changeme

Running Tests

Python unit tests

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

Playwright E2E tests

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

Coverage report

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

# Open htmlcov/index.html in your browser

Linting & Formatting

Python

# Lint
ruff check .

# Auto-fix
ruff check --fix .

# Format
ruff format .

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

TypeScript

cd dashboard

# Lint
npm run lint

# Type check
npx tsc -b --noEmit

Database Migrations

# 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

Project Layout

agentbreeder/
├── api/                    # FastAPI backend
│   ├── main.py             # App entry, middleware, routers
│   ├── routes/             # REST endpoints
│   │   ├── agents.py       # Agent CRUD
│   │   ├── deploys.py      # Deploy from dashboard (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

Dashboard Pages

Page	Path	Description
Agents	`/agents`	Agent registry browser
Agent Detail	`/agents/:id`	Agent detail + deploy history
Agent Builder	`/agents/builder`	Visual drag-and-drop agent builder (ReactFlow canvas, 8 node types)
Deploys	`/deploys`	Deploy from dashboard with 8-step pipeline dialog
Prompts	`/prompts`	Prompt registry + test panel
Prompt Builder	`/prompts/builder`	Template variables, live preview, versioning
Tools	`/tools`	Tool registry
Tool Builder	`/tools/builder`	Tool builder + sandbox execution
MCP Servers	`/mcp-servers`	MCP server registry
Models	`/models`	Model registry + model compare
RAG Builder	`/rag`	RAG index management, file ingestion, hybrid search
Memory Builder	`/memory`	Memory config management, conversation storage
Approvals	`/approvals`	Approval workflow, PR review UI, environment promotion
Activity	`/activity`	Activity feed / audit log
Settings	`/settings`	Org + user settings

API Routes (v0.3)

Routes added in v0.3:

Method	Endpoint	Description
`POST`	`/api/v1/deploys`	Trigger deploy from dashboard
`POST`	`/api/v1/prompts/test`	Test a prompt with model + variables
`POST`	`/api/v1/tools/sandbox/execute`	Execute a tool in sandbox
`GET/POST`	`/api/v1/rag/*`	RAG indexes, file ingestion, search
`GET/POST`	`/api/v1/memory/*`	Memory configs, conversation storage
`GET/POST`	`/api/v1/git/*`	Git operations, PR review workflow
`GET/POST`	`/api/v1/providers/*`	Provider configuration

Environment Variables

Key variables in .env:

# 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

Common Tasks

Add a new API endpoint

Add route in api/routes/
Add service logic in api/services/ or registry/
Add Pydantic schemas in api/models/schemas.py
Write unit tests in tests/unit/

Add a new CLI command

Create cli/commands/your_command.py
Register in cli/main.py: app.command(name="your-command")(your_module.your_function)
Write unit tests

Add a new dashboard page

Create page in dashboard/src/pages/
Add route in dashboard/src/App.tsx
Add navigation link in dashboard/src/components/shell.tsx
Write Playwright E2E test in dashboard/tests/e2e/

Modify the database schema

Update SQLAlchemy model in api/models/
Create migration: alembic revision --autogenerate -m "description"
Review the generated migration file
Apply: alembic upgrade head

Troubleshooting

Port already in use:

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

Database connection refused:

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

Stale migrations:

alembic downgrade base && alembic upgrade head    # Reset DB

Node modules issues:

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

Local Development

On this page