Configuration Reference

Complete reference for all environment variables used by the KaireonAI platform.

1. Quick Reference

Variable	Required	Default	Category
`DATABASE_URL`	Yes	—	Database
`REDIS_URL`	No	— (no-op cache when unset)	Cache
`NEXTAUTH_URL`	Yes (prod)	—	Authentication
`NEXTAUTH_SECRET`	Yes (prod)	—	Authentication
`JWT_SIGNING_SECRET`	Yes (prod)	—	Authentication
`CONNECTOR_ENCRYPTION_KEY`	Yes (prod)	—	Security
`WEBHOOK_SIGNING_SECRET`	Yes (prod)	—	Security
`API_KEY_PEPPER`	Yes (prod)	—	Security
`CORS_ALLOWED_ORIGINS`	Yes (prod)	—	Security
`LOG_LEVEL`	No	`info`	Observability
`NODE_ENV`	No	`development`	Runtime
`WORKER_CONCURRENCY`	No	`5`	Workers
`EVENT_PUBLISHER`	No	`redis`	Integration
`INTERACTION_STORE`	No	`pg`	Integration
`SEARCH_INDEX`	No	`pg`	Integration
`STORAGE_BACKEND`	No	`local`	Storage
`OTEL_EXPORTER_OTLP_ENDPOINT`	No	—	Observability

validateEnv() (src/lib/env-validation.ts) throws at startup in production if any of DATABASE_URL, NEXTAUTH_SECRET, JWT_SIGNING_SECRET, CONNECTOR_ENCRYPTION_KEY, WEBHOOK_SIGNING_SECRET, or API_KEY_PEPPER is missing, and if CORS_ALLOWED_ORIGINS is empty or *. In development these are warnings, not fatal.

2. Database

DATABASE_URL

PostgreSQL connection string used by Prisma via the @prisma/adapter-pg driver adapter.

Property	Value
Required	Yes
Default	—
Format	`postgresql://USER:PASSWORD@HOST:PORT/DATABASE?sslmode=require`
Example	`postgresql://kaireon:s3cret@db.example.com:5432/kaireon_prod?sslmode=require`

Notes:

In Prisma 7, this value is read from prisma.config.ts, not from the schema.prisma datasource block.
For RDS deployments, append ?sslmode=require and optionally &sslrootcert=/app/certs/rds-ca.pem.
Use IAM database authentication in production where possible.
Connection pooling is handled by the pg adapter; set connection_limit in the connection string if needed.

REDIS_URL

Redis connection string for caching. Optional — when unset the cache is a pass-through no-op and reads fall through to PostgreSQL.

Property	Value
Required	No
Default	— (cache disabled when not set)
Format	`redis://[:PASSWORD@]HOST:PORT[/DB]` or `rediss://` for TLS
Example	`rediss://:authtoken@cache.example.com:6379/0`

Notes:

Use rediss:// (double s) for TLS connections to ElastiCache.
For ElastiCache cluster mode, use the configuration endpoint.
The same Redis is used by the default EVENT_PUBLISHER=redis event bus.

3. Authentication

NEXTAUTH_URL

The canonical URL of the KaireonAI application. Used by NextAuth.js for callback URLs and CSRF protection.

Property	Value
Required	Yes
Default	—
Format	Full URL with protocol
Example	`https://app.kaireon.example.com`

Notes:

Must match the domain configured in your OAuth provider.
Do not include a trailing slash.
In development, use http://localhost:3000.

NEXTAUTH_SECRET

Secret used to encrypt NextAuth.js session tokens and CSRF tokens.

Property	Value
Required	Yes
Default	—
Format	Random string, minimum 32 characters
Example	`a1b2c3d4e5f6...` (use `openssl rand -base64 32` to generate)

Notes:

Must be identical across all application replicas.
Rotate every 180 days. See the security hardening guide for rotation procedures.
Store in AWS Secrets Manager, never in source control.

JWT_SIGNING_SECRET

