Getting Started

Getting Started

Run Agora locally in a few minutes. The only hard requirement is a Postgres DATABASE_URL (a Supabase transaction-pooler URL by default).

Prerequisites

• Node 22+ and pnpm (pinned via corepack).
• A Postgres database — a Supabase project (default) or a local Postgres. Note: a local DB must be the supabase/postgres distribution, not a vanilla Postgres — Agora's migrations need its bundled extensions (pgvector, PostGIS, pgmq, pgcrypto) and the auth roles. See Deployment / self-hosting.

Quick start

corepack enable          # activate the pinned pnpm
pnpm install             # install all workspaces (from the repo root)
pnpm -r build            # build every package (contract first, topologically)

# Backend — the only hard requirement is a DATABASE_URL
cd apps/api
cp ../../.env.dev.example .env      # dev (host + cloud); see README -> Environment files
pnpm db:migrate:run       # apply migrations (idempotent; safe to re-run)
pnpm dev                  # http://localhost:4000/v7   (GET /health to verify)

# Admin dashboard (optional)
cd ../admin && pnpm dev   # http://localhost:5173

Use pnpm db:migrate:run (the runtime migrator the container uses), not db:migrate.

Environment

Each app loads its own .env from its package directory — for the API, cp ../../.env.dev.example .env in apps/api/. There is one complete template per run mode — .env.dev.example (host-run dev, above), .env.selfhost.example (container from source), and .env.prod.example (pulled prod image); see Deployment for which goes with which compose file. DATABASE_URL is the only hard requirement; everything else gates a specific feature and is validated as optional — e.g. SUPABASE_* (Auth + Storage), VOYAGE_API_KEY (semantic search), NEO4J_URI (the Social Graph), OPERATOR_USER_IDS/OPERATOR_EMAILS (the operator allowlist). The per-app layout (and an optional single-file setup) is in the repo README's Environment files section.

The deploy-oriented env reference lives in docs/CHEAT-SHEET.md, which maps each recipe to the variables it needs and where to obtain each value.

Running the whole ecosystem

Agora is one of three repos. To exercise the SDK end-to-end, run the server, seed a demo user, then run the agora-demo harness against it. The full local-dev walkthrough is in the repo CLAUDE.md and each app's README.

Next

• Architecture — how the pieces fit together.
• Deployment — Docker Compose and production recipes.
• The backend's own setup, configuration, and conventions: apps/api/README.md.