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	Must be a valid URL. See the note below on replica sets.
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

When a replica set is required

Ordinary operation does not need one — everything on the request path stays within a single document, and the default URI above is a standalone instance so local development works against a bare mongod.

Encryption-key rotation is the exception. It re-encrypts several collections and commits them in a single transaction, because a half-rotated deployment is split across two keys and cannot be recovered. Transactions require a replica set. Against a standalone instance the rotation refuses to start rather than proceeding non-atomically.

Every shipped compose file starts MongoDB with --replSet, so this only affects a bare local instance.

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	The origin the admin console is served from. The console opens a WebSocket for live dashboard and audit updates; if this does not match, the connection is refused and the console simply stops updating without reporting why.
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

Audit retention

Set on the worker, which is the only writer of audit entries.

Variable	Required	Default	Description
AUDIT_LOG_RETENTION_DAYS	No	365	Days an audit entry is kept before the TTL index removes it. 0 disables expiry entirely.

Set this before you start recording anything you need to keep

The retention window is stamped onto each entry as it is written, and that stamp is immutable. Changing this variable affects entries written afterwards only — it cannot extend the life of entries already on disk. A deployment that needs a year of history must set the window before the history it needs begins.

The worker logs the window it resolved at startup, so the effective value is visible in its first lines rather than something you have to infer. A malformed value is refused rather than silently replaced with the default.

Observability (OpenTelemetry)

All optional. When OTEL_EXPORTER_OTLP_ENDPOINT is unset, OpenTelemetry is a no-op with zero overhead. When set, the server and worker export traces, metrics, and logs over OTLP/HTTP; the collector base URL has /v1/{traces,metrics,logs} appended. See Observability for the full metric list and Grafana/Prometheus assets.

Variable	Required	Default	Description
OTEL_EXPORTER_OTLP_ENDPOINT	No	—	OTLP collector base URL (e.g. http://otel-collector:4318). Unset disables OpenTelemetry export.
OTEL_SERVICE_NAME	No	ai-gateway / ai-gateway-worker	Overrides the service.name resource attribute (worker defaults to ai-gateway-worker).
OTEL_METRIC_EXPORT_INTERVAL_MS	No	30000	Metric export interval in ms when OTLP is enabled.

For full ESM auto-instrumentation, start each process with node --import ./dist/telemetry/otel.js ./dist/index.js. Prometheus metrics remain available at GET /metrics regardless of OTLP configuration.

Encryption Key Source (KMS / BYOK)

Variable	Required	Default	Description
KEY_PROVIDER	No	env	Source of the data-encryption key. env uses ENCRYPTION_KEY. A misconfigured value fails loudly rather than silently falling back. (vault / awskms are extension points, not yet implemented.)

Budget Alert Delivery

All optional; a budget’s notifyVia channel is a no-op unless the matching variables are set. Delivery is best-effort and isolated per channel. See Budgets.

Variable	Required	Default	Description
SMTP_HOST	No	—	SMTP server host (enables email alerts).
SMTP_PORT	No	587	SMTP port.
SMTP_SECURE	No	false	Use TLS on connect (set true for port 465).
SMTP_USER	No	—	SMTP username.
SMTP_PASS	No	—	SMTP password.
SMTP_FROM	No	gatewyse@localhost	From address for alert emails.
BUDGET_ALERT_WEBHOOK_URL	No	—	Webhook endpoint for budget alerts (HMAC-signed when a secret is set).
BUDGET_ALERT_WEBHOOK_SECRET	No	—	Secret used to HMAC-sign webhook payloads.
SLACK_WEBHOOK_URL	No	—	Slack incoming-webhook URL for budget alerts.

License (EE)

The Enterprise Edition gates service on an Ed25519-signed license JWT issued by the 137 & Co. platform. If LICENSE_TOKEN is missing or invalid when NODE_ENV=production, the server still boots but locks out: every request except health probes, admin sign-in, and the licence endpoints is refused until a valid licence is installed. It never exits, so recovery never requires shell access.

Variable	Required	Default	Description
LICENSE_TOKEN	Prod	—	Ed25519-signed JWT issued by the 137 & Co. platform. Required in production.
LICENSE_PUBLIC_KEYS	When LICENSE_TOKEN is set	—	One or more PEM-encoded public keys joined with ;; (the double-semicolon delimiter is used because newlines inside env values are unreliable across shells and Docker).
LICENSE_SERVER_URL	No	—	Points the daily revocation check at the licence server; set it on every non-air-gapped deployment. Air-gap is a signed licence claim (Government edition), never a configuration setting — unsetting this does not make a deployment air-gapped.
LICENSE_PHONE_HOME_INTERVAL_MS	No	86400000	Polling interval (ms) for the revocation check. Default is 24 hours.
LICENSE_GRACE_PERIOD_MS	No	604800000	How long a revoked licence continues to serve before the deployment locks out. Default is 7 days, measured from the issuer’s revocation timestamp.
GATEWYSE_LICENSE_FINGERPRINT	No	—	Optional hardware-fingerprint override. Read directly via process.env in packages/license/src/fingerprint.ts (it is not part of the Zod env schema), because the license verifier runs before env validation. When set, it overrides the auto-derived machine fingerprint used for hardware-bound licenses.

The license verifier runs before the Zod env validator and Winston logger because both depend on environment that has not yet been validated at bootstrap time. For that reason LICENSE_* and GATEWYSE_LICENSE_FINGERPRINT are read straight from process.env and do not appear in the Zod env schema. See packages/server/src/services/license.service.ts for the boot sequence.

API Documentation

Variable	Required	Default	Description
ENABLE_SWAGGER	No	false	When true, exposes the Swagger UI at /docs. In production this is off by default; set to true to enable.

Provider API Keys

Provider API keys are managed through the admin dashboard (or the admin API) and stored in the deployment provider catalogue, encrypted at rest with AES-256-GCM — the gateway resolves them from the database at request time. There is no runtime code path that reads OPENAI_API_KEY, ANTHROPIC_API_KEY, etc. from the environment for live routing.

The variable names below are listed for reference only (e.g. for local development scripts, seeding, or smoke tests); setting them does not configure a provider for the gateway:

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.