Skip to content

Configuration

All configuration is driven by environment variables. Use a .env file in development (Bun loads it automatically) or set variables directly in your shell / container environment.

An annotated .env.example is included in the repository.

Core

Variable Default Description
NODE_ENV (unset) Set to production to use raw JSON logging; otherwise logs are pretty-printed
TZ system default Timezone for cron schedules, e.g. Europe/Berlin
LOG_LEVEL info Minimum log level: trace, debug, info, warn, error, fatal

MQTT

Variable Default Description
MQTT_HOST localhost Hostname or IP of the MQTT broker
MQTT_PORT 1883 MQTT broker port
ZIGBEE2MQTT_PREFIX zigbee2mqtt Topic prefix used by Zigbee2MQTT

Automations

Variable Default Description
AUTOMATIONS_RECURSIVE false Scan subdirectories of automationsDir recursively

State persistence

Variable Default Description
STATE_PERSIST false Save state to disk on shutdown and restore on startup
STATE_FILE_PATH ./state.json Path to the state persistence JSON file

HTTP server

The HTTP server serves health probes, the debug API, webhook endpoints, and optionally the web UI. Set HTTP_PORT=0 to disable it entirely (also disables webhooks and the web UI).

Variable Default Description
HTTP_PORT 8080 Port for the HTTP server. Set to 0 to disable.
HTTP_TOKEN (empty) Bearer token for debug/webhook endpoints. Empty = no authentication.

Web UI

Variable Default Description
WEB_UI_ENABLED false Enable the browser-based web UI dashboard
WEB_UI_PATH /status URL path prefix for the web UI

See Web UI for full details.

Device Registry

Automatically discovers all Zigbee2MQTT devices and tracks their live state. Required for device_state, device_joined, and device_left trigger types, as well as the Devices tab in the CLI dashboard and web UI.

Variable Default Description
DEVICE_REGISTRY_ENABLED false Enable automatic Zigbee2MQTT device discovery and state tracking
DEVICE_REGISTRY_PERSIST false Persist the device list and last-known device states to disk on shutdown and restore them on startup
DEVICE_REGISTRY_FILE_PATH ./device-registry.json Path to the device registry JSON persistence file

See Device Registry for full details including nice names, device triggers, and persistence.

Example .env

TZ=Europe/Berlin
LOG_LEVEL=info

MQTT_HOST=192.168.1.10
MQTT_PORT=1883
ZIGBEE2MQTT_PREFIX=zigbee2mqtt

STATE_PERSIST=true
STATE_FILE_PATH=./data/state.json

HTTP_PORT=8080
HTTP_TOKEN=my-secret-token

WEB_UI_ENABLED=true
WEB_UI_PATH=/status

DEVICE_REGISTRY_ENABLED=true
DEVICE_REGISTRY_PERSIST=true
DEVICE_REGISTRY_FILE_PATH=./data/device-registry.json