Secret used to sign and verify JWT tokens for API authentication.

Property	Value
Required	Yes
Default	—
Format	Random string, minimum 32 characters
Example	`x9y8z7w6v5u4...` (use `openssl rand -base64 32` to generate)

Notes:

Used for service-to-service authentication and API key validation.
Must differ from NEXTAUTH_SECRET.
Support dual-key validation during rotation: the application accepts tokens signed with either the current or previous key.

4. Security

CONNECTOR_ENCRYPTION_KEY

AES-256 encryption key used to encrypt connector credentials (database passwords, API keys, OAuth tokens) at rest.

Property	Value
Required	Yes
Default	—
Format	32-byte hex string (64 hex characters) or base64-encoded 32 bytes
Example	`0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef`

Notes:

Used by the connector registry to encrypt sensitive configuration fields before storing in PostgreSQL.
Rotation requires re-encrypting all existing connector credentials. See the security hardening guide.
Generate with: openssl rand -hex 32.

WEBHOOK_SIGNING_SECRET

Secret used to sign and verify outbound/inbound webhook payloads (HMAC).

Property	Value
Required	Yes (production)
Default	—
Format	Random string, minimum 32 characters
Example	`openssl rand -base64 32`

Notes:

Required in production — validateEnv() throws at startup if unset.
Rotation is supported alongside the previous key during a cutover window.

API_KEY_PEPPER

Server-side pepper mixed into API-key hashing so stored key hashes are not reversible even if the database is exposed.

Property	Value
Required	Yes (production)
Default	—
Format	Random string, minimum 32 characters
Example	`openssl rand -base64 32`

Notes:

Required in production — validateEnv() throws at startup if unset.
Changing it invalidates all existing API-key hashes; rotate deliberately.

CORS_ALLOWED_ORIGINS

Comma-separated allowlist of browser origins permitted to call the API.

Property	Value
Required	Yes (production)
Default	—
Format	Comma-separated list of origins
Example	`https://app.kaireon.example.com`

Notes:

In production, validateEnv() throws if this is unset, empty, or * (wildcard origins are rejected as a security risk).
The legacy CORS_ORIGIN variable is not read by any code — use CORS_ALLOWED_ORIGINS.

5. Runtime

NODE_ENV

Node.js environment identifier. Controls Next.js build behavior, logging verbosity, and debug features.

Property	Value
Required	No
Default	`development`
Allowed	`development`, `production`, `test`
Example	`production`

Notes:

Set to production in all deployed environments (staging, production).
In development mode, Next.js enables hot module replacement and verbose error pages.
In production mode, error details are hidden from responses for security.

LOG_LEVEL

Controls the minimum severity level for application log output.

Property	Value
Required	No
Default	`info`
Allowed	`error`, `warn`, `info`, `debug`, `trace`
Example	`info`

Notes:

Use debug or trace only for troubleshooting. These levels generate high log volume.
In production, info is recommended. Use warn if log costs are a concern.
Log output is structured JSON when NODE_ENV=production.

WORKER_CONCURRENCY

Maximum number of concurrent pipeline tasks a single worker pod processes.

Property	Value
Required	No
Default	`5`
Format	Positive integer
Example	`8`

Notes:

Increase for CPU-heavy transform workloads on larger instances.
Each concurrent task consumes approximately 256 MiB of memory. Ensure the pod memory limit accommodates WORKER_CONCURRENCY * 256 MiB plus overhead.
Set to 1 for debugging pipeline issues in isolation.

6. Integration Backends

These variables control which backing services KaireonAI uses for event publishing, caching, interaction storage, and search. Each is read once at process startup and selects a process-wide singleton (src/lib/infra/container.ts), so changing one requires a restart. Sensible defaults (pg stores, redis event bus, no-op cache without REDIS_URL) keep a single-node deployment working without extra infrastructure.

Note: These backend selectors are environment-driven. Any in-app settings screens record operator preferences and audit entries — they do not repoint the live adapter. To change the active backend, set the env var (plus the per-backend variables) and restart.

