Installation

Three deployments and a Postgres: the Next.js app, the NestJS API, and the research agent. Locally they run together under one command.

Prerequisites

• Bun
• Docker (for the bundled Postgres)

Quick start

git clone https://github.com/Hrida-AI/crm.git && cd crm
cp .env.example .env
bun install

docker compose up -d          # Postgres on :5432
bun run db:deploy             # apply migrations
bun run db:seed               # optional: a demo pipeline (idempotent)
bun run dev                   # everything, in watch mode

• App → localhost:3000
• API → localhost:3001
• Agent → 127.0.0.1:2000

The required values

Open .env and set these. Everything else in the file is optional and commented out — see Configuration.

Variable	What to put in it
DATABASE_URL	Already matches the docker compose Postgres — leave it unless you brought your own.
BETTER_AUTH_SECRET	openssl rand -base64 32. Signs session cookies; the API mints and the app verifies, so a mismatch is a redirect loop.
ALLOWED_SIGN_IN	Your email domain (acme.com) or a single address (you@gmail.com). This is the entire authorization model — an unset value means nobody can sign in.
GOOGLE_CLIENT_ID / GOOGLE_CLIENT_SECRET	A Google OAuth client. Both or neither. Optional if you sign in through SSO instead.

ALLOWED_SIGN_IN accepts whole domains, single addresses, or a mix:

ALLOWED_SIGN_IN="acme.com"                       # everyone at your company
ALLOWED_SIGN_IN="acme.com,contractor@gmail.com"  # …plus one outsider
ALLOWED_SIGN_IN="you@gmail.com"                  # a one-person install

Getting the Google OAuth client

1. Google Cloud console → Credentials → Create credentials → OAuth client ID → Web application.
2. Under Authorized redirect URIs, add http://localhost:3001/api/auth/callback/google.
3. Enable the Gmail API and the Calendar API.
4. Copy the client ID and secret into .env.

The same client is the sign-in button and the Gmail / Calendar sync. If your account is on a Google Workspace domain, set the consent screen to Internal — gmail.readonly is a restricted scope, and an External app using it needs OAuth verification plus an annual security assessment.

The agent model

The research agent has no compiled-in API key. Pick a provider and paste its key on Settings → General — OpenRouter, Anthropic, or a custom OpenAI-compatible endpoint. With no connection configured, the agent has no model to run on. See Agent model & providers.

Admin access

/admin-login is a second, separate door — email and password stored in this app's own database, independent of Google, SSO, or ALLOWED_SIGN_IN. It exists for getting into a workspace before any of those are configured. Registration is open to anyone who reaches the page and grants full workspace owner access, so decide whether to leave it reachable on a real deployment. See Authentication.

Common tasks

Command
bun run dev	Everything, in watch mode
bun run build	Build all apps and packages
bun run test	Run the test suite
bun run db:migrate	Create and apply a migration
bun run db:seed	Top up the demo pipeline (idempotent)
bun run db:studio	Prisma Studio
bun run --filter=agent dispatch	Drain the agent queue once, by hand (dev only)

Scope any of them with a Turborepo filter: bun run dev --filter=api.

Deploying

The three services are independent. The only things they must agree on are DATABASE_URL and BETTER_AUTH_SECRET. Set API_URL and APP_URL to the real origins; if the two are on different subdomains of one parent, set AUTH_COOKIE_DOMAIN to the parent. Add http://your-api-host/api/auth/callback/google to the OAuth client's redirect URIs. Set CRON_SECRET and point a scheduler at POST /internal/sync/google to keep the mailbox sync running. Details in Configuration.