Environment variables reference

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.

string

required

PostgreSQL connection string. Format: postgresql://user:password@host:port/database

DATABASE_URL="postgresql://lumiq:lumiq@localhost:5432/zespan"

string

required

ClickHouse HTTP endpoint. Include the protocol and port.

CLICKHOUSE_HOST="http://localhost:8123"

string

required

ClickHouse username.

string

required

ClickHouse password. Can be empty for local development.

string

required

ClickHouse database name.

CLICKHOUSE_DB="zespan"

string

required

Redis hostname (not a full redis:// URL, despite the name) — used together with REDIS_PORT, REDIS_USERNAME, and REDIS_PASSWORD below to connect. If unset, the API server starts without Redis (BullMQ queues, API-key caching, and rate limiting are disabled — not suitable for production).

REDIS_URL="localhost"
REDIS_PORT="6379"

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

string

required

The base URL of the API server, used for auth callback URLs.

BETTER_AUTH_URL="https://api.yourdomain.com"

string

required

Allowed CORS origins. Comma-separate multiple values. Rejected at startup if set to * in production.

CORS_ORIGIN="https://app.yourdomain.com"
# Or for multiple origins:
CORS_ORIGIN="https://app.yourdomain.com,https://staging.yourdomain.com"

Security and secrets

string

AES-256-GCM encryption key for BYOK (bring-your-own-key) LLM connection credentials — the API keys customers store when connecting their own OpenAI/Anthropic/etc. accounts via LLM Connections. Must be a 64-character hex string (32 bytes).If unset, the server falls back to SSO_SECRET and logs a warning. At least one of the two must be set to a valid 64-char hex string, or encryption calls throw. Set this explicitly and separately from SSO_SECRET in production so the two credential domains don’t share key material.

LLM_CONNECTION_SECRET="<64-char hex string>"
# Generate one with:
# node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"

string

Encryption key used for two purposes: (1) encrypting stored SSO/OIDC client secrets (see SSO), and (2) as the fallback encryption key for LLM_CONNECTION_SECRET if that variable is unset. Must be a 64-character hex string (32 bytes).

string

Server-side pepper mixed into project API key hashing before storage. Security-critical — treat like a database credential and never expose it to the client.

Secret used to sign CSRF-protection cookies. Falls back to BETTER_AUTH_SECRET if unset — set a dedicated value in production to keep session-signing and CSRF-cookie-signing keys isolated.

Cookie domain for the auth session and CSRF cookies. Set this when the web app and API live on different subdomains of the same parent domain (e.g. .yourdomain.com) so the session cookie is shared across them.

string

default:"1"

Origin-allowlist CSRF enforcement for state-mutating dashboard requests. Enabled by default; set to 0 to disable (not recommended in production).

Configure any of these provider pairs to enable that login method. See SSO for the Team/Scale-gated enterprise OIDC connector, which is configured per-organization rather than via env vars.

string

Google OAuth client ID for “Sign in with Google.”

string

Google OAuth client secret.

string

GitHub OAuth client ID for “Sign in with GitHub.”

string

GitHub OAuth client secret.

string

Microsoft OAuth client ID for “Sign in with Microsoft.”

string

Microsoft OAuth client secret.

string

Microsoft Entra ID (Azure AD) tenant ID to restrict sign-in to a specific tenant.

AI model providers

At least one AI provider key is required to use ZespanPilot, Cost Optimizer, Anomaly Detection, and Root Cause Analysis.

string

Anthropic API key. Used for ZespanPilot (cost optimization reasoning) and root cause analysis.

ANTHROPIC_API_KEY="sk-ant-..."

string

Google Generative AI API key. Used for ZespanPilot (function calling), anomaly explanations, and NLQ.

GOOGLE_GENERATIVE_AI_API_KEY="AIza..."

string

OpenAI API key. Used as a fallback AI provider for some features.

OPENAI_API_KEY="sk-..."

string

OpenRouter API key. Used for overview summaries via free models.

OPENROUTER_API_KEY="sk-or-..."

Email

string

Resend API key for transactional email (account verification, alert notifications, team invitations). Without this, emails will not be sent.

RESEND_API_KEY="re_..."

string

default:"noreply@zespan.com"

The sender address for transactional emails.

EMAIL_FROM="noreply@yourdomain.com"

Payments (Polar.sh)

These variables are only required if you want to use the billing integration. Note that Free has no Polar product (it’s the no-subscription default) and Scale is sold as a custom contract, so there is no POLAR_PRODUCT_* variable for either — only Solo, Pro, and Team map to real Polar products.

string

Polar.sh API access token.

string

default:"production"

Set to sandbox to use Polar’s sandbox environment during development/testing. Any other value (or unset) uses production.

string

Webhook signing secret from Polar.sh. Used to verify that webhook payloads originate from Polar.

string

Polar product ID for the Solo plan.

string

Polar product ID for the Pro plan.

string

Polar product ID for the Team plan.

string

Polar product ID used to bill extra seats beyond a plan’s included member count.

string

Polar usage-meter ID for reporting trace overage (traces ingested beyond the monthly quota) for billing.

string

URL Polar redirects to after a successful checkout.

string

URL the Polar customer portal returns to after the customer closes it. Falls back to {NEXT_PUBLIC_APP_URL}/settings/billing if unset.

Object storage (exports)

string

Cloudflare R2 account ID, used to store audit-log export files.

string

R2 access key ID.

string

R2 secret access key.

string

R2 bucket name for audit-log exports.

string

S3 bucket used for DSAR (data subject access request) data exports.

string

S3 bucket used to mirror audit-log records, if configured separately from R2_BUCKET.

string

default:"us-east-1"

AWS region for S3_BUCKET operations.

string

Path prefix used when writing audit-log export files to object storage.

number

default:"90"

Number of days audit log entries are retained before the retention worker purges them.

ZespanPilot

string

Default Gemini model ZespanPilot uses for its main reasoning loop.

string

Higher-capability model tier ZespanPilot escalates to for complex queries.

string

Mid-tier fast model ZespanPilot uses for routine queries.

string

Lightweight/cheapest model tier, used for simple or free-tier demo queries.

string

A Zespan project API key used to self-trace ZespanPilot’s own AI calls. When set, Pilot’s model calls appear in your traces under the zespanpilot agent tag.

string

Ingest URL ZespanPilot’s self-tracer sends spans to.

string

The project ID to associate with ZespanPilot self-traces.

number

default:"10"

Overrides how many free ZespanPilot demo queries a Free-plan organization gets per month.

number

default:"20"

Minimum recent spans a project must have before the free-tier ZespanPilot demo will answer a query (otherwise it responds with a warning instead of consuming a query).

Simulations

string

Set to allow simulation webhook/HTTP targets to resolve to private/internal IP ranges. Leave unset in production — this exists for local/self-hosted testing only.

string

Comma-separated hostname allowlist restricting which endpoints simulations are permitted to call.

number

Minutes after which a simulation batch with no progress is considered stuck and swept by the worker.

Workers

string

Restricts a worker process to a subset of BullMQ queues (e.g. ingest, evaluate, simulate, notify, billing). Omit to run all worker types in one process — set this per-process when you want to scale specific queues independently.

string

Optional separate PostgreSQL connection string for worker processes. Falls back to DATABASE_URL if unset — use this to point workers at a different connection pool/replica than the API server.

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.

string

required

Base URL of the API server. Used both by next.config.js to proxy /api/* requests to the Fastify backend (same-origin API calls in production) and by the frontend’s Axios client for direct calls.

NEXT_PUBLIC_API_BASE_URL="https://api.yourdomain.com"

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"

Optional server configuration

number

default:"3001"

Port the API server listens on.

string

default:"info"

Logging verbosity. Accepted values: fatal, error, warn, info, debug, trace.

string

Standard Node environment flag. Set to production to enforce production-only checks (e.g. rejecting a wildcard CORS_ORIGIN, using secure cookies).

number

Number of Node.js cluster workers the API process forks in production. Has no effect when NODE_ENV isn’t production or when running under Vitest.

number

default:"6379"

Redis port, paired with the REDIS_URL hostname above.

string

Redis username, if your Redis instance requires ACL auth.

string

Redis password.

AI Providers (BYOK)

Deployment

Security & Compliance

Account

Environment variables reference

Required variables

Security and secrets

AI model providers

Email

Payments (Polar.sh)

Object storage (exports)

ZespanPilot

Simulations

Workers

Web app (frontend)

Optional server configuration

​Required variables

​Security and secrets

​OAuth / SSO login providers

​AI model providers

​Email

​Payments (Polar.sh)

​Object storage (exports)

​ZespanPilot

​Simulations

​Workers

​Web app (frontend)

​Optional server configuration

Required variables

Security and secrets

OAuth / SSO login providers

AI model providers

Email

Payments (Polar.sh)

Object storage (exports)

ZespanPilot

Simulations

Workers

Web app (frontend)

Optional server configuration