---
description: Configure Aidbox behavior using settings through UI or environment variables, including FHIR, security, database, and observability options.
---

# Settings

This page explains how to configure Aidbox using settings. Settings control how your Aidbox instance behaves and can be managed using Aidbox UI and environment variables.

### How settings work

Each setting in Aidbox:

* Has a unique name that identifies it (like [`fhir.search.default-params.count`](../reference/all-settings.md#fhir.search.default-params.count))
* Can be configured through the UI or environment variables
* Includes a description explaining its purpose
* Maps to a specific environment variable name
* May have a default value (for example, [`fhir.search.default-params.count`](../reference/all-settings.md#fhir.search.default-params.count) defaults to `100`)

### Setting categories

You can find all settings organized into these categories in the Aidbox UI under the `Settings` tab:

* **General**: Core server configuration options
* **FHIR**: Settings specific to FHIR functionality
* **Security and Access Control**: Authentication, authorization, audit logging settings
* **Modules**: Settings for individual Aidbox modules
* **Web**: HTTP server configuration
* **Database**: Database connection and connection pool settings
* **Observability**: Logging, monitoring, and debugging options
* **Zen**: Legacy settings (deprecated)

### Setting groups

Some settings have special properties:

* **Sensitive Settings**: These contain secure data like passwords and API keys
  * Can only be set using environment variables
  * Example: [`security.encrypt-secret`](../reference/all-settings.md#security.encrypt-secret)
  * Not editable in the UI
* **Restart Required Settings**: Changes to these require an Aidbox server restart
  * Example: [`db.pool.maximum-pool-size`](../reference/all-settings.md#db.pool.maximum-pool-size)
  * The UI will notify you when a restart is needed

Full details are available in the reference documentation.

### Settings precedence

When Aidbox starts up, it determines setting values in this order:

1. Environment variables (highest priority)
   * Take precedence over all other sources
   * Cannot be changed using the UI
   * Best practice for production environments
2. User-defined settings in UI
   * Applied when no environment variable exists
   * Can be changed using the UI
3. System defaults (lowest priority)
   * Built-in values provided by Aidbox
   * Used when no other value is specified

This hierarchy provides:

* Flexible and quick configuration during development via UI
* Secure, consistent configuration in deployment scripts and CI/CD pipelines via environment variables

### Enable runtime settings editing

A user can enable runtime editing of Aidbox settings using the [`settings.mode`](../reference/all-settings.md#settings-mode) in `read-write` value.

Possible values:

* `read-write`: enables editing Aidbox settings using the UI. This mode disables loading configuration from the Aidbox configuration project (zen).
* `read-only`: reads settings values from environment variables and Aidbox settings in read-only mode. This mode disables loading configuration from the Aidbox configuration project (zen).
* `legacy`: reads configuration values from the legacy Aidbox configuration project (zen) in read-only mode. This mode exists for backward compatibility. Read [more](https://www.health-samurai.io/news/aidbox-transitions-to-the-fhir-schema-engine).

For example, a user can set `BOX_SETTINGS_MODE: read-write` in the environment variables to enable runtime editing of Aidbox settings.

Starting from March 2025 existing instances use `legacy` mode for backward compatibility. All new instances use `read-write` by default.

### Environment variable naming by settings mode

The format of environment variable names depends on the active settings mode. Using the wrong format for your mode means the setting will be **silently ignored**.

| Settings mode | Separator | Example |
|---|---|---|
| `read-write` | `_` (single underscore) | `BOX_DB_POOL_MAXIMUM_POOL_SIZE` |
| `read-only` | `_` (single underscore) | `BOX_DB_POOL_MAXIMUM_POOL_SIZE` |
| `legacy` | `__` (double underscore) | `BOX_DB_POOL_MAXIMUM__POOL__SIZE` |

In `legacy` mode Aidbox uses a different env var parser that treats `__` as a path separator. The newer single-underscore names map to wrong config paths and their values are never applied.

{% hint style="warning" %}
If you rename env vars from the `__`-style to the `_`-style, you must also switch `BOX_SETTINGS_MODE` to `read-write` or `read-only`. Renaming env vars alone will silently break your configuration.
{% endhint %}

### Migrating from legacy to read-write mode

{% stepper %}
{% step %}
Set `BOX_SETTINGS_MODE=read-write` in your environment variables.
{% endstep %}
{% step %}
Replace all double-underscore separators in env var names with single underscores.

For example: `BOX_DB_POOL_MAXIMUM__POOL__SIZE` → `BOX_DB_POOL_MAXIMUM_POOL_SIZE`

The [Settings reference](../reference/all-settings.md) lists the current env var name for each setting under **Environment variable** and the legacy `__`-style name under **Legacy mode environment variable**.
{% endstep %}
{% step %}
Restart Aidbox to apply the changes.
{% endstep %}
{% endstepper %}

### Product-specific settings

In some cases there're specific settings defined in products: Smartbox, Multibox, etc. These settings will have `<product>.<setting>` name format.

### Settings reference documentation

{% content-ref url="../reference/settings/" %}
[settings](../reference/all-settings.md)
{% endcontent-ref %}