Configuration reference

What this page covers: every setting you are likely to change when you install and run mmune, grouped by area. You set them as environment variables for the backend, in the .env file that sits next to the Compose file in your delivered package. This page tells you what each variable does, whether you must set it, and what happens when you leave it alone. It also lists the smallest set of values you need for a first start.

Related pages: Account and access explains the accounts, roles and license states that several of these settings control, and the API overview describes the HTTP interface.

How values are loaded

The backend reads its settings from environment variables when it starts. In a packaged install, Docker Compose takes the values from the .env file next to the Compose file and passes them into the containers. A container install is configured by environment variables alone, so there are no additional configuration files to edit. After you change a value, recreate the containers so the backend picks it up.

Leave an optional variable unset instead of writing KEY= with nothing after the equals sign. Compose passes a blank value on as an empty string, and several settings are parsed as numbers, so an empty string stops them from working. The example .env file in your package keeps optional keys commented out for this reason.

Most true or false settings accept 1, true, yes and on, in any letter case. A few accept only 1, true and yes, including MMUNE_AUTO_DUPLICATE_SCAN, MMUNE_HANA_SSL_VALIDATE and the three *_ROW_COUNT_EXACT settings. Use true and false when in doubt.

In the tables below, "Required" means the Compose file refuses to start, or the backend refuses to boot in prod mode, when the value is missing. Values in angle brackets, such as <GENERATE-A-STRONG-VALUE>, are placeholders you must replace.

Minimum settings for a first start

A production install needs these values before it will start.

Setting	What to put there
POSTGRES_PASSWORD, REDIS_PASSWORD, RABBITMQ_PASSWORD, GRAFANA_PASSWORD	A separate strong password for each service.
JWT_SECRET_KEY and APP_SECRET_KEY	Two different random values. See Generating strong values.
ENCRYPTION_KEY	A random key that protects stored credentials. Back it up.
MMUNE_ADMIN_PASSWORD and MMUNE_USER_PASSWORD	Strong passwords for the two initial accounts.
MMUNE_SCAN_TARGETS	The networks or hosts mmune should scan. The backend starts without it, but nothing is discovered.
A license	Deliver the license file with or before the first start. Without one, monitoring and AutoPilot do not run. See Licensing.

An AI provider key is optional. Without one, mmune uses its built-in pattern engine and still works.

Generating strong values

Generate each secret on a trusted machine and store it in your own secret store as well as the .env file.

# 64 hex characters, suitable for JWT_SECRET_KEY, APP_SECRET_KEY and ENCRYPTION_KEY
openssl rand -hex 32

# a random password or probe key
openssl rand -base64 24

Use a different value for every variable. Never reuse a password from another system.

Runtime mode

Variable	Required	Default	What it does
MMUNE_MODE	Optional	prod in the packaged Compose file	Set to prod. The backend runs only against your real systems and refuses to start with missing secrets.
MMUNE_LOG_RENDERER	Optional	json	Set to console for human-readable logs. Any other value gives JSON logs.

Authentication and security

Variable	Required	Default	What it does
JWT_SECRET_KEY	Required	none	Source of the session signing secret. Compose passes it to the backend as MMUNE_JWT_SECRET.
MMUNE_JWT_SECRET	Required in prod	taken from JWT_SECRET_KEY	Secret that signs sign-in tokens. In prod the backend refuses to issue or accept tokens without it.
MMUNE_JWT_SECRET_PREVIOUS	Optional	unset	The old signing secret, accepted for verification only while you rotate to a new one. New tokens always use MMUNE_JWT_SECRET. Remove it once old sessions have expired.
APP_SECRET_KEY	Required	none	Application secret that the Compose file requires you to set.
ENCRYPTION_KEY	Required	none	Key for the encrypted credential store. In prod the backend refuses to start without it. If you lose it, every stored credential becomes unreadable, so back it up. A 64-character hex value is accepted.
MMUNE_ADMIN_PASSWORD	Required in prod	none	Password of the initial administrator account. In prod the account is not created without it. Choose a strong, unique value.
MMUNE_USER_PASSWORD	Required in prod	none	Password of the initial read-only account. Choose a strong, unique value.
MMUNE_READ_ONLY	Optional	true	Blocks real script execution and hides agent tools that change things. Only an explicit false, 0 or no allows them.
MMUNE_PROBE_KEY	Optional	unset	Shared secret that probes present when they send heartbeats, in the X-Probe-Key header. While it is unset the heartbeat endpoint answers 503, so probe enrollment is closed.
CORS_ORIGINS	Optional	local development addresses only	Comma-separated list of browser origins allowed to call the API. Add the address users open the console at if it differs from MMUNE_API_URL.
MMUNE_RATE_LIMIT_GLOBAL_CALLS	Optional	6000	Requests allowed per window across all callers.
MMUNE_RATE_LIMIT_GLOBAL_PERIOD	Optional	60	Length of the global window in seconds.
MMUNE_RATE_LIMIT_PER_KEY_CALLS	Optional	18000	Requests allowed per window for one caller.
MMUNE_RATE_LIMIT_PER_KEY_PERIOD	Optional	3600	Length of the per-caller window in seconds.