EVENT_PUBLISHER

The event publishing backend for domain events (offer served, decision made, pipeline completed).

Property	Value
Required	No
Default	`redis`
Allowed	`redis`, `kafka`, `redpanda`, `msk`, `eventbridge`, `kinesis`
Example	`kafka`

Related variables by backend:

Backend	Additional Variables
`redis`	Uses `REDIS_URL` (shared with cache). Default when unset.
`kafka` / `redpanda`	`KAFKA_BROKERS`, `KAFKA_CLIENT_ID`, `KAFKA_TLS_ENABLED`, `KAFKA_SASL_MECHANISM`, `KAFKA_SASL_USERNAME`, `KAFKA_SASL_PASSWORD`, `KAFKA_CONSUMER_GROUP_ID`
`msk`	`MSK_BROKERS`, `MSK_REGION`, `MSK_AUTH_MODE`, `MSK_ROLE_ARN`, `MSK_SASL_USERNAME`, `MSK_SASL_PASSWORD`, `MSK_CONSUMER_GROUP_ID`, `MSK_TOPIC_PREFIX`
`eventbridge`	`EVENTBRIDGE_AUTH_MODE`, `EVENTBRIDGE_REGION`, `EVENTBRIDGE_ROLE_ARN`, `EVENTBRIDGE_BUS_NAME`, `EVENTBRIDGE_DETAIL_TYPE_PREFIX`
`kinesis`	`KINESIS_AUTH_MODE`, `KINESIS_REGION`, `KINESIS_ROLE_ARN`, `KINESIS_STREAM_NAME`, `KINESIS_PARTITION_KEY`

For AWS MSK with IAM authentication, set EVENT_PUBLISHER=msk and MSK_AUTH_MODE=iam_role (uses the pod’s IRSA role).

Cache backend (REDIS_URL)

The caching backend for decision results, feature vectors, and session data is selected by whether REDIS_URL is set.

Property	Value
Required	No
Default	Pass-through no-op cache when `REDIS_URL` is unset

Notes:

Without REDIS_URL, the cache is a pass-through no-op and all reads hit PostgreSQL directly. Suitable for low-traffic deployments.
With REDIS_URL, the platform uses Redis (or any Redis-compatible store, e.g., Dragonfly). Recommended for multi-replica deployments or >1000 req/s.
Use rediss:// for TLS.

INTERACTION_STORE

The storage backend for customer interaction history used by scoring engines.

Property	Value
Required	No
Default	`pg` (PostgreSQL)
Allowed	`pg`, `dynamodb`, `keyspaces`, `scylla` (aliases: `cassandra` → scylla, `aws_keyspaces` → keyspaces)
Example	`dynamodb`

Related variables by backend:

Backend	Additional Variables
`pg`	`DATABASE_URL` (shared)
`dynamodb`	`DYNAMODB_TABLE_NAME` (default `kaireon-interactions`), `DYNAMODB_REGION`, `DYNAMODB_AUTH_MODE`, `DYNAMODB_ROLE_ARN`, `DYNAMODB_ACCESS_KEY_ID`, `DYNAMODB_SECRET_ACCESS_KEY`
`keyspaces`	`KEYSPACES_KEYSPACE`, `KEYSPACES_REGION`, `KEYSPACES_AUTH_MODE`, `KEYSPACES_USERNAME`, `KEYSPACES_PASSWORD`, `KEYSPACES_REQUEST_TIMEOUT_MS`
`scylla`	`SCYLLA_CONTACT_POINTS`, `SCYLLA_LOCAL_DATACENTER`, `SCYLLA_KEYSPACE`, `SCYLLA_USERNAME`, `SCYLLA_PASSWORD`, `SCYLLA_TLS_ENABLED`, `SCYLLA_REPLICATION_FACTOR`, `SCYLLA_CONSISTENCY_LEVEL`, `SCYLLA_POOL_SIZE`, `SCYLLA_REQUEST_TIMEOUT_MS`

