Run from source

Running from source suits contributors and feature development; it is not equivalent to a production deployment. The backend uses Python 3.13, FastAPI, and Celery; the frontend uses Next.js 16 with Bun.

Base dependencies

Start PostgreSQL 17 + pg_search, Redis, and Qdrant 1.18.3. Copy the root .env.example to .env and set the database, Redis, Qdrant, backend/frontend URLs, and NEXT_PUBLIC_API_URL.

The repository ships a development compose file for the infrastructure:

cp .env.example .env
docker compose -f deploy/docker-compose.dev.yml --env-file .env up -d

Backend

Requires Python 3.13+ with uv. Install dependencies, then start the API, worker, and beat in separate terminals; the database initializes automatically on first run:

uv sync --project backend

uv run --project backend main.py server          # API, defaults to 127.0.0.1:8000
uv run --project backend main.py worker          # consumes default,agent,knowledge,workflow
uv run --project backend main.py beat

# Optional: only when you need code execution / sandbox features
uv run --project backend main.py sandbox-worker -c 1

The development service listens on API 8000; the OpenAPI page is at /docs. Useful development commands: uv run ruff check ., uv run ruff format ., and cd backend && uv run pytest.

Frontend

Requires Bun 1.0+. Install dependencies and start the development server (default port 3000):

bun install --cwd frontend
bun run --cwd frontend dev

For source development set NEXT_PUBLIC_API_URL=http://localhost:8000/api/v1. bun run --cwd frontend lint|build|test is available for validation.