In prod mode the backend also needs a reachable Redis, which it uses for rate limiting and for revoking tokens across replicas. It refuses to start without it.

Public URL and network binding

Variable	Required	Default	What it does
MMUNE_API_URL	Optional	http://localhost:8000 in the packaged Compose file	Public URL of the backend. The backend adds its origin to the allowed CORS origins. Standalone probe agents need it and exit when it is unset.
MMUNE_HTTP_BIND	Optional	127.0.0.1	Address the console's plain HTTP port 80 listens on. By default the only external listener is HTTPS on port 443. Setting 0.0.0.0 also serves the console over plain HTTP, which is suitable for a lab only.
MMUNE_TLS_CN	Optional	mmune.local	Common name and subject alternative name of the self-signed certificate created on first boot. For production, mount a certificate issued by your own certificate authority instead.
MMUNE_FRONTEND_BASE_URL	Optional	unset	Base address of the console, used to build links back to mmune inside tickets.

Database, cache and message broker

The packaged Compose file runs PostgreSQL, Redis and RabbitMQ for you and builds the connection strings from the values below.

Variable	Required	Default	What it does
POSTGRES_PASSWORD	Required	none	Password of the PostgreSQL service.
POSTGRES_USER	Optional	admin	PostgreSQL user created by the Compose file.
POSTGRES_DB	Optional	mmune_kb	Database name.
MMUNE_DATABASE_URL	Optional	built by Compose from the PostgreSQL values	Connection URL of the metadata database. Set it only to use an external PostgreSQL server, for example postgresql://<user>:<password>@db.example.local:5432/mmune_kb.
MMUNE_DB_POOL_SIZE	Optional	5	Database connection pool size. Raise it for large estates, because each concurrent monitoring check needs a connection.
MMUNE_DB_POOL_MAX_OVERFLOW	Optional	10	Extra connections allowed beyond the pool size.
REDIS_PASSWORD	Required	none	Password of the Redis service. Compose builds the Redis URL from it.
REDIS_URL	Optional	built by Compose	Connection URL of Redis. Set it to use an external Redis.
RABBITMQ_PASSWORD	Required	none	Password of the RabbitMQ service.
RABBITMQ_USER	Optional	mmune	RabbitMQ user created by the Compose file.
RABBITMQ_VHOST	Optional	mmune	RabbitMQ virtual host.
GRAFANA_PASSWORD	Required	none	Admin password of the bundled Grafana dashboards.

AutoPilot and discovery

AutoPilot onboards integrations without per-integration action from you. After you set the values below once, a backend restart drives discovery, registration and introspection, then lineage, semantic mappings and monitoring.

