Configuration Reference

All Shell API vars use the APP_ENV_ prefix. Validated with Zod at startup (shell/api/src/config/env.config.ts) — missing required vars cause an immediate startup failure with a clear error message.

All variable names at a glance

APP_ENV_HOST
APP_ENV_PORT
APP_ENV_SERVER_BASE_PATH
APP_ENV_NODE_ENV
APP_ENV_DATABASE_URL
APP_ENV_REDIS_URL
APP_ENV_MINIO_ENDPOINT
APP_ENV_MINIO_ACCESS_KEY
APP_ENV_MINIO_SECRET_KEY
APP_ENV_JWT_SECRET
APP_ENV_JWT_ISSUER
APP_ENV_JWT_AUDIENCE
APP_ENV_KEYCLOAK_URL
APP_ENV_KEYCLOAK_INTERNAL_URL
APP_ENV_KEYCLOAK_REALM
APP_ENV_KEYCLOAK_CLIENT_ID
APP_ENV_KEYCLOAK_CLIENT_SECRET
APP_ENV_KEYCLOAK_REDIRECT_URI
APP_ENV_GOOGLE_CLIENT_ID
APP_ENV_GOOGLE_CLIENT_SECRET
APP_ENV_API_URL
APP_ENV_FRONTEND_URL
APP_ENV_SURE_GRPC_URL
APP_ENV_HRM_GRPC_URL
APP_ENV_REPORT_GRPC_URL
APP_ENV_GRPC_URLS
APP_ENV_STRIPE_SECRET_KEY
APP_ENV_STRIPE_WEBHOOK_SECRET
APP_ENV_STRIPE_PUBLISHABLE_KEY
APP_ENV_CORS_ORIGINS
APP_ENV_LOG_PATH
VITE_API_URL

---

All variables

Variable	Default	Req	Description
APP_ENV_HOST	0.0.0.0		Bind address
APP_ENV_PORT	3000		HTTP port
APP_ENV_SERVER_BASE_PATH	/api		Route prefix for all endpoints
APP_ENV_NODE_ENV	development		development | production | test
APP_ENV_DATABASE_URL	—	required	PostgreSQL connection string
APP_ENV_REDIS_URL	redis://localhost:6379		Redis URL (PKCE state, token blacklist)
APP_ENV_MINIO_ENDPOINT	http://localhost:9000		MinIO / S3-compatible endpoint
APP_ENV_MINIO_ACCESS_KEY	—	optional	MinIO access key
APP_ENV_MINIO_SECRET_KEY	—	optional	MinIO secret key
APP_ENV_JWT_SECRET	—	required	HS256 signing secret — minimum 32 characters
APP_ENV_JWT_ISSUER	—	optional	JWT iss claim
APP_ENV_JWT_AUDIENCE	—	optional	JWT aud claim
APP_ENV_KEYCLOAK_URL	http://localhost:8080		Public Keycloak URL — sent to browser for PKCE redirect
APP_ENV_KEYCLOAK_INTERNAL_URL	(falls back to KEYCLOAK_URL)		Internal Keycloak URL — server-side token exchange and JWKS
APP_ENV_KEYCLOAK_REALM	veni-ai		Keycloak realm name
APP_ENV_KEYCLOAK_CLIENT_ID	veni-ai-platform		Keycloak client ID
APP_ENV_KEYCLOAK_CLIENT_SECRET	—	optional	Required for confidential clients only
APP_ENV_KEYCLOAK_REDIRECT_URI	http://localhost:3000/api/auth/callback		OAuth callback URL (must match Keycloak client)
APP_ENV_GOOGLE_CLIENT_ID	—	optional	Google OAuth client ID
APP_ENV_GOOGLE_CLIENT_SECRET	—	optional	Google OAuth client secret
APP_ENV_API_URL	http://localhost:3000		Public API URL (used in OAuth redirects and emails)
APP_ENV_FRONTEND_URL	http://localhost:5173		Frontend URL (default CORS origin)
APP_ENV_SURE_GRPC_URL	http://localhost:3008/api		Sure service gRPC URL
APP_ENV_HRM_GRPC_URL	http://localhost:3001/api		HRM service gRPC URL
APP_ENV_REPORT_GRPC_URL	http://localhost:3002/api		Report service gRPC URL
APP_ENV_GRPC_URLS	—	optional	JSON map of additional service URLs: {"slug":"http://host/api"}
APP_ENV_STRIPE_SECRET_KEY	—	optional	Stripe secret key (sk_...)
APP_ENV_STRIPE_WEBHOOK_SECRET	—	optional	Stripe webhook signing secret (whsec_...)
APP_ENV_STRIPE_PUBLISHABLE_KEY	—	optional	Stripe publishable key — returned to frontend via /api/config
APP_ENV_CORS_ORIGINS	(see below)		Comma-separated allowed origins. Defaults to FRONTEND_URL, localhost:5173, localhost:3000
APP_ENV_LOG_PATH	/tmp		Directory for log files. Must be /tmp in K8s (readOnlyRootFilesystem: true)

---

Shell UI

Variable	Required	Description
VITE_API_URL	required	Full API base URL including /api path

# shell/ui/.env.local
VITE_API_URL=http://localhost:3000/api

---

Redis password format in K8s

# K8s — note the colon before the password
APP_ENV_REDIS_URL=redis://:mypassword@redis:6379
# Local (no auth)
APP_ENV_REDIS_URL=redis://localhost:6380

Dual Keycloak URL in K8s

Set APP_ENV_KEYCLOAK_URL to the public HTTPS URL (browser-facing) and APP_ENV_KEYCLOAK_INTERNAL_URL to the internal cluster service URL (server-side token exchange). In local dev, set both to http://localhost:8080.