Environment Variables Reference

All environment variables are validated at startup using Zod schemas defined in packages/server/src/config/env.ts. The server will exit with descriptive errors if validation fails.

Core

Variable	Required	Default	Description
NODE_ENV	No	development	development, production, or test
PORT	No	3000	HTTP server listen port
HOST	No	0.0.0.0	HTTP server bind address
LOG_LEVEL	No	info	error, warn, info, http, verbose, debug, silly

Database

Variable	Required	Default	Validation
MONGODB_URI	No	mongodb://localhost:27017/ai-gateway?replicaSet=rs0	Must be a valid URL
MONGODB_DB_NAME	No	ai-gateway	Non-empty string
REDIS_HOST	No	localhost	String
REDIS_PORT	No	6379	Positive integer
REDIS_PASSWORD	Prod	(empty)	Required in production
REDIS_DB	No	0	Non-negative integer

Authentication

Variable	Required	Default	Validation
JWT_SECRET	Yes	—	Minimum 16 characters. Must not contain placeholder values in production.
JWT_REFRESH_SECRET	Yes	—	Minimum 16 characters. Must not contain placeholder values in production.
JWT_ACCESS_EXPIRY	No	15m	Duration string (e.g., 15m, 1h)
JWT_REFRESH_EXPIRY	No	7d	Duration string (e.g., 7d, 30d)
ENCRYPTION_KEY	Yes	—	Exactly 64 hex characters (256-bit AES key). Sequential patterns rejected in production.

Super Admin Seed

Used by pnpm seed to create the initial administrator account.

Variable	Required	Default	Validation
SUPER_ADMIN_EMAIL	No	admin@ai-gateway.local	Valid email address
SUPER_ADMIN_PASSWORD	Yes	—	12+ characters, must include uppercase, lowercase, digit, and special character

Semantic Cache

Variable	Required	Default	Description
CACHE_EMBEDDING_MODEL	No	nomic-embed-text	Embedding model for cache similarity
CACHE_SIMILARITY_THRESHOLD	No	0.96	Cosine similarity threshold (0.0-1.0)
CACHE_DEFAULT_TTL_SECONDS	No	86400	Cache entry TTL in seconds (default: 24 hours)

Rate Limiting

Variable	Required	Default	Description
RATE_LIMIT_WINDOW_MS	No	60000	Window duration in milliseconds
RATE_LIMIT_MAX_PER_WINDOW	No	60	Max requests per window

CORS and Networking

Variable	Required	Default	Description
CORS_ORIGINS	No	(empty)	Comma-separated allowed origins (each must be a valid URL)
SOCKET_CORS_ORIGIN	No	http://localhost:3001	Socket.io CORS origin
ADMIN_URL	No	http://localhost:3001	Admin dashboard URL
SSO_CALLBACK_BASE_URL	No	(optional)	Base URL for SSO callback endpoints

Background Workers

Variable	Required	Default	Description
BULLMQ_PREFIX	No	aigw	Redis key prefix for BullMQ queues

S3 Backup

All S3 variables are optional. When not configured, audit log backups are stored locally.

Variable	Required	Default	Description
S3_BUCKET	No	—	S3 bucket name
S3_REGION	No	us-east-1	AWS region
S3_ACCESS_KEY_ID	No	—	AWS access key ID
S3_SECRET_ACCESS_KEY	No	—	AWS secret access key
S3_PREFIX	No	backups	Key prefix within the S3 bucket

SIEM Export

All SIEM variables are optional. When not configured, SIEM export is disabled.

Variable	Required	Default	Description
SIEM_TYPE	No	—	Export type: splunk, elk, or webhook
SIEM_URL	No	—	SIEM endpoint URL
SIEM_TOKEN	No	—	Authentication token
SIEM_BATCH_SIZE	No	100	Events per batch

Provider API Keys

Provider API keys are typically managed through the admin dashboard. They can also be set as environment variables, though dashboard-configured keys are encrypted at rest with AES-256-GCM.

OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...
GOOGLE_AI_API_KEY=AIza...
AZURE_OPENAI_API_KEY=...
AZURE_OPENAI_ENDPOINT=https://your-resource.openai.azure.com
GROQ_API_KEY=gsk_...
MISTRAL_API_KEY=...
COHERE_API_KEY=...
DEEPSEEK_API_KEY=...
TOGETHER_API_KEY=...
FIREWORKS_API_KEY=...
PERPLEXITY_API_KEY=pplx-...
AI21_API_KEY=...
HUGGINGFACE_API_KEY=hf_...
XAI_API_KEY=...
CEREBRAS_API_KEY=...
SAMBANOVA_API_KEY=...
REPLICATE_API_TOKEN=r8_...
ELEVENLABS_API_KEY=...
ASSEMBLYAI_API_KEY=...

Production Security Checks

When NODE_ENV=production, the server enforces additional validation at startup:

1. JWT_SECRET must not contain known placeholder strings
2. JWT_REFRESH_SECRET must not contain known placeholder strings
3. ENCRYPTION_KEY must not use sequential hex patterns (e.g., 0123456789abcdef repeated)
4. REDIS_PASSWORD must be set (non-empty)

If any check fails, the server exits with a descriptive error message.