Gatewyse is configured through environment variables. Copy .env.example to .env and customize the values for your deployment.
Terminal window
cp.env.example.env
All environment variables are validated at startup using Zod schemas. The server will exit with a descriptive error if any required variable is missing or invalid.
MongoDB connection string. Single-node by default — see below.
MONGODB_DB_NAME
ai-gateway
Database name
REDIS_HOST
localhost
Redis hostname
REDIS_PORT
6379
Redis port
REDIS_PASSWORD
(empty)
Redis password (required in production)
REDIS_DB
0
Redis database number
Does MongoDB need a replica set?
Not for ordinary operation. Everything on the request path stays within a single
document, so nothing uses transactions or change streams and the default URI is
a plain single-node one — a bare mongod is enough for local development.
There is one exception. Encryption-key rotation re-encrypts several
collections and commits them together in a single transaction, because a
half-rotated deployment is split across two keys and unrecoverable. Transactions
require a replica set, and against a standalone instance the rotation refuses to
start rather than proceeding non-atomically — refusing is recoverable,
half-rotating is not.
Every shipped Compose file and the Helm chart start MongoDB with --replSet, so
this only affects a bare local instance.
Authentication
Variable
Default
Description
JWT_SECRET
(required)
JWT signing key, minimum 16 characters
JWT_REFRESH_SECRET
(required)
Refresh token signing key, minimum 16 characters
JWT_ACCESS_EXPIRY
15m
Access token lifetime
JWT_REFRESH_EXPIRY
7d
Refresh token lifetime
ENCRYPTION_KEY
(required)
AES-256-GCM key as 64-character hex string for API key encryption
Super Admin Seed
These are used by pnpm seed to create the initial admin account:
Variable
Default
Description
SUPER_ADMIN_EMAIL
admin@ai-gateway.local
Initial admin email
SUPER_ADMIN_PASSWORD
(required)
Must be 12+ chars with uppercase, lowercase, digit, and special character
Semantic Cache
Variable
Default
Description
CACHE_EMBEDDING_MODEL
nomic-embed-text
Model used for cache similarity matching
CACHE_SIMILARITY_THRESHOLD
0.96
Minimum cosine similarity for a cache hit (0.0-1.0)
CACHE_DEFAULT_TTL_SECONDS
86400
Cache entry time-to-live in seconds
Rate Limiting
Variable
Default
Description
RATE_LIMIT_WINDOW_MS
60000
Rate limit window in milliseconds
RATE_LIMIT_MAX_PER_WINDOW
60
Maximum requests per window
CORS and Networking
Variable
Default
Description
CORS_ORIGINS
(empty)
Comma-separated list of allowed CORS origins
SOCKET_CORS_ORIGIN
http://localhost:3001
Socket.io CORS origin
ADMIN_URL
http://localhost:3001
Admin dashboard URL
SSO_CALLBACK_BASE_URL
(optional)
Base URL for SSO callbacks
Background Workers
Variable
Default
Description
BULLMQ_PREFIX
aigw
BullMQ queue key prefix in Redis
S3 Backup (Optional)
Variable
Default
Description
S3_BUCKET
(optional)
S3 bucket name for audit log backups
S3_REGION
us-east-1
AWS region
S3_ACCESS_KEY_ID
(optional)
AWS access key
S3_SECRET_ACCESS_KEY
(optional)
AWS secret key
S3_PREFIX
backups
Key prefix within the bucket
SIEM Export (Optional)
Variable
Default
Description
SIEM_TYPE
(optional)
Export type: splunk, elk, or webhook
SIEM_URL
(optional)
SIEM endpoint URL
SIEM_TOKEN
(optional)
Authentication token for SIEM
SIEM_BATCH_SIZE
100
Number of events per batch export
Provider API Keys
Provider API keys are configured through the admin dashboard (or admin API) and stored in the deployment provider catalogue, encrypted at rest (an organization or department may override an entry with its own credential). The gateway reads them from the database at request time — it does not read OPENAI_API_KEY, ANTHROPIC_API_KEY, etc. from the environment for live routing. Names like the following are reference-only (local dev scripts / smoke tests):
Terminal window
OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...
GROQ_API_KEY=gsk_...
License & API Docs
Enterprise Edition startup is gated on a license (LICENSE_TOKEN, LICENSE_PUBLIC_KEYS, and the optional LICENSE_SERVER_URL / LICENSE_PHONE_HOME_INTERVAL_MS / LICENSE_GRACE_PERIOD_MS / GATEWYSE_LICENSE_FINGERPRINT). Swagger UI at /docs is controlled by ENABLE_SWAGGER (off by default). See Environment Variables for the full reference.
Production Checklist
In production mode (NODE_ENV=production), the server enforces additional security checks:
JWT_SECRET and JWT_REFRESH_SECRET must not contain placeholder values
ENCRYPTION_KEY must not be a sequential pattern
REDIS_PASSWORD must be set
SUPER_ADMIN_PASSWORD must meet complexity requirements