SEARCH_INDEX

The backend for full-text search across offers, blueprints, and connectors.

Property	Value
Required	No
Default	`pg` (PostgreSQL tsvector)
Allowed	`pg`, `opensearch`
Example	`opensearch`

Related variables by backend:

Backend	Additional Variables
`pg`	`DATABASE_URL` (shared, uses `tsvector` columns)
`opensearch`	`OPENSEARCH_NODE_URL`, `OPENSEARCH_INDEX_PREFIX`, `OPENSEARCH_AUTH_MODE`, `OPENSEARCH_REGION`, `OPENSEARCH_USERNAME`, `OPENSEARCH_PASSWORD`, `OPENSEARCH_TLS_ENABLED`, `OPENSEARCH_TLS_REJECT_UNAUTHORIZED`, `OPENSEARCH_MAX_RETRIES`, `OPENSEARCH_REQUEST_TIMEOUT_MS`

STORAGE_BACKEND

Blob store for AI-import attachments and related file payloads.

Property	Value
Required	No
Default	`local`
Allowed	`local`, `s3`
Example	`s3`

Related variables by backend:

Backend	Additional Variables
`local`	`ATTACHMENT_STORAGE_PATH` (local filesystem root)
`s3`	`ATTACHMENT_S3_BUCKET` (required when `STORAGE_BACKEND=s3` — startup throws if unset), `AWS_REGION`

Note on Sections 7-10: The default Helm configmap.yaml only passes through OTEL_EXPORTER_OTLP_ENDPOINT plus the CloudWatch log-group and region values. All other variables in sections 7-10 require manual addition to your Helm values override or direct environment variable injection. They are documented here for teams integrating with these services.

7. Observability

OTEL_EXPORTER_OTLP_ENDPOINT

Enables lightweight tracing of the decision pipeline. When set, the platform emits structured trace spans as JSON to stdout (compatible with Winston / log aggregation); when unset, tracing is a no-op with zero overhead.

Property	Value
Required	No
Default	— (tracing disabled when not set)
Format	URL with protocol and port
Example	`http://otel-collector.observability:4318`

Notes:

The platform does not bundle the OpenTelemetry SDK. The value is used only as an on/off switch — spans are written to stdout, not pushed to the endpoint over OTLP.
Because there is no OTLP exporter, the standard OTEL tuning variables (OTEL_SERVICE_NAME, OTEL_EXPORTER_OTLP_PROTOCOL, OTEL_TRACES_SAMPLER, OTEL_TRACES_SAMPLER_ARG) are not read by the platform.
When set, the decision pipeline emits spans for its stages (qualification, scoring, ranking, delivery, contact policy, budget check).

8. Kafka Integration (Manual Config)

These variables are required only when EVENT_PUBLISHER=kafka.

KAFKA_BROKERS

Comma-separated list of Kafka broker addresses.

Property	Value
Required	When `EVENT_PUBLISHER=kafka`
Default	—
Format	`host1:port,host2:port`
Example	`kafka-1.example.com:9092,kafka-2.example.com:9092`

KAFKA_SASL_USERNAME / KAFKA_SASL_PASSWORD

SASL/PLAIN credentials for authenticating with the Kafka cluster.

Property	Value
Required	When Kafka requires authentication
Default	—
Format	String
Example	`kaireon-producer` / `s3cret`

9. AWS Integration (Manual Config)

AWS_REGION

AWS region for SDK calls (DynamoDB, S3, SES, EventBridge, Kinesis).

Property	Value
Required	When using AWS-backed integrations
Default	`us-east-1`
Format	AWS region code
Example	`us-west-2`

DYNAMODB_TABLE_NAME

DynamoDB table name for interaction storage when INTERACTION_STORE=dynamodb.

Property	Value
Required	When `INTERACTION_STORE=dynamodb`
Default	`kaireon-interactions`
Format	String
Example	`kaireon-interactions-prod`

10. Search Integration (Manual Config)