Variable	Required	Default	What it does
MMUNE_AUTOPILOT_ENABLED	Optional	true in the packaged Compose file	Starts the AutoPilot loop when the backend starts.
MMUNE_SCAN_TARGETS	Required for anything to onboard	empty	Comma-separated networks in CIDR form or host names to scan, for example 10.0.0.0/24,db01.example.local.
MMUNE_SCAN_PORTS	Optional	built-in list of common database and service ports	Replaces the built-in port list when set, for example 5432,1521.
MMUNE_SCAN_PORT_RANGE	Optional	unset	Extra port ranges to sweep in addition to the known ports, for example 1-1024,8000-9000. A range wider than about 5000 ports is skipped entirely rather than shortened.
MMUNE_EXTRA_DB_PORTS	Optional	unset	Extra port:provider hints for identifying services on non-standard ports, for example 1521:oracle,50000:db2.
MMUNE_AUTOPILOT_INTERVAL	Optional	120	Seconds between reconcile cycles. Values below 30 are raised to 30.
MMUNE_RESCAN_INTERVAL	Optional	3600	Seconds between full network re-scans for new systems. 0 turns periodic re-scans off.
MMUNE_CREDENTIAL_FILE	Optional	client-credentials.yaml	File name of your credential profile file. It sits next to the Compose file and is mounted read-only into the backend.
MMUNE_CREDENTIAL_PROFILES	Optional	the mounted credential file	Path inside the container of the credential profile file. mmune uses a matching profile from your credential file; if none matches, the integration is marked as needing credentials.
MMUNE_REGISTER_DETECTED_ONLY	Optional	false	By default, infrastructure endpoints that mmune detects are listed but not registered, so they use no license seat. Set to true to configure, test and register them too.
MMUNE_WATCHDOG_MAX_CONCURRENT	Optional	10	Most integration checks that run at the same time in one monitoring cycle. It limits parallelism, not how many integrations you can have.
MMUNE_ESTATE_LOAD_CEILING_PER_CYCLE	Optional	unlimited	Most sampling queries mmune sends to your monitored systems per cycle. Plain reachability checks are never limited by it.
MMUNE_AUTO_DUPLICATE_SCAN	Optional	false	Samples a small set of rows from the most identity-like table of each newly discovered PostgreSQL or MySQL system and runs duplicate detection on it.
MMUNE_AUTO_DUPLICATE_SCAN_ROWS	Optional	200	Rows sampled per automatic duplicate scan. The hard limit is 1000.

Licensing

mmune checks its license offline against a signed token, so it never contacts the vendor. A license in the valid or grace state allows monitoring. Without a valid license the backend still starts, but monitoring and AutoPilot stay off until a license is applied. An administrator can apply a renewal without restarting. The states and the renewal steps are described in Account and access.

Variable	Required	Default	What it does
MMUNE_LICENSE_FILE	Optional	/var/lib/mmune/license/mmune.license	Path of the license file inside the container. The path is on a persistent volume.
MMUNE_LICENSE	Optional	unset	The license token itself, as an alternative to the file. mmune checks a license stored by an earlier renewal first, then the file, then this variable.

AI providers and local models

mmune works without any AI key, using a built-in pattern engine. A key adds chat, semantic enrichment and orchestration. Set one or more providers and choose the default.

Variable	Required	Default	What it does
DEFAULT_AI_PROVIDER	Optional	gemini in the packaged Compose file	One of gemini, openai, claude or ollama. The aliases google_gemini, anthropic, anthropic_claude and local are also accepted. The air-gapped package pins it to ollama.
GEMINI_API_KEY	Optional	unset	Google Gemini key. GOOGLE_API_KEY is also accepted. GEMINI_DEFAULT_MODEL overrides the model.
OPENAI_API_KEY	Optional	unset	OpenAI key. OPENAI_DEFAULT_MODEL overrides the model, and OPENAI_API_BASE points mmune at an OpenAI-compatible gateway.
ANTHROPIC_API_KEY	Optional	unset	Anthropic key. ANTHROPIC_DEFAULT_MODEL overrides the model.
MMUNE_LOCAL_LLM_BASE_URL	Optional	unset	Base URL of any OpenAI-compatible local model server, for example http://ollama:11434/v1.
MMUNE_LOCAL_LLM_MODEL	Required with the base URL	unset	Chat model name on the local server. Without it the local provider is not registered and a warning is logged. The air-gapped package defaults it to qwen3:0.6b.
MMUNE_LOCAL_LLM_EMBED_MODEL	Optional	unset	Embedding model name, for local servers that serve embeddings.
MMUNE_LOCAL_LLM_API_KEY	Optional	local	Key sent to the local server. Most local servers ignore it.
MMUNE_LOCAL_LLM_TIMEOUT_SECONDS	Optional	120	Per-request timeout for the local model. If you raise it, also raise the read timeout of the web proxy in front of mmune (660 seconds by default), or a slow model can still produce a 504 error.
MMUNE_LOCAL_LLM_MAX_INFLIGHT	Optional	2	Most local requests that run at once. Extra requests wait their turn.
MMUNE_LOCAL_LLM_NUM_CTX	Optional	4096	Context size used to trim prompts before they reach the local model.
MMUNE_LLM_TIMEOUT_SECONDS	Optional	30	Per-attempt timeout for cloud providers. mmune retries failed calls.
MMUNE_LLM_ENRICHMENT_ENABLED	Optional	false	Adds AI enrichment on top of rule-based advisor findings. Findings marked as AI-generated need this on.
MMUNE_AI_BUDGET_DAILY_USD	Optional	unlimited	Daily ceiling on AI spend across mmune. Per-integration budgets saved in mmune take precedence.
MMUNE_AI_BUDGET_MONTHLY_USD	Optional	unlimited	Monthly ceiling on AI spend.
MMUNE_AI_COMPONENT_ROUTING	Optional	unset	JSON map from a component name to an ordered list of providers, for example {"chat": ["ollama"]}. Invalid JSON is ignored and a warning is logged.
MMUNE_AI_LOCAL_ONLY_COMPONENTS	Optional	unset	Comma-separated components that may only use the local model, for example chat,advisor. Use it to keep specific data off cloud providers.

