---
title: "Environment Variables"
description: "Every environment variable BxLens reads, and how to set any BxLens setting from the environment with the BoxLang convention."
icon: lucide:terminal
---

# Environment variables

There are two ways to use the environment with BxLens:

1. **BxLens variables.** A few fixed variables that start with `BXLENS_`. They name the server, its store folder and its secrets key.
2. **The BoxLang convention.** BoxLang can override any setting of `boxlang.json` from the environment, and that includes every BxLens setting.

Set them in the environment of the server process: a service file, a Dockerfile, a Compose file or a Kubernetes manifest.

## BxLens variables

| Variable | Used for | Falls back to |
|---|---|---|
| `BXLENS_SERVER_NAME` | The name of this server. The registration key is tied to it. | `server.name`, then this variable, then the host name |
| `BXLENS_SERVER_ADDRESS` | The primary address of this server | `server.address`, then this variable, then the first usable IPv4 address of the machine |
| `BXLENS_SERVER_ID` | A fixed id for this instance | `server.id`, then this variable, then an id made from the host name and the JVM start time |
| `BXLENS_SERVER_GROUP` | The group in the fleet, for example `prod-web`. 1 to 32 characters of letters, digits, space, `_`, `-` and `.`. | `server.group`, then this variable, then no group |
| `BXLENS_SERVER_KIND` | `host`, `docker`, `swarm`, `kubernetes`, `podman`, `lxc`, `lambda`, `ecs`, `cloud-run` or `azure` | `server.kind`, then this variable, then detected |
| `BXLENS_INSTANCE` | The name of this server's folder in the [store](store.md). Letters, digits, `.`, `_`, `-`, 64 characters at most. | `store.instanceFolder`, then this variable, then the host name |
| `BXLENS_SECRETS_KEY` | The key of the [Secret Store](../security.md#the-secret-store): base64 of 32 bytes. Replaces `secrets.key` and is never shown. | The `secrets.key` file |

In a container the host name changes on every deploy. Set `BXLENS_SERVER_NAME` and `BXLENS_INSTANCE` to fixed values.

## Variables whose name you choose

These settings hold the **name** of a variable, never its value. For the first two, the name must start with the prefix shown, so a setting cannot send out any other variable of the server (a license, a cloud key).

| Setting | The name starts with | Example |
|---|---|---|
| `notifications.smtp.passwordEnv` | `BXLENS_SMTP_` | `BXLENS_SMTP_PASSWORD` |
| `channels[].urlEnv`, `tokenEnv`, `signingKeyEnv` | `BXLENS_CHANNEL_` | `BXLENS_CHANNEL_OPS_SLACK` |
| `registration.keyEnv` | any name | `BXLENS_REGISTRATION_KEY` |
| `ai.apiKeyEnv` | any name | `OPENAI_API_KEY` |

## Passwords in `boxlang.json`

BoxLang replaces `${env.NAME}` in `boxlang.json` itself. Any name works. These are the ones the documentation uses:

```json
"console": {
    "password": "${env.BXLENS_PASSWORD}",
    "viewerPassword": "${env.BXLENS_VIEWER_PASSWORD}"
}
```

A default is allowed: `${env.BXLENS_PASSWORD:change-me}`.

## The BoxLang convention: any setting from the environment

BoxLang lets any item of its configuration be overridden from the environment or from a Java system property. The BxLens settings live under `modules.bxlens.settings`, so the same rule applies to them. See [Environmental properties configuration](https://boxlang.ortusbooks.com/getting-started/configuration#environmental-properties-configuration) in the BoxLang documentation.

**The rule.** Start with `BOXLANG_`, then the path of the setting with each dot written as `_`:

```
modules.bxlens.settings.console.sessionStorage
        |
BOXLANG_MODULES_BXLENS_SETTINGS_CONSOLE_SESSIONSTORAGE
```

**Examples**

```bash
BOXLANG_MODULES_BXLENS_SETTINGS_CONSOLE_SESSIONSTORAGE=cache
BOXLANG_MODULES_BXLENS_SETTINGS_CONSOLE_SESSIONCACHE=SESSIONS
BOXLANG_MODULES_BXLENS_SETTINGS_THRESHOLDS_SLOWQUERYMS=250
```

The same setting as a Java system property uses dots and the exact case, and needs the `boxlang.` prefix:

```bash
-Dboxlang.modules.bxlens.settings.console.sessionStorage=cache
```

**Good to know**

- **Case.** The variable name is not case sensitive. BoxLang matches it to the key that is already in `boxlang.json`, and BxLens reads its settings without regard to case too.
- **Keys that are not in `boxlang.json`.** They are added, and nested paths work.
- **Values.** Every value arrives as a text. BxLens turns the text into a boolean or a number where the setting needs one, so `true`, `false` and `250` work.
- **Lists.** A list (for example `access.proxyPeers`) does not arrive as a list. Set lists in `boxlang.json`.
- **The prefix `BXLENS_SETTINGS_` is not a thing.** `BXLENS_SETTINGS_CONSOLE_SESSIONSTORAGE` is ignored. Use the `BOXLANG_MODULES_BXLENS_SETTINGS_` form.
- **Settings of the console.** A setting that an admin changed in the console is kept in the settings file of the store and is a separate layer. See [Configuration](../configuration.md).

!!! note
    This was checked on BoxLang 1.19.0 with a `boxlang.json` that already holds the setting. Older versions of BoxLang may not support it.

## Variables of the platform

BxLens only asks **whether** these are set, never for their value, to tell where the server runs. Do not set them yourself.

| Variable | Means |
|---|---|
| `AWS_LAMBDA_FUNCTION_NAME` | AWS Lambda |
| `ECS_CONTAINER_METADATA_URI_V4`, `ECS_CONTAINER_METADATA_URI` | AWS ECS or Fargate |
| `K_SERVICE` | Google Cloud Run |
| `WEBSITE_SITE_NAME` | Azure App Service |
| `KUBERNETES_SERVICE_HOST` | Kubernetes |

BxLens also reads `BOXLANG_INSTANCE_NAME` (the BoxLang runtime instance name), `COMMANDBOX_VERSION` (the CommandBox version) and, for the host name, `HOSTNAME` or `COMPUTERNAME`.

## All variables on one page

| Variable | Kind |
|---|---|
| `BXLENS_SERVER_NAME`, `BXLENS_SERVER_ADDRESS`, `BXLENS_SERVER_ID`, `BXLENS_SERVER_GROUP`, `BXLENS_SERVER_KIND` | Identity of the server |
| `BXLENS_INSTANCE` | Store folder |
| `BXLENS_SECRETS_KEY` | Secret Store key |
| `BXLENS_SMTP_...` | Name you choose, for the SMTP password |
| `BXLENS_CHANNEL_...` | Name you choose, for a channel address, token or signing key |
| `BXLENS_REGISTRATION_KEY` | Name you choose, for the registration key (example) |
| `BXLENS_PASSWORD`, `BXLENS_VIEWER_PASSWORD` | Names you choose, for `${env.NAME}` in `boxlang.json` (examples) |
| `BOXLANG_MODULES_BXLENS_SETTINGS_<PATH>` | Any BxLens setting |
| `BOXLANG_INSTANCE_NAME`, `COMMANDBOX_VERSION`, `HOSTNAME`, `COMPUTERNAME` | Read for the runtime and the host |
| `AWS_LAMBDA_FUNCTION_NAME`, `ECS_CONTAINER_METADATA_URI(_V4)`, `K_SERVICE`, `WEBSITE_SITE_NAME`, `KUBERNETES_SERVICE_HOST` | Platform, presence only |