General settings

Aidbox name

Aidbox instance unique ID. Can be used to separate telemetry data (logs, metrics, traces) in observability systems for multiple deployments.

IDbox-id
TypeString
Default valuedevbox
Environment variableBOX_ID
Deprecated environment variablesAIDBOX_BOX_ID
Sensitivefalse — value will be visible in plaintext in Admin UI
Set viaEnvironment variables
Hot reloadfalse — setting requires system restart

Instance name

Provided instance name will be attached to metric labels. It is required for monitoring multiple Aidbox instances.

IDinstance-name
TypeString
Default valueAidbox
Environment variableBOX_INSTANCE_NAME
Sensitivefalse — value will be visible in plaintext in Admin UI
Set viaAdmin UI → Settings
Environment variables
Hot reloadtrue — setting can be changed at runtime

Root FHIR package

Identifier for the main Aidbox FHIR package that stores dependencies and canonical resources provided by the user.

IDroot-fhir-package
TypeString
Default valueapp.aidbox.main#0.0.1
Environment variableBOX_ROOT_FHIR_PACKAGE
Deprecated environment variablesAIDBOX_AR_PACKAGE
Sensitivefalse — value will be visible in plaintext in Admin UI
Set viaAdmin UI → Settings
Environment variables
Hot reloadfalse — setting requires system restart

Bootstrap FHIR package list

During the first startup Aidbox loads these packages. This setting has no effect on any consecutive starts.

Format: <name1>#<version1>:<name2>#<version2>...

IDbootstrap-fhir-packages
TypeString
Default value(no default)
Environment variableBOX_BOOTSTRAP_FHIR_PACKAGES
Deprecated environment variablesAIDBOX_FHIR_PACKAGES
Sensitivefalse — value will be visible in plaintext in Admin UI
Set viaAdmin UI → Settings
Environment variables
Hot reloadfalse — setting requires system restart

Init bundle

URL of the Bundle resource in JSON format executed on Aidbox startup. Not available to edit because if file is not reachable, Aidbox will not start.

IDinit-bundle
TypeString
Default value(no default)
Environment variableBOX_INIT_BUNDLE
Sensitivefalse — value will be visible in plaintext in Admin UI
Set viaEnvironment variables
Hot reloadfalse — setting requires system restart

Share usage statistics with Aidbox developers

Allows Aidbox to collect and send high-level API usage statistics to help improve the product.

IDusage-stats
TypeBool
Default valuetrue
Environment variableBOX_USAGE_STATS
Deprecated environment variablesBOX_TELEMETRY_USAGE_STATS
Sensitivefalse — value will be visible in plaintext in Admin UI
Set viaAdmin UI → Settings
Environment variables
Hot reloadfalse — setting requires system restart

Settings mode

Settings mode defines the source of settings values and possibility to change them at runtime.

IDsettings-mode
TypeEnum
Valueslegacy — Reads configuration values from the legacy Aidbox configuration project (zen) in read-only mode. This mode exists for backward compatibility. It will be obsolete in July 2025. &lt;a href='https://www.health-samurai.io/news/aidbox-transitions-to-the-fhir-schema-engine'&gt;Read more&lt;/a&gt;
read-only — Reads settings values from environment variables and Aidbox settings in read-only mode. Loading configuration from the Aidbox configuration project (Zen) is disabled.
read-write — Enables editing Aidbox settings using the UI. Loading configuration from the Aidbox configuration project (Zen) is disabled.
Default valuelegacy
Environment variableBOX_SETTINGS_MODE
Available from2502
Sensitivefalse — value will be visible in plaintext in Admin UI
Set viaEnvironment variables
Hot reloadfalse — setting requires system restart

Enable export settings endpoint

Allow user to request current Aidbox settings as a set of environment variables on /api/v1/settings/export.

Be aware, that endpoint may expose your sensitive settings.

IDexport-settings-endpoint
TypeBool
Default valuefalse
Environment variableBOX_EXPORT_SETTINGS_ENDPOINT
Sensitivefalse — value will be visible in plaintext in Admin UI
Set viaEnvironment variables
Hot reloadfalse — setting requires system restart

Enable cache replication

Aidbox automatically syncs runtime cache (SearchParameters, FHIR Schemas, OperationDefinitions, etc) across multiple instances for high availability. If you configure everything at startup and don't modify metadata at runtime, you can disable cache replication to improve performance.

IDcache-replication-disable
TypeBool
Default valuefalse
Environment variableBOX_CACHE_REPLICATION_DISABLE
Sensitivefalse — value will be visible in plaintext in Admin UI
Set viaAdmin UI → Settings
Environment variables
Hot reloadfalse — setting requires system restart

Aidbox modules load list

During startup Aidbox loads these modules. Format: <module-name2>,<module-name2>,<module-name3>...

IDmodule-load
TypeString
Default value(no default)
Environment variableBOX_MODULE_LOAD
Available from2505
Sensitivefalse — value will be visible in plaintext in Admin UI
Set viaEnvironment variables
Hot reloadfalse — setting requires system restart

Aidbox module jar

Path to an Aidbox module jar files separated by ":" Format: <path1>:<path2>:<path3>...

IDmodule-jar
TypeString
Default value(no default)
Environment variableBOX_MODULE_JAR
Available from2505
Sensitivefalse — value will be visible in plaintext in Admin UI
Set viaEnvironment variables
Hot reloadfalse — setting requires system restart

Last updated 2025-07-15T00:23:12Z