To run a model on the same host, set DEFAULT_AI_PROVIDER=ollama together with the MMUNE_LOCAL_LLM_* values and start the stack with the local-llm Compose profile enabled. On a host with a GPU, use the GPU override file delivered with your package as well.

Monitoring and drift tuning

The monitoring samplers read these values at startup. Each sampler can be switched off with its *_ENABLED variable, which accepts 0, false or no. The defaults suit most estates.

Structure and value drift

Variable	Required	Default	What it does
MMUNE_REINTROSPECT_INTERVAL_SECONDS	Optional	300	How often each integration is read again to refresh lineage and detect structural drift.
MMUNE_VALUE_SAMPLE_ENABLED	Optional	true	Turns the value and semantic drift sampler on or off.
MMUNE_VALUE_SAMPLE_INTERVAL_SECONDS	Optional	300	Seconds between value drift samples.
MMUNE_VALUE_DRIFT_TABLES_PER_CYCLE	Optional	8	Tables sampled per integration per cycle. Each is a read-only aggregate query on the monitored database. The value must be a positive whole number.
MMUNE_VALUE_DRIFT_WARMUP_SAMPLES	Optional	5	Samples a field must collect before mmune evaluates it.
MMUNE_VALUE_DRIFT_SIGMA	Optional	3.0	Deviation, in standard deviations, that counts as out of range for a numeric field.
MMUNE_VALUE_DRIFT_SIGMA_CRITICAL	Optional	6.0	Deviation that raises a finding to critical.
MMUNE_VALUE_DRIFT_VOCAB_SHARE	Optional	0.05	Share of sampled rows with previously unseen category values that triggers a vocabulary-break finding.
MMUNE_VALUE_DRIFT_VOCAB_SHARE_CRITICAL	Optional	0.5	Share that raises the finding to critical.
MMUNE_VALUE_DRIFT_NULL_RATE_DELTA	Optional	0.2	Absolute rise in the share of empty values, compared with the baseline, that counts as a spike.
MMUNE_VALUE_DRIFT_NULL_RATE_DELTA_CRITICAL	Optional	0.5	Rise that raises the finding to critical.
MMUNE_VALUE_DRIFT_BOUNDS	Optional	unset	JSON map of schema.table.column to [low, high] numeric bounds, for example {"public.orders.amount": [0, 100000]}. Malformed JSON is ignored and a warning is logged.
MMUNE_DRIFT_REPORTS_RETENTION_DAYS	Optional	90	Days drift reports are kept.

Staleness and pipelines