OPENSEARCH_NODE_URL

OpenSearch cluster endpoint when SEARCH_INDEX=opensearch.

Property	Value
Required	When `SEARCH_INDEX=opensearch`
Default	`https://localhost:9200`
Format	URL with protocol
Example	`https://search.example.com:9200`

OPENSEARCH_INDEX_PREFIX

Prefix for OpenSearch index names.

Property	Value
Required	No
Default	`kaireon-`
Format	String
Example	`kaireon-prod-`

11. Example .env Files

Development

# Database
DATABASE_URL=postgresql://postgres:postgres@localhost:5432/kaireon_dev

# Auth
NEXTAUTH_URL=http://localhost:3000
NEXTAUTH_SECRET=<generate with: openssl rand -base64 32>
JWT_SIGNING_SECRET=<generate with: openssl rand -base64 64>

# Security
CONNECTOR_ENCRYPTION_KEY=<generate with: openssl rand -hex 32>

# Runtime
NODE_ENV=development
LOG_LEVEL=debug

# Backends (defaults shown — safe to omit)
EVENT_PUBLISHER=redis
INTERACTION_STORE=pg
SEARCH_INDEX=pg
STORAGE_BACKEND=local

Production (Minimal — PostgreSQL Only)

# Database (from Secrets Manager via ESO)
DATABASE_URL=postgresql://kaireon:ROTATED_PASSWORD@kaireon-db.abc123.us-east-1.rds.amazonaws.com:5432/kaireon?sslmode=require

# Auth (from Secrets Manager via ESO)
NEXTAUTH_URL=https://app.kaireon.example.com
NEXTAUTH_SECRET=ROTATED_SECRET_FROM_SECRETS_MANAGER
JWT_SIGNING_SECRET=ROTATED_SECRET_FROM_SECRETS_MANAGER

# Security (from Secrets Manager via ESO)
CONNECTOR_ENCRYPTION_KEY=ROTATED_KEY_FROM_SECRETS_MANAGER
WEBHOOK_SIGNING_SECRET=ROTATED_SECRET_FROM_SECRETS_MANAGER
API_KEY_PEPPER=ROTATED_SECRET_FROM_SECRETS_MANAGER
CORS_ALLOWED_ORIGINS=https://app.kaireon.example.com

# Runtime
NODE_ENV=production
LOG_LEVEL=info
WORKER_CONCURRENCY=8

# Observability (optional — enables JSON trace-span emission to stdout)
OTEL_EXPORTER_OTLP_ENDPOINT=http://otel-collector.observability:4318

Note: This minimal profile runs on PostgreSQL only. Without REDIS_URL the cache is a no-op and the default redis event publisher just logs a non-fatal connect warning (outbox rows still persist) — add REDIS_URL to enable caching and event publishing. Backends are selected by env vars at startup; AWS-backed backends use IAM roles (IRSA) by default on EKS.

Production (Full Infrastructure via Env Vars)

All backends selected explicitly via env vars:

# Database (from Secrets Manager via ESO)
DATABASE_URL=postgresql://kaireon:ROTATED_PASSWORD@kaireon-db.abc123.us-east-1.rds.amazonaws.com:5432/kaireon?sslmode=require

# Cache (enables the Redis cache and the default redis event bus)
REDIS_URL=rediss://:AUTH_TOKEN@kaireon-cache.abc123.use1.cache.amazonaws.com:6379/0

# Auth (from Secrets Manager via ESO)
NEXTAUTH_URL=https://app.kaireon.example.com
NEXTAUTH_SECRET=ROTATED_SECRET_FROM_SECRETS_MANAGER
JWT_SIGNING_SECRET=ROTATED_SECRET_FROM_SECRETS_MANAGER

# Security (from Secrets Manager via ESO)
CONNECTOR_ENCRYPTION_KEY=ROTATED_KEY_FROM_SECRETS_MANAGER
WEBHOOK_SIGNING_SECRET=ROTATED_SECRET_FROM_SECRETS_MANAGER
API_KEY_PEPPER=ROTATED_SECRET_FROM_SECRETS_MANAGER
CORS_ALLOWED_ORIGINS=https://app.kaireon.example.com

# Runtime
NODE_ENV=production
LOG_LEVEL=info
WORKER_CONCURRENCY=8

# Backends (selected at startup — restart to change)
EVENT_PUBLISHER=kafka
INTERACTION_STORE=pg
SEARCH_INDEX=opensearch

# Kafka (for AWS MSK use EVENT_PUBLISHER=msk with MSK_* vars + MSK_AUTH_MODE=iam_role)
KAFKA_BROKERS=kafka-1.example.com:9092,kafka-2.example.com:9092,kafka-3.example.com:9092
KAFKA_SASL_USERNAME=kaireon-producer
KAFKA_SASL_PASSWORD=FROM_SECRETS_MANAGER

# AWS
AWS_REGION=us-east-1

# Search (AWS OpenSearch — set OPENSEARCH_AUTH_MODE for IAM/IRSA auth)
OPENSEARCH_NODE_URL=https://search.example.com:9200
OPENSEARCH_INDEX_PREFIX=kaireon-prod-

# Observability (optional — enables JSON trace-span emission to stdout)
OTEL_EXPORTER_OTLP_ENDPOINT=http://otel-collector.observability:4318

​1. Quick Reference

​2. Database

​DATABASE_URL

​REDIS_URL

​3. Authentication

​NEXTAUTH_URL

​NEXTAUTH_SECRET

​JWT_SIGNING_SECRET

​4. Security

​CONNECTOR_ENCRYPTION_KEY

​WEBHOOK_SIGNING_SECRET

​API_KEY_PEPPER

​CORS_ALLOWED_ORIGINS

​5. Runtime

​NODE_ENV

​LOG_LEVEL

​WORKER_CONCURRENCY

​6. Integration Backends

​EVENT_PUBLISHER

​Cache backend (REDIS_URL)

​INTERACTION_STORE

​SEARCH_INDEX

​STORAGE_BACKEND

​7. Observability

​OTEL_EXPORTER_OTLP_ENDPOINT

​8. Kafka Integration (Manual Config)

​KAFKA_BROKERS

​KAFKA_SASL_USERNAME / KAFKA_SASL_PASSWORD

​9. AWS Integration (Manual Config)

​AWS_REGION

​DYNAMODB_TABLE_NAME

​10. Search Integration (Manual Config)

​OPENSEARCH_NODE_URL

​OPENSEARCH_INDEX_PREFIX

​11. Example .env Files

​Development

​Production (Minimal — PostgreSQL Only)

​Production (Full Infrastructure via Env Vars)

1. Quick Reference

2. Database

DATABASE_URL

REDIS_URL

3. Authentication

NEXTAUTH_URL

NEXTAUTH_SECRET

JWT_SIGNING_SECRET

4. Security

CONNECTOR_ENCRYPTION_KEY

WEBHOOK_SIGNING_SECRET

API_KEY_PEPPER

CORS_ALLOWED_ORIGINS

5. Runtime

NODE_ENV

LOG_LEVEL

WORKER_CONCURRENCY

6. Integration Backends

EVENT_PUBLISHER

Cache backend (REDIS_URL)

INTERACTION_STORE

SEARCH_INDEX

STORAGE_BACKEND

7. Observability

OTEL_EXPORTER_OTLP_ENDPOINT

8. Kafka Integration (Manual Config)

KAFKA_BROKERS

KAFKA_SASL_USERNAME / KAFKA_SASL_PASSWORD

9. AWS Integration (Manual Config)

AWS_REGION

DYNAMODB_TABLE_NAME

10. Search Integration (Manual Config)

OPENSEARCH_NODE_URL

OPENSEARCH_INDEX_PREFIX

11. Example .env Files

Development

Production (Minimal — PostgreSQL Only)

Production (Full Infrastructure via Env Vars)