Environment Variables Reference
Complete Reference for MazeVault Configuration Variables
Document Version: 1.0.0
Last Updated: 2026-04-26
All MazeVault components are configured via environment variables. This page provides a centralized reference for all supported variables across backend, agent, gateway, and frontend.
Sensitive values
Variables marked with 🔐 contain secrets. Store them in a secrets manager or sealed Kubernetes secrets — never commit them to version control.
1. Core / Required
These variables must be set for the backend to start.
| Variable |
Example |
Description |
🔐 MAZEVAULT_MASTER_KEY |
base64:... |
Master encryption key for all secrets at rest |
🔐 MAZEVAULT_JWT_KEY |
base64:... |
JWT signing key for access tokens |
🔐 DATABASE_URL |
postgres://user:pass@host:5432/mazevault |
PostgreSQL connection string |
MAZEVAULT_LISTEN_ADDR |
:8443 |
Backend listen address and port |
MAZEVAULT_BASE_URL |
https://vault.example.com |
Public-facing URL of the platform |
2. Database
| Variable |
Default |
Description |
🔐 DATABASE_URL |
— |
Full PostgreSQL connection string |
DB_MAX_OPEN_CONNS |
25 |
Maximum open connections |
DB_MAX_IDLE_CONNS |
5 |
Maximum idle connections |
DB_CONN_MAX_LIFETIME |
5m |
Connection maximum lifetime |
🔐 ORACLE_PASSWORD |
— |
Oracle database password (required when using Oracle SQL integration) |
3. Authentication & SSO (Entra ID)
| Variable |
Default |
Description |
ENTRA_ENABLED |
false |
Enable Entra ID (Azure AD) SSO |
ENTRA_TENANT_ID |
— |
Azure AD tenant ID |
ENTRA_CLIENT_ID |
— |
Application (client) ID |
🔐 ENTRA_CLIENT_SECRET |
— |
Application client secret |
ENTRA_REDIRECT_URI |
— |
OAuth2 redirect URI |
ENTRA_SCOPES |
openid profile email |
Requested OAuth2 scopes |
ENTRA_AUTO_CREATE_USERS |
true |
Auto-provision users on first SSO login |
ENTRA_DEFAULT_ROLE |
viewer |
Default role for auto-provisioned users |
MAZEVAULT_ENFORCE_OIDC_NONCE |
false |
Enforce nonce validation on OIDC tokens — recommended true in production |
4. TLS
| Variable |
Default |
Description |
MAZEVAULT_TLS_ENABLED |
true |
Enable TLS for backend |
MAZEVAULT_TLS_CERT_FILE |
— |
Path to TLS certificate PEM file |
MAZEVAULT_TLS_KEY_FILE |
— |
Path to TLS private key PEM file |
MAZEVAULT_TLS_CA_FILE |
— |
Path to CA bundle for mTLS verification |
MAZEVAULT_TLS_MIN_VERSION |
1.2 |
Minimum TLS version (1.2 or 1.3) |
5. Encrypted Secrets Vault (Optional)
Variables for enabling the encrypted vault file as an alternative to .env for sensitive secrets. See Encrypted Secrets Vault for complete documentation.
| Variable |
Default |
Description |
MAZEVAULT_VAULT_FILE |
— |
Path to encrypted secrets.vault file. If not set, legacy .env mode is used |
MAZEVAULT_VAULT_KEY_FILE |
vault.key |
Path to vault passphrase file (on-premise mode) |
MAZEVAULT_VAULT_AKV_URL |
— |
Azure Key Vault URL for passphrase retrieval (Azure mode) |
MAZEVAULT_VAULT_AKV_SECRET |
mazevault-vault-key |
Name of the AKV secret containing the vault passphrase |
6. Email / SMTP
| Variable |
Default |
Description |
SMTP_ENABLED |
false |
Enable SMTP email sending |
SMTP_HOST |
— |
SMTP server hostname |
SMTP_PORT |
587 |
SMTP server port |
SMTP_FROM |
— |
Sender email address |
🔐 SMTP_USERNAME |
— |
SMTP authentication username |
🔐 SMTP_PASSWORD |
— |
SMTP authentication password |
SMTP_TLS |
true |
Use TLS for SMTP connection |
Office 365 (Optional — takes priority over SMTP when enabled)
| Variable |
Default |
Description |
O365_EMAIL_ENABLED |
false |
Enable Office 365 Graph API email sending (takes priority over SMTP) |
O365_TENANT_ID |
— |
Azure AD tenant ID |
O365_CLIENT_ID |
— |
App registration client ID (requires Mail.Send permission) |
🔐 O365_CLIENT_SECRET |
— |
Client secret (for client_secret auth method) |
O365_SENDER_EMAIL |
— |
Sender address (user or shared mailbox) |
O365_AUTH_METHOD |
client_secret |
Auth method: client_secret, certificate, managed_identity |
O365_CERTIFICATE_PATH |
— |
Path to PFX/PEM certificate (for certificate auth) |
🔐 O365_CERTIFICATE_PASSWORD |
— |
Certificate password (for certificate auth) |
O365_MANAGED_IDENTITY_CLIENT_ID |
— |
Managed Identity client ID (for managed_identity auth in Azure) |
7. Cache (Redis)
| Variable |
Default |
Description |
REDIS_URL |
— |
Redis connection string (redis://host:6379) |
🔐 REDIS_PASSWORD |
— |
Redis password (if authentication enabled) |
CACHE_TTL |
300 |
Default cache TTL in seconds |
8. Azure Gateway Mode
Variables for running MazeVault backend in gateway mode, connecting to a primary on-premise backend.
8.1 Core Gateway
| Variable |
Default |
Description |
MAZEVAULT_MODE |
primary |
Set to gateway to run in gateway mode |
PRIMARY_BACKEND_URL |
— |
URL of the on-premise primary backend (required in gateway mode) |
🔐 GATEWAY_BOOTSTRAP_TOKEN |
— |
One-time token for initial registration (generate from primary admin UI) |
GATEWAY_NAME |
— |
Human-readable name for this gateway instance |
MAZEVAULT_PRIMARY_ENVIRONMENTS |
— |
Comma-separated list of environments the primary backend serves directly (optional — seeds on first startup; subsequent changes via UI → Deployment → Gateways) |
8.2 Multi-Gateway Identity
| Variable |
Default |
Description |
MAZEVAULT_GATEWAY_ENVIRONMENT |
— |
Environment this gateway serves (NPR, PRO) |
MAZEVAULT_GATEWAY_ENVIRONMENTS |
— |
Multi-env mode: comma-separated list (overrides singular) |
MAZEVAULT_GATEWAY_ROLE |
primary |
Gateway role: primary or dr-standby |
MAZEVAULT_GATEWAY_STATE_FILE |
/etc/mazevault/gateway-state.json |
Path to persistent gateway state file |
MAZEVAULT_VERSION |
— |
Software version reported in heartbeats |
8.3 Azure Managed Identity
| Variable |
Default |
Description |
AZURE_MANAGED_IDENTITY_CLIENT_ID |
— |
Client ID of the Azure Managed Identity for Key Vault access |
8.4 mTLS & Security
| Variable |
Default |
Description |
MAZEVAULT_MTLS_CA_FILE |
— |
Path to custom CA certificate for mTLS verification |
GATEWAY_BOOTSTRAP_TTL |
24h |
TTL for bootstrap tokens (min 5m, max 24h) |
9. Agent
See also the Agent Deployment Guide for full details.
| Variable |
Default |
Description |
MAZEVAULT_SERVER_URL |
— |
Backend URL for agent communication |
🔐 MAZEVAULT_BOOTSTRAP_TOKEN |
— |
One-time registration token |
MAZEVAULT_AGENT_NAME |
hostname |
Agent display name in UI |
MAZEVAULT_PROJECT_ID |
— |
Project scope for secrets |
MAZEVAULT_CERT_STORE_PATH |
/var/lib/mazevault/certs |
Certificate store directory |
MAZEVAULT_STATE_DIR |
/etc/mazevault |
Configuration and state directory |
MAZEVAULT_LOG_LEVEL |
info |
Log level (debug, info, warn, error) |
MAZEVAULT_LOG_FORMAT |
text |
Log format (text, json) |
SYNC_INTERVAL_SECONDS |
300 |
Secret sync interval in seconds |
MAZEVAULT_AGENT_INSTALL_CHAIN_TO_TRUSTSTORE |
true |
Install the internal CA chain to the OS trust store on the agent host |
MAZEVAULT_AGENT_TRUST_STORE_PATH |
auto |
Override the default system trust store directory (Linux only; auto-detected if empty) |
10. OCSP Responder
| Variable |
Default |
Description |
OCSP_ENABLED |
false |
Enable the OCSP responder |
OCSP_LISTEN_ADDR |
:8888 |
OCSP responder listen address |
OCSP_CACHE_TTL |
300 |
OCSP response cache duration in seconds |
11. Multi-Datacenter
| Variable |
Default |
Description |
MAZEVAULT_DC_NAME |
— |
Datacenter identifier |
MAZEVAULT_DC_PRIMARY |
true |
Whether this is the primary DC |
MAZEVAULT_DC_REPLICAS |
— |
Comma-separated replica URLs |
MAZEVAULT_DC_SYNC_INTERVAL |
30s |
Cross-DC replication interval |
12. Frontend (Vite)
Frontend variables are embedded at build time. They must be prefixed with VITE_.
| Variable |
Default |
Description |
VITE_API_URL |
/api |
Backend API base URL |
VITE_WEBSOCKET_URL |
— |
WebSocket endpoint URL |
VITE_ENTRA_ENABLED |
false |
Show SSO login button |
VITE_DOCS_URL |
— |
Link to documentation portal |
VITE_SUPPORT_URL |
— |
Link to support portal |
13. Security Flags
| Variable |
Default |
Description |
MAZEVAULT_CORS_ORIGINS |
— |
Allowed CORS origins (comma-separated) |
MAZEVAULT_RATE_LIMIT |
100 |
API requests per minute per client |
MAZEVAULT_SESSION_TIMEOUT |
30m |
Session inactivity timeout |
MAZEVAULT_MFA_REQUIRED |
false |
Require MFA for all users |
MAZEVAULT_AUDIT_RETENTION_DAYS |
365 |
Audit log retention in days |
14. Deployment Mode
| Variable |
Default |
Description |
MAZEVAULT_ENV |
production |
Environment name (development, staging, production) |
MAZEVAULT_DEBUG |
false |
Enable debug mode (do not use in production) |
MAZEVAULT_LOG_LEVEL |
info |
Backend log level |
MAZEVAULT_LOG_FORMAT |
json |
Backend log format |
SWAGGER_ENABLED |
true |
Enable the Swagger UI at /swagger/index.html |
FRONTEND_URL |
https://localhost |
Public frontend URL — used for SSO redirect URIs and CORS configuration |
15. License / Organization Registration
Variables identifying the organization to the MazeVault license server on first startup.
| Variable |
Default |
Description |
MAZEVAULT_CUSTOMER_NAME |
— |
Organization display name (for license registration) |
MAZEVAULT_CUSTOMER_EMAIL |
— |
Admin contact email |
MAZEVAULT_COMPANY_ID |
— |
Company registration number |
MAZEVAULT_VAT_ID |
— |
VAT number — alternative to MAZEVAULT_COMPANY_ID |
MAZEVAULT_INSTANCE_ID |
auto |
Unique instance identifier (auto-generated if empty) |
MAZEVAULT_REGION |
EU |
Geographic region for license compliance (EU, US, APAC) |
16. Orchestrator Mode
Controls whether MazeVault stores sensitive values locally or offloads them to an external provider. Immutable after first initialization.
See Encryption — Orchestrator Mode for full details.
| Variable |
Default |
Description |
MAZEVAULT_ORCHESTRATOR_MODE |
false |
Enable Orchestrator Mode — secrets and private keys offloaded to Azure Key Vault, AWS Secrets Manager, or HashiCorp Vault; only metadata stored locally |
Immutable after initialization
Once the platform is initialized with MAZEVAULT_ORCHESTRATOR_MODE=true, this setting cannot be changed. Plan your deployment mode before first startup.
17. ACME DNS-01
Optional variables for wildcard certificate automation via DNS-01 challenge.
| Variable |
Default |
Description |
MAZEVAULT_ACME_DNS_PROVIDER |
none |
DNS provider for ACME DNS-01 challenges (cloudflare, none) |
🔐 MAZEVAULT_ACME_DNS_API_TOKEN |
— |
API token for DNS provider (encrypted at rest) |
18. KeyTab Management (v1.0.36+)
Optional variables for Kerberos KeyTab lifecycle management.
| Variable |
Default |
Description |
MAZEVAULT_KEYTAB_ENABLED |
true |
Enable the KeyTab management module |
MAZEVAULT_KEYTAB_MAX_SIZE_MB |
10 |
Maximum keytab file upload size in MB |
MAZEVAULT_KEYTAB_DEFAULT_EXPIRY_DAYS |
365 |
Default expiry period for newly imported keytabs |
19. Agent Binary Proxy (v1.0.39+)
Optional variables for serving agent binaries locally from a private GitHub repository instead of the public release endpoint.
| Variable |
Default |
Description |
🔐 AGENT_BINARY_GITHUB_TOKEN |
— |
Fine-grained PAT with Contents: Read on MazeVault/maze-release |
AGENT_BINARY_CACHE_DIR |
/data/agent-binaries |
Local disk cache directory for downloaded agent binaries |
AGENT_BINARY_RELEASE_API_URL |
https://api.github.com/repos/MazeVault/maze-release/releases |
GitHub Releases API URL |
AGENT_DOWNLOAD_BASE_URL |
https://github.com/MazeVault/maze-release/releases |
Base URL served to agents for binary downloads |
AGENT_VERSION |
latest |
Agent version to distribute (latest or vX.Y.Z) |
AGENT_ROLLOUT_PERCENTAGE |
100 |
Percentage of agents that receive update notifications (0–100) — deterministic per-agent bucketing |
AGENT_MAX_CONCURRENT_DOWNLOADS |
10 |
Maximum concurrent binary download streams |
MAZEVAULT_SERVER_URL |
— |
Public backend URL used as fallback for agent self-update download links when the reverse proxy does not propagate Origin/Host headers |