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 |
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 |
MAZEVAULT_CA_FILE |
— |
PEM file (path inside the backend container) with the CA that issued the MazeVault server certificate. It is embedded into generated agent install scripts, which download the agent with it and install it as the agent's server_ca_file. Leave empty when agent hosts already trust the server certificate (enterprise CA): installers and agents then use the host's system trust store. Lookup order: MAZEVAULT_MTLS_CA_FILE, MAZEVAULT_CA_FILE, MAZEVAULT_CERT_FILE. In the Compose kit, place the file in CUSTOM_CERT_DIR (./certs) and set /custom-certs/ca.crt |
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 |
CACHE_TTL |
1m |
How long an OCSP response is cached (Go duration); also the longest a revocation can stay invisible |
CA_REFRESH_INTERVAL |
5m |
How often the responder reloads its certificate authorities (0 = only at start) |
TRUSTED_PROXIES |
— |
Comma-separated IPs/CIDRs of reverse proxies whose X-Forwarded-For the OCSP rate limiter believes (empty = peer address only) |
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 |
The frontend container also reads one runtime variable (no rebuild needed):
| Variable |
Default |
Description |
DOCS_URL |
https://${MAZEVAULT_DOMAIN}:8088 (Compose kit) |
Documentation portal link served to the UI at container start; set by both installers, docker-compose.yml and the Helm chart |
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 |
TRUSTED_PROXY_CIDRS |
(empty) |
Comma-separated CIDRs of reverse proxies. Only from them are X-Forwarded-For (client IP of CIDR-restricted roles) and the mTLS headers X-Client-Cert / ssl-client-cert accepted; the proxy must strip these headers from client requests |
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. The license server also answers the update check (see Maintenance); no GitHub token is needed.
| 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; 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 Binaries
The backend serves signed agent binaries to agents. It looks for them in this order: the directory bundled in the backend image (/opt/mazevault/agent-binaries/<version>/), the on-disk cache, then the MazeVault Harbor (OCI artifact), using temporary pull credentials issued by the license server. No registry credential is configured in the backend. A gateway has no license: instead of the Harbor it fetches missing versions from its primary, so AGENT_BINARY_REPOSITORY has no effect there.
| Variable |
Default |
Description |
AGENT_BINARY_CACHE_DIR |
/data/agent-binaries |
Local disk cache for downloaded agent binaries |
AGENT_BINARY_REPOSITORY |
agents/agent-binaries |
OCI repository with the agent binaries in Harbor; the agent packages (deb, rpm, msi) are read from agent-packages in the same project and cached under <AGENT_BINARY_CACHE_DIR>/packages |
AGENT_VERSION |
latest |
Deprecated. Seeds both channel targets of the agent version policy (latest = none) |
AGENT_MAX_ALLOWED_VERSION |
— |
Deprecated. Seeds the version ceiling of the agent version policy |
AGENT_ROLLOUT_PERCENTAGE |
100 |
Deprecated. Seeds both channels' rollout percentage (0–100) of the agent version policy |
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 |
Which agent version each agent is offered is set by the agent version policy (Deployment → Agents → Version policy, or GET/PUT /api/v1/agents/version-policy): a target, rollout percentage and pause per update channel (early, stable), a version ceiling, the rollback floor min_rollback_version and the mapping of environments to channels. AGENT_VERSION, AGENT_MAX_ALLOWED_VERSION and AGENT_ROLLOUT_PERCENTAGE are no longer read at request time: they only seed the policy on the primary's first start while no policy is stored, and log a deprecation warning while set. Gateways ignore them and apply the primary's policy. Remove them once the policy is set. Setting these variables after the policy exists only logs the deprecation warning. Downgrade warning: pinned AGENT_VERSION / AGENT_MAX_ALLOWED_VERSION values become policy targets and the ceiling, so agents running a higher version are offered a downgrade to them; to avoid it, clear the targets and ceiling in the version policy or set a minimum rollback version (min_rollback_version).
20. Gateway Stacks
The backend generates a Docker Compose stack and installer for each gateway deployment.
| Variable |
Default |
Description |
MAZEVAULT_IMAGE_REGISTRY |
registry.mazevault.com/mazevault |
Registry of the backend image in generated gateway stacks; set it to your mirror if gateways cannot pull from the MazeVault Harbor. The Compose kit defaults it to the installation's IMAGE_REGISTRY and the Helm chart to the registry of backend.image.repository. The image tag is the primary's own version. |
The generated stack requires MAZEVAULT_GATEWAY_ENVIRONMENT (see section on gateway mode): run the installer as root with sudo MAZEVAULT_GATEWAY_ENVIRONMENT=prod bash install.sh (the variable goes after sudo, which drops the caller's environment); it stores the value in the stack's .env.
21. SCEP
| Variable |
Default |
Description |
🔐 SCEP_CHALLENGE_PASSWORD |
— |
Shared challengePassword (RFC 8894) every SCEP enrolment at /api/v1/scep/<ca_id> must send; it applies to all internal CAs. Empty refuses every SCEP enrolment; GetCACaps and GetCACert keep working. In Helm set it through global.keyVault.secretKeys.scepChallengePassword. Setting it enables SCEP for every organization's internal CA, and anyone holding the value can enrol at any of them: in a multi-organization deployment set it only if all organizations trust each other, otherwise leave SCEP off. |