Variable	Required	Default	What it does
MMUNE_STALENESS_SAMPLE_ENABLED	Optional	true	Turns on detection of tables whose row count stops changing, for PostgreSQL and MySQL.
MMUNE_STALENESS_SAMPLE_INTERVAL_SECONDS	Optional	300	Seconds between staleness samples.
MMUNE_STALENESS_AFTER_SECONDS	Optional	900	How long a row count may stay flat before the table is reported as stale.
MMUNE_FLOW_SAMPLE_ENABLED	Optional	true	Turns the TIBCO flow sampler on or off.
MMUNE_FLOW_SAMPLE_INTERVAL_SECONDS	Optional	120	Seconds between TIBCO flow samples.
MMUNE_KAFKA_FLOW_SAMPLE_ENABLED	Optional	true	Turns the Kafka consumer-lag sampler on or off.
MMUNE_KAFKA_FLOW_SAMPLE_INTERVAL_SECONDS	Optional	120	Seconds between Kafka samples.
MMUNE_KAFKA_LAG_THRESHOLD	Optional	1000	Lag at or above which a consumer group counts as stuck.
MMUNE_KAFKA_MAX_GROUPS_PER_CYCLE	Optional	20	Consumer groups sampled per cycle.
MMUNE_AIRFLOW_RUN_SAMPLE_ENABLED	Optional	true	Turns the Airflow run sampler on or off.
MMUNE_AIRFLOW_RUN_SAMPLE_INTERVAL_SECONDS	Optional	120	Seconds between Airflow samples.
MMUNE_AIRFLOW_CONSECUTIVE_FAILURES	Optional	3	Consecutive failed runs that raise a finding.
MMUNE_AIRFLOW_STUCK_MULTIPLE	Optional	3.0	A run counts as stuck when it takes longer than this multiple of its typical duration.

Scans, incidents and containment

Variable	Required	Default	What it does
MMUNE_ADVISOR_RESCAN_HOURS	Optional	24	Hours between full-estate advisor rescans. 0 turns them off.
MMUNE_SECURITY_SCAN_INTERVAL_HOURS	Optional	24	Hours between scheduled security scans.
MMUNE_AUTO_SCAN_ENABLED	Optional	true	Turns automatic security scans on or off.
MMUNE_AUTO_SCAN_STARTUP_DELAY_SECONDS	Optional	120	Delay before the first automatic scan after the backend starts.
MMUNE_AUTO_SCAN_DEBOUNCE_SECONDS	Optional	300	Quiet period before a scan triggered by a change runs.
MMUNE_AUTO_SCAN_DEBOUNCE_MAX_SECONDS	Optional	900	Longest a scan triggered by a change can be deferred.
MMUNE_INCIDENT_CORRELATION_WINDOW_HOURS	Optional	24	Window in hours used to group alerts into one incident. The minimum is 1.
MMUNE_INCIDENT_ANALYSIS_MODE	Optional	on_demand	One of off, on_demand or auto_on_open.
MMUNE_CONTAINMENT_MODE	Optional	off	One of off, observe or active. A value saved in the console takes precedence over this variable.
MMUNE_CONTAINMENT_SEVERITY_THRESHOLD	Optional	critical	Lowest severity that triggers containment.
MMUNE_IMPACT_COST_PER_RECORD	Optional	unset	Cost of one affected record, used in impact reports. Values saved in the console take precedence.
MMUNE_IMPACT_COST_PER_HOUR	Optional	unset	Cost of one hour of disruption, used in impact reports. Values saved in the console take precedence.

Source-system connectors

These settings apply to specific kinds of monitored systems. Set the ones that match your estate and leave the rest alone. Per-system details such as host, user and password normally go in your credential profile file rather than here.

