Reference
Environment variables
The variables from .env.example, grouped by service.
Convex
| Variable | Purpose | Required |
|---|---|---|
| CONVEX_DEPLOYMENT | Deployment slug used by Convex CLI tooling (e.g. dev:my-project-123). Set automatically by npx convex dev. | Yes |
| NEXT_PUBLIC_CONVEX_URL | WebSocket/HTTP URL for the Convex deployment. Used by the browser client and must be publicly reachable. | Yes |
| NEXT_PUBLIC_CONVEX_SITE_URL | Base URL for Convex HTTP actions (e.g. the SSE chat endpoint). Distinct from the query/mutation URL. | Yes |
Clerk
| Variable | Purpose | Required |
|---|---|---|
| NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY | Clerk publishable key embedded in the browser bundle. Safe to expose — starts with pk_. | Yes |
| CLERK_SECRET_KEY | Server-side Clerk secret key. Never expose this in a NEXT_PUBLIC_ variable. Starts with sk_. | Yes |
| CLERK_JWT_ISSUER_DOMAIN | Issuer URL from the Clerk JWT template named convex. Convex verifies incoming tokens against this domain in auth.config.ts. | Yes |
| NEXT_PUBLIC_CLERK_SIGN_IN_URL | Path Clerk redirects to for sign-in. Set to /sign-in. | Yes |
| NEXT_PUBLIC_CLERK_SIGN_UP_URL | Path Clerk redirects to for sign-up. Also /sign-in since sign-up is colocated. | Yes |
| NEXT_PUBLIC_CLERK_SIGN_IN_FALLBACK_REDIRECT_URL | Where Clerk sends the user after sign-in when no redirectUrl param is present. Set to /dashboard. | Yes |
| NEXT_PUBLIC_CLERK_SIGN_UP_FALLBACK_REDIRECT_URL | Where Clerk sends the user after sign-up when no redirectUrl param is present. Set to /dashboard. | Yes |
- Use dev keys (pk_test_ / sk_test_) for local development.
- Switch to live keys (pk_live_ / sk_live_) for production. The JWT template must also be configured in the production Clerk instance.
Site URLs
| Variable | Purpose | Required |
|---|---|---|
| SITE_URL | Server-side canonical origin (e.g. http://localhost:3000). Used in server-only code and must not be prefixed NEXT_PUBLIC_. | Yes |
| NEXT_PUBLIC_SITE_URL | Browser-readable canonical origin. Must match SITE_URL. Clerk callback URLs and the Convex site URL must also match this value. | Yes |
Mistral (OCR)
| Variable | Purpose | Required |
|---|---|---|
| MISTRAL_API_KEY | Mistral API key used to call the OCR endpoint. Every PDF upload triggers an OCR job that uses this key. | Yes |
| MISTRAL_OCR_MODEL | OCR model identifier. Default is mistral-ocr-4-0. Change only if Mistral releases a newer model you want to test. | Yes |
OpenAI
| Variable | Purpose | Required |
|---|---|---|
| OPENAI_API_KEY | OpenAI API key for both embedding and chat generation. Used in Convex server functions — never exposed to the browser. | Yes |
| OPENAI_EMBEDDING_MODEL | Model for creating 1536-dim chunk embeddings. Default is text-embedding-3-small. | Yes |
| OPENAI_CHAT_MODEL | Model for routing, per-page summaries, document summaries, and grounded answer generation. Default is gpt-5.4-mini. | Yes |
| OPENAI_CHAT_REASONING_EFFORT | Reasoning effort for chat answers on reasoning models (minimal | low | medium | high). Lower effort makes tokens start streaming sooner; clamped to what the model supports. Default is low. | Yes |
Analytics (optional)
| Variable | Purpose | Required |
|---|---|---|
| NEXT_PUBLIC_POSTHOG_PROJECT_TOKEN | PostHog project token. Omit to disable analytics entirely. NEXT_PUBLIC_POSTHOG_KEY is supported as a fallback alias. | Optional |
| NEXT_PUBLIC_POSTHOG_HOST | PostHog ingest endpoint. Default is https://us.i.posthog.com. | Optional |