Local Development & Migrations

Want to hack on Scout locally or contribute a feature? Follow the steps below to run the backend, background worker, and frontend in development mode.

Prerequisites

Python 3.11–3.13 (managed via uv)
Node.js 18+ (Node 22+ recommended)
Goose CLI installed locally (goose configure)
SQLite (built-in fallback) or PostgreSQL (pgvector/pgvector:pg16 recommended)

1. Backend (FastAPI)

cd backend
# Install dependencies and sync virtual environment with uv
uv sync

cp ../.env.example .env
# Edit .env to set SESSION_SECRET, ENCRYPTION_KEY, and GOOGLE_API_KEY

# Start the FastAPI server with hot reload
uv run uvicorn app.main:app --reload --port 8000

2. Background Worker (Telegram ↔ Goose Poller & Scheduler)

In a second terminal, start the async worker that processes Telegram messages, scheduled reminders, and background subagents:

cd backend
uv run python -m app.worker

3. Frontend (React + TypeScript + Vite)

In a third terminal, start the Vite dev server:

cd frontend
npm install
npm run dev

Open http://localhost:5173 in your browser. Vite proxies /api requests to http://localhost:8000.

4. Database Migrations (Alembic)

Scout uses Alembic to manage database schema evolutions seamlessly across releases for both SQLite and PostgreSQL.

Automatic on Startup: Database migrations apply automatically whenever the application container or backend starts up (alembic upgrade head). Pre-Alembic databases are automatically detected, patched, and stamped.

Create a new migration:

cd backend
uv run alembic revision --autogenerate -m "add description to agents"

Apply migrations manually:
Terminal window
```
cd backend
uv run alembic upgrade head
```
Check current revision:
Terminal window
```
cd backend
uv run alembic current
```
Roll back the last migration:
Terminal window
```
cd backend
uv run alembic downgrade -1
```

5. Running Tests & Builds

# Run backend test suite
cd backend
uv run pytest

# Type-check and build frontend
cd frontend
npm run build

# Build documentation website
cd site
npm run build