Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.lumiqtrace.com/llms.txt

Use this file to discover all available pages before exploring further.

All environment variables are read by the API server at startup. There is no hot-reload — restart the server after changing any variable. The .env.example file in the repository root documents all variables with example values.

​
Required variables

These variables must be set for the server to start.
​
DATABASE_URL
string
required
PostgreSQL connection string. Format: postgresql://user:password@host:port/database
DATABASE_URL="postgresql://lumiq:lumiq@localhost:5432/lumiqtrace"
​
CLICKHOUSE_HOST
string
required
ClickHouse HTTP endpoint. Include the protocol and port.
CLICKHOUSE_HOST="http://localhost:8123"
​
CLICKHOUSE_USER
string
required
ClickHouse username.
​
CLICKHOUSE_PASSWORD
string
required
ClickHouse password. Can be empty for local development.
​
CLICKHOUSE_DB
string
required
ClickHouse database name.
CLICKHOUSE_DB="lumiqtrace"
​
REDIS_URL
string
required
Redis connection string.
REDIS_URL="redis://localhost:6379"
​
BETTER_AUTH_SECRET
string
required
Random secret used to sign authentication tokens. Must be at least 32 characters.
BETTER_AUTH_SECRET="a-very-long-random-string-of-at-least-32-characters"
Generate a suitable value: openssl rand -hex 32
​
BETTER_AUTH_URL
string
required
The base URL of the API server, used for auth callback URLs.
BETTER_AUTH_URL="https://api.yourdomain.com"
​
CORS_ORIGIN
string
required
Allowed CORS origins. Comma-separate multiple values.
CORS_ORIGIN="https://app.yourdomain.com"
# Or for multiple origins:
CORS_ORIGIN="https://app.yourdomain.com,https://staging.yourdomain.com"

​
AI model providers

At least one AI provider key is required to use LumiqPilot, Cost Optimizer, Anomaly Detection, and Root Cause Analysis.
​
ANTHROPIC_API_KEY
string
Anthropic API key. Used for LumiqPilot (cost optimization reasoning) and root cause analysis.
ANTHROPIC_API_KEY="sk-ant-..."
​
GOOGLE_GENERATIVE_AI_API_KEY
string
Google Generative AI API key. Used for LumiqPilot (function calling), anomaly explanations, and NLQ.
GOOGLE_GENERATIVE_AI_API_KEY="AIza..."
​
OPENAI_API_KEY
string
OpenAI API key. Used as a fallback AI provider for some features.
OPENAI_API_KEY="sk-..."
​
OPENROUTER_API_KEY
string
OpenRouter API key. Used for overview summaries via free models.
OPENROUTER_API_KEY="sk-or-..."

​
Email

​
RESEND_API_KEY
string
Resend API key for transactional email (account verification, alert notifications, team invitations). Without this, emails will not be sent.
RESEND_API_KEY="re_..."
​
EMAIL_FROM
string
default:"[email protected]"
The sender address for transactional emails.
EMAIL_FROM="[email protected]"

​
Payments (Polar.sh)

These variables are only required if you want to use the billing integration.
​
POLAR_ACCESS_TOKEN
string
Polar.sh API access token.
​
POLAR_ORGANIZATION_ID
string
Your Polar.sh organization ID.
​
POLAR_WEBHOOK_SECRET
string
Webhook signing secret from Polar.sh. Used to verify that webhook payloads originate from Polar.
​
POLAR_FREE_PLAN_PRODUCT_ID
string
Polar product ID for the Free plan.
​
POLAR_PRO_PLAN_PRODUCT_ID
string
Polar product ID for the Pro plan.
​
POLAR_TEAM_PLAN_PRODUCT_ID
string
Polar product ID for the Team plan.
​
POLAR_SCALE_PLAN_PRODUCT_ID
string
Polar product ID for the Scale plan.

​
LumiqPilot self-tracing

​
LUMIQPILOT_API_KEY
string
A LumiqTrace project API key used to trace LumiqPilot’s own AI calls. When set, Pilot’s model calls appear in your traces under the lumiqpilot agent tag.
​
LUMIQPILOT_PROJECT_ID
string
The project ID to associate with LumiqPilot self-traces.

​
Web app (frontend)

These variables are read by the Next.js web app container (apps/web). Create a separate .env.web or .env.local file for the web app.
​
NEXT_PUBLIC_API_URL
string
required
Base URL of the API server, used by the frontend for all API calls.
NEXT_PUBLIC_API_URL="https://api.yourdomain.com"
​
NEXT_PUBLIC_APP_URL
string
required
Public URL of the web app itself. Used for auth callback URLs and email links.
NEXT_PUBLIC_APP_URL="https://app.yourdomain.com"
​
NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY
string
Stripe publishable key for the billing UI. Only required if you are using the Polar/Stripe billing integration.

​
Optional server configuration

​
PORT
number
default:"3001"
Port the API server listens on.
​
LOG_LEVEL
string
default:"info"
Logging verbosity. Accepted values: fatal, error, warn, info, debug, trace.
​
RATE_LIMIT_MAX
number
default:"1000"
Maximum ingest requests per minute per API key.
​
SESSION_TTL_SECONDS
number
default:"604800"
Session token lifetime in seconds. Default is 7 days.
​
API_KEY_CACHE_TTL_SECONDS
number
default:"60"
How long to cache API key lookups in Redis before re-validating against the database.