Development Setup

Development Setup

Get Maestro running locally, end to end, at zero cost — the full agent flow works offline via Ollama.

Prerequisites

• Docker (for Postgres/Mongo/Qdrant/Redis, and optionally the code-execution sandbox).
• Python 3.11+.
• Node 20.
• Ollama (optional but recommended) — for the free chat model (qwen3.5:9b) and embeddings (nomic-embed-text). Without a local chat model, subtasks fail but tasks still complete with a "no successful subtask output" result.

No paid API key is required: use local Ollama, or a provider's free tier (e.g. Gemini).

Quick start (one command)

The dev scripts bootstrap infra + backend + frontend together:

• Windows: scripts/dev.ps1 — params -SkipInfra, -SkipSeed, -BackendPort 8000, -FrontendPort 3000.
• macOS/Linux: scripts/dev.sh — flags --skip-infra, --skip-seed; env BACKEND_PORT / FRONTEND_PORT.

Each script: (1) docker compose up -d the infra; (2) create/use backend/.venv, copy .env.example → backend/.env if missing, pip install, alembic upgrade head, seed the marketplace (python -m app.scripts.seed_marketplace); (3) copy frontend/.env.local.example → .env.local, npm install if needed, run npm run dev; and tear both down cleanly on Ctrl+C.

Note: the scripts install requirements.txt; to run tests/lint you also need requirements-dev.txt (see below).

Manual setup

# 1. Infrastructure (Postgres 5433, Mongo 27017, Qdrant 6333, Redis 6379)
docker compose up -d

# 2. Backend
cd backend
python -m venv .venv
source .venv/bin/activate            # Windows: .venv\Scripts\activate
pip install -r requirements.txt -r requirements-dev.txt
cp ../.env.example .env              # then edit as needed
alembic upgrade head
python -m app.scripts.seed_marketplace   # optional: featured teams
uvicorn app.main:app --reload        # http://localhost:8000

# 3. Frontend (new terminal)
cd frontend
cp .env.local.example .env.local
npm install
npm run dev                          # http://localhost:3000

Optional local models:

ollama pull qwen3.5:9b
ollama pull nomic-embed-text

Verification (matches CI)

Run these before opening a PR — CI runs exactly these:

Backend (backend/):

ruff check .
ruff format --check .
pytest

Frontend (frontend/):

npm run lint
npm run type-check
npm run build

The frontend has no test runner — do not add npm test without an issue. See Contributing-and-License.

Tests

• 68 test files under backend/tests/ (flat test_*.py) + conftest.py.
• asyncio_mode = "auto" (no @pytest.mark.asyncio needed).
• Tests run against SQLite via aiosqlite and fakeredis[lua] — no Docker required.
• Coverage spans agents/flow (test_agents_flow, test_main_agent_parallel, test_reviewer_rubric, test_quality_layer), the LLM layer (test_llm_layer_v2, test_llm_anthropic, test_token_accounting), the durable engine (test_task_engine, test_task_events, test_redis_bus), auth/security/2FA (test_auth_refresh, test_two_factor, test_url_guard, test_prompt_injection), billing/quota (test_quota_service, test_payment_card), email, marketplace, tools, and infra (test_rate_limiter, test_health, test_tracing, test_account_purge).

End-to-end manual smoke test

1. Register a user. With EMAIL_PROVIDER=console, the verification link is printed to the backend logs — open it to verify.
2. Subscribe on /settings/billing using the mock test card 4242 4242 4242 4242 (any future expiry / CVC). Without a subscription, POST /tasks returns 402.
3. Add a BYOK key on /settings/api-keys, or rely on local Ollama.
4. Start a task on /architect, watch the live graph and streamed synthesis.
5. Note: a single task emits two terminal events; with the slow qwen3.5:9b model the first subtasks can take a while.

See Configuration for all settings and Deployment for production.