Variable	Required	Default	What it does
MMUNE_HANA_SCHEMAS	Optional	the profile's database field	Comma-separated SAP HANA schemas to read. Point it at your application schema, not the system schema.
MMUNE_HANA_TENANT	Optional	the profile value	HANA tenant database name.
MMUNE_HANA_ENCRYPT	Optional	true	Set to false, 0 or no for a HANA system that has no TLS.
MMUNE_HANA_SSL_VALIDATE	Optional	true	Whether mmune validates the HANA server certificate. A value in the profile wins over this variable.
MMUNE_HANA_CA_CERT	Optional	unset	Path inside the container of the certificate authority file used to validate the HANA certificate.
MMUNE_ORACLE_SERVICE	Required if the profile does not give one	the profile value	Oracle service name.
MMUNE_ORACLE_SCHEMAS	Optional	the profile's schemas field	Comma-separated Oracle schemas to read. Use it to limit load on large estates.
MMUNE_POSTGRES_ROW_COUNT_EXACT, MMUNE_MYSQL_ROW_COUNT_EXACT, MMUNE_MONGODB_ROW_COUNT_EXACT	Optional	off	Use exact row counts instead of the database's own estimates. Exact counts put more load on the monitored database.
MMUNE_RABBITMQ_MGMT_PORT	Optional	15672	Management API port used when monitoring RabbitMQ.
MMUNE_TIBCO_TARGETS	Optional	empty	Comma-separated host[:ssh_port] list, each registered as a TIBCO integration. TIBCO is reached over SSH, so port scanning does not find it.
MMUNE_TIBCO_SSH_KEY_PATH	Optional	unset	Path inside the container of the SSH private key used to collect TIBCO data. A key set in the profile wins.
MMUNE_TIBCO_KNOWN_HOSTS	Optional	unset	Path inside the container of the known_hosts file. A host key that is not listed is rejected, not added automatically.
MMUNE_TIBCO_ELK_CA_CERT	Optional	unset	Certificate authority file for TIBCO's ELK log endpoint.
MMUNE_TIBCO_EMS_ADMIN_USER, MMUNE_TIBCO_EMS_ADMIN_PASSWORD	Optional	unset	Credentials for the EMS administration tool, used when the profile does not set them.

Alerts and notifications

For each channel, mmune uses the first match of a channel configuration saved in the console, then the environment, then the built-in default. Most channels are on by default, and ServiceNow is off. To turn a channel on or off, set MMUNE_NOTIFICATION_<CHANNEL>_ENABLED, where the channel is SLACK, WEBHOOK, PAGERDUTY, SERVICENOW, TEAMS or EMAIL_DIGEST.

Variable	Required	Default	What it does
MMUNE_SLACK_WEBHOOK_URL	Optional	unset	Slack incoming webhook URL.
MMUNE_TEAMS_WEBHOOK_URL	Optional	unset	Microsoft Teams webhook URL.
MMUNE_PAGERDUTY_ROUTING_KEY	Optional	unset	PagerDuty Events API v2 routing key.
MMUNE_ALERT_WEBHOOK_URL	Optional	unset	Address of a generic webhook that receives alerts.
MMUNE_ALERT_WEBHOOK_AUTH_TOKEN	Optional	unset	Token sent to the generic webhook. Without it, alerts are posted without authentication.
MMUNE_ALERT_WEBHOOK_AUTH_HEADER	Optional	Authorization	Name of the header that carries the token.
MMUNE_SMTP_HOST	Optional	unset	SMTP server for the email digest. The digest also needs recipients.
MMUNE_SMTP_TO	Optional	unset	Comma-separated recipients. Without recipients the digest is not configured.
MMUNE_SMTP_FROM	Optional	mmune@localhost	Sender address.
MMUNE_SMTP_PORT	Optional	587	SMTP port.
MMUNE_SMTP_USE_TLS	Optional	true	Use STARTTLS.
MMUNE_SMTP_USER, MMUNE_SMTP_PASSWORD	Optional	unset	SMTP credentials.
MMUNE_EMAIL_DIGEST_INTERVAL_HOURS	Optional	24	Hours between digests. The minimum is 0.1.
MMUNE_ALERT_MIN_SEVERITY	Optional	no minimum	Drops alerts below this severity. Accepts info, low, warning, medium, high and critical. An unrecognized value means no minimum.
MMUNE_ALERT_RETRY_MAX	Optional	3	Delivery attempts per channel.
MMUNE_ALERT_DEDUP_WINDOW	Optional	off	Seconds within which a repeat of the same alert is dropped.
MMUNE_ALERT_CIRCUIT_FAILURES	Optional	5	Consecutive failures that pause a channel.
MMUNE_ALERT_CIRCUIT_RESET_SECONDS	Optional	60	Cooldown before mmune tries a paused channel again.
MMUNE_ALERT_MAX_INFLIGHT_PER_CHANNEL	Optional	4	Deliveries allowed at the same time per channel.

Backup

Variable	Required	Default	What it does
MMUNE_BACKUP_RETENTION	Optional	14	Number of backups the backup script from your package keeps.
MMUNE_BACKUP_PASSPHRASE	Optional	unset	Strongly recommended. Encrypts the backup archive. Choose a strong value and store it apart from the backups.