Installation

Prerequisites

• Node.js 20+ (22 recommended)
• Docker (for the PostgreSQL + pgvector database) — or your own Postgres 16 with the vector extension
• An AI provider API key (OpenAI, Anthropic or Google) to use the chat. Google Gemini has a free tier and is the default.

One-command setup (recommended)

npm installnpm run setup

npm run setup is idempotent and:

1. Creates .env from .env.example and generates a BETTER_AUTH_SECRET.
2. Starts the database container.
3. Waits for it to be healthy.
4. Applies migrations.
5. Seeds the demo account.

Then start the app:

npm run dev

Open http://localhost:3000.

Manual setup

If you prefer to run the steps yourself:

npm installcp .env.example .env          # then edit .env (see below)docker compose up -d db       # start Postgres + pgvectornpm run db:migrate            # apply the schemanpm run db:seed               # create the demo accountnpm run dev

Generate an auth secret for .env:

openssl rand -base64 32

Verify it works

• Visit / and click View live demo → you land on the dashboard as the demo user.
• Or sign up at /signup with your own email.
• Add an AI provider key to .env (see AI providers) to chat.

Troubleshooting

• Port 5432 already in use — a local Postgres is running. Set DB_POSTGRES_PORT in .env (e.g. 5433) and update the port in DATABASE_URL.
• npm run setup fails — make sure Docker Desktop is running.
• Env validation error on boot — a required variable is missing; check .env against Environment variables.