Configuration reference

MDMbox is configured through environment variables.

For the Prometheus listener and its environment variables, see Monitoring.

HTTP request size

Available from: 2610.0.

MDMbox accepts HTTP request bodies up to 64 MiB, including shared model definitions with population frequency parameters. Configure any reverse proxy or ingress in front of MDMbox to accept the model sizes you import or save. The MDMbox Helm chart accepts ingress controller settings through ingress.annotations.

License

MDMbox requires an active license. Choose an activation method:

1. Production and CI: obtain an MDMbox license from the portal and set MDMBOX_LICENSE in the MDMbox environment.
2. Local development: start MDMbox, open /mdmbox on your Aidbox address (http://localhost:8888/mdmbox in the local example), sign in to Aidbox, and click Sign in to activate to issue a development license with your portal account. Operations are available immediately after activation. The license is saved in the database and reused on restart. Replicas waiting for activation on the same database pick up the saved license automatically.

Before activation, MDMbox redirects API and Admin UI requests to its activation page. If an upgrade finds multiple previously saved MDMbox licenses, the page explains the ambiguity: set MDMBOX_LICENSE to the intended license and restart, or issue a new development license through the page.

An invalid, expired, or inactive configured or saved license prevents startup. Check the startup log for the verification error, set MDMBOX_LICENSE to a valid MDMbox license, and restart.

If a running instance's license expires or becomes inactive, MDMbox returns HTTP 403 with {"error":"MDMbox license verification failed"}. A temporary license portal outage allows a 24-hour grace period; requests receive the same HTTP 403 response after that period expires. Both /healthz and /readyz remain available while activation is pending or a running instance is restricted.

For Aidbox activation, see Aidbox licensing.

Aidbox URL

Pass Aidbox's BOX_WEB_BASE_URL to MDMbox as well. MDMbox uses the same public Aidbox address for the Activate Aidbox link in the Admin UI and the fullUrl values in $match and $referencing results. Use the address that users and API clients use to access Aidbox. With Helm, the existing aidboxConfigMap supplies it when the variable is present there.

The URL is required and has no default. An unset, empty, or invalid value prevents startup with an error naming BOX_WEB_BASE_URL. Use an absolute http:// or https:// URL without a query or fragment, for example https://aidbox.example.com. A deployment path such as https://example.com/aidbox is supported; trailing slashes are removed. This setting does not configure the database connection; supply BOX_DB_* separately.

The deprecated Aidbox alias AIDBOX_BASE_URL is also accepted. If both variables are present, BOX_WEB_BASE_URL takes precedence, as in Aidbox's Base URL setting. Set the same variable and value in both services; a shared ConfigMap avoids duplicating it.

Authentication

Authentication is enabled by default. Direct API requests use an Authorization header; the Admin UI uses the Aidbox browser session and AccessPolicies through App/mdmbox. See Authentication for setup and examples.

MDMBOX_ADMIN_ROLE is no longer used. UI access is granted by Aidbox AccessPolicies, including the initial policy created for MDMBOX_ADMIN_ID.

Audit

MDMbox automatically records operation audit events. See Audit for covered operations, querying, and retention.

Match operation

Merge and unmerge algorithms

Built-ins are enabled by default. Set MDMBOX_BUILT_IN_ALGORITHMS to a comma-separated allowlist such as simple,strict, or an empty value to disable all built-ins. IDs are case-sensitive; unknown IDs prevent startup. Restart after changing the setting.

Git and database scripts are configured separately. The default algorithm IDs are simple for merge and restore for unmerge. Make the selected default available as a built-in or custom script; an unavailable default returns HTTP 400.

Manage scripts and Git sources through Algorithms in the Admin UI. Runtime sources can be added and synchronized without restarting. The variables below configure a separate, reserved environment source:

Setting a Git environment option requires a valid URL. This source refreshes at startup; invalid configuration, unavailable revisions, authentication errors, or invalid scripts prevent startup. Runtime sources retain their last published scripts without fetching on startup.

See Algorithm management for setup, private access, precedence, and synchronization.

Shared database configuration

Set MDMbox's BOX_DB_* values to the database used by Aidbox. For Aidbox database and FHIR configuration, see the Aidbox settings reference.

PostgreSQL extensions

MDMbox requires the PostgreSQL extensions unaccent, fuzzystrmatch, and pg_trgm and installs missing extensions at startup. If your database account does not have permission to install extensions, ask your database administrator to install them before starting MDMbox.

MDMbox connection pools

MDMbox has a main connection pool for API and Admin UI traffic and a bulk pool for matching workers.

Both bulk matching jobs and continuous matching processes use the bulk pool. Each job or process reserves one connection per worker plus one for its coordinator, including during preparation. A Start that exceeds the bulk pool capacity is refused with HTTP 409. Include both pools, other applications and all replicas when sizing PostgreSQL's connection limit. See continuous matching deployment and upgrades for process handover and upgrade requirements.

HTTP Server

Logging

For example, add this to the MDMbox service in Docker Compose:

environment:
  MDMBOX_LOG_LEVEL: debug

With the Helm chart, set config.MDMBOX_LOG_LEVEL to the desired level. Restart the container after changing the setting. Empty or unsupported values prevent startup with an error.

Related Pages

• Getting started
• Authentication
• Find duplicates: $match

Model builder

Available from: 2610.0.

Model builder uses PostgreSQL to profile Patient records and store selected fields in a training table. By default it uses the configured MDMbox database. The workspace stores prepared data in the database and survives normal application restarts.

When using a separate database, supply any required credentials and TLS settings in the JDBC URL. The account must read public.patient and create the workspace schema, tables and matching functions. The database must provide the standard fuzzystrmatch, unaccent and pg_trgm extensions; Model builder installs missing prerequisites when the account has permission. No custom native extension is required.

The source override affects the builder workspace only. Saved models and online, Bulk and Continuous matching use MDMbox's configured database. The former MDMBOX_MODEL_BUILDER_DUCKDB setting is no longer used. See Model builder preview for preparation and upgrade steps.

AI assistant

Available from: 2610.0.

The Model builder assistant supports OpenAI and Anthropic. Configure one or both providers and restart MDMbox. A provider becomes available when both its key and model are set. Choose a model available to your provider account.

Provide keys through deployment secrets. The browser receives provider availability and model names, without keys. Kubernetes deployments can use the chart's extraEnvFromSecrets and extraEnvFromConfigMaps settings. The assistant sends messages, code, field names and aggregate counts to the selected provider when you send a request; it excludes sample records and REPL output. See AI assistant for the review workflow.