Environment Variables Reference
Complete Reference for MazeVault Configuration Variables
Document Version: 1.0.0
Last Updated: 2026-10-28
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 |
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 |
TRUSTED_PROXY_CIDRS |
empty |
Comma-separated CIDRs of proxies whose X-Client-Cert / ssl-client-cert header is accepted as the mTLS client certificate. Empty (default) disables the header path, so only certificates presented directly in the TLS handshake are honoured. Not the same as TRUSTED_PROXIES (section 14), which controls client IP resolution |
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. Web Interface (Frontend and Edge)
The web interface is a Nuxt application with a built-in server (BFF). It reads its settings at container start (no rebuild needed); the former VITE_* variables no longer exist.
| Variable |
Default |
Description |
NUXT_CORE_API_URL |
Compose https://backend:8443; Helm http://<release>-backend:<backend.service.port> |
Backend address the BFF talks to. Set by the kit and the chart |
NUXT_CORE_API_SERVERNAME |
Compose MAZEVAULT_DOMAIN, else localhost; Helm not set |
Optional. TLS name by which the BFF verifies the backend certificate. The certificate must name it; for an IP MAZEVAULT_DOMAIN the installers and upgrade-mazevault.sh set it to localhost (see TLS Configuration) |
🔐 NUXT_BFF_SECRET |
from BFF_SHARED_SECRET |
Shared secret between the BFF and the backend, required. Set by the kit and the chart; do not set it separately |
NUXT_PUBLIC_ORIGIN |
Compose FRONTEND_URL (default https://localhost); Helm backend.urls.frontend, else https://<appHost> |
Address of the web interface exactly as the browser shows it (scheme, host and a non-default port). The BFF refuses state-changing requests whose Origin differs (403). With a custom FRONTEND_PORT, add the port here if FRONTEND_URL has none |
NUXT_PUBLIC_DOCS_URL |
Compose DOCS_URL, else https://${MAZEVAULT_DOMAIN}:8088; Helm frontend.urls.docs, else https://<docsHost> |
Documentation portal link shown in the UI. DOCS_URL is the deprecated name, still read for this release |
NODE_EXTRA_CA_CERTS |
Compose /certs/ca-bundle.crt; Helm not set |
CA bundle by which the BFF verifies an HTTPS backend. Must contain the leaf and its CA chain (see TLS Configuration). In Helm needed only for an HTTPS backend URL, through frontend.extraEnv |
FRONTEND_MEMORY_LIMIT |
256m |
Memory limit of the frontend container (Compose) |
EDGE_MEMORY_LIMIT |
64m |
Memory limit of the edge container (Compose) |
FRONTEND_PORT |
443 |
Host port of the edge for HTTPS (Compose) |
FRONTEND_HTTP_PORT |
80 |
Host port of the edge for the HTTP to HTTPS redirect (Compose) |
MAZEVAULT_SUBNET |
172.31.250.0/24 |
IPv4 subnet of the Compose network frontend (and the default of TRUSTED_PROXIES in Compose). Change it when it overlaps your address plan; the upgrade script checks it against Docker networks and host routes |
The edge container routes /api/ and /swagger to the backend and everything else to the frontend; see On-Premise Deployment.
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 |
🔐 BFF_SHARED_SECRET |
— |
Shared secret of the frontend server (BFF); the backend accepts server-side browser sessions (Authorization: Session) only with this value in the X-MazeVault-BFF header. At least 32 bytes (the installers generate 48 characters); a shorter value fails startup. Required by the Compose kit and by Helm while the frontend is enabled. Generated by install-mazevault.sh (and by upgrade-mazevault.sh when missing); in Helm set global.keyVault.secretKeys.bffSharedSecret. Secret: never put it in plain configuration |
UI_SESSION_IDLE_TIMEOUT |
30m |
Browser session idle timeout (Go duration) |
UI_SESSION_ABSOLUTE_TIMEOUT |
12h |
Browser session lifetime from login, regardless of activity |
UI_SESSION_MFA_TIMEOUT |
5m |
Time to complete MFA after a password login before the pending session expires |
MAZEVAULT_MFA_REQUIRED |
false |
Require MFA for all users |
MAZEVAULT_AUDIT_RETENTION_DAYS |
365 |
Audit log retention in days |
HSM_PKCS11_MODULES |
— |
Comma-separated absolute paths of the PKCS#11 libraries the server may load for PKCS#11 HSM devices. Empty (the default) refuses every PKCS#11 device: it cannot be created or changed (400), and an existing one is not loaded by the connection test, the health monitor or key routing. The library must also exist inside the backend container (mount it and list its in-container path). The module path of a device is loaded as native code by the server, so only the operator decides which libraries are allowed. At startup the log lists PKCS#11 devices whose module is not allowed. Set it before upgrading if you use PKCS#11 devices |
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 |
Serve the OpenAPI 3.1 document (/swagger/doc.json) and Swagger UI 5 (/swagger/index.html); any other non-empty value disables them |
SWAGGER_HOST |
— |
Host used for the "Try it out" server (https://<host>); when unset, the origin of FRONTEND_URL is used |
TRUSTED_PROXIES |
Backend and Helm: 127.0.0.1/32,::1/128,10.0.0.0/8,172.16.0.0/12,192.168.0.0/16,fc00::/7; Docker Compose kit: the value of MAZEVAULT_SUBNET |
Comma-separated CIDRs/IPs of proxies whose X-Forwarded-For is trusted when resolving client IPs (rate limits, audit log, zero-trust). In Compose the default is the kit subnet, where the edge runs: an external load balancer in front of the edge on another private range must be listed here, otherwise its X-Forwarded-For is ignored and the client IP becomes the proxy's. The subnet also contains the Docker bridge gateway (.1, e.g. 172.31.250.1): clients that reach the edge through Docker's port proxy (host-local clients, IPv6 clients on a dual-stack host) appear as that address, so a client-supplied X-Forwarded-For of theirs is trusted. Where that matters, list only the edge and frontend addresses instead of the whole subnet. In Helm set it to the pod CIDR of the ingress controller when that is not a private range; a proxy with a public IP must be listed explicitly. Warning: on networks where untrusted clients have private addresses (e.g. a corporate LAN reaching the server directly), a client can forge X-Forwarded-For and spoof its IP in audit log and rate limits; set TRUSTED_PROXIES to the exact edge/ingress (and later BFF) addresses or subnets. Not the same as TRUSTED_PROXY_CIDRS (section 8.4) |
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, 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, at most 11 (keytabs arrive base64-encoded in a JSON body, and request bodies are capped at 16 MiB); a larger value is treated as 11 |
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 |
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.