Configuration

HomeCmdr is configured through a single TOML file. The default location is config/default.toml inside your workspace, but you can override it:

• CLI flag: --config /path/to/config.toml
• Environment variable: HOMECMDR_CONFIG=/path/to/config.toml

When installed as a systemd service, the CLI copies and adjusts your config to /etc/homecmdr/default.toml.

[api]

[api]
bind_address = "127.0.0.1:3001"

[api.cors]

Cross-origin requests are disabled by default. Enable them for browser-based dashboards served from a different origin.

[api.cors]
enabled = true
allowed_origins = ["http://127.0.0.1:8080"]

[api.rate_limit]

Optional token-bucket rate limiter on write endpoints.

[api.rate_limit]
enabled = false
requests_per_second = 100
burst_size = 20

Affects: POST /devices/{id}/command, POST /rooms/{id}/command, POST /groups/{id}/command, POST /scenes/{id}/execute.

Requests that exceed the configured rate receive HTTP 429 Too Many Requests.

[auth]

[auth]
master_key = "your-strong-key-here"

The master key grants full admin access and is used for initial setup and API key management. It is stored and compared as a SHA-256 hex digest.

Override it at runtime with the HOMECMDR_MASTER_KEY environment variable (takes precedence over the config file value).

See Authentication for the full key management model.

[locale]

[locale]
timezone = "Europe/London"
latitude  = 51.5
longitude = -0.1

Used by sunrise/sunset automation triggers and wall-clock scheduling. latitude and longitude are in decimal degrees. timezone must be a valid IANA timezone name.

[persistence]

SQLite (default)

[persistence]
backend = "sqlite"
database_url = "sqlite://data/homecmdr.db"
auto_create = true

The database file is created automatically on first run. Relative paths in database_url are resolved from the directory set by HOMECMDR_DATA_DIR (or the current working directory if unset).

PostgreSQL

[persistence]
backend = "postgres"
database_url = "postgres://user:pass@localhost/homecmdr"

Both backends store the same data: device and room state, full attribute history, command audit log, scene and automation execution history.

[scenes]

[scenes]
enabled   = true
directory = "config/scenes"
watch     = false

When watch = true, saving any .lua file under the directory triggers a debounced reload identical to POST /scenes/reload. Keep watch = false in production.

[automations]

[automations]
enabled   = true
directory = "config/automations"
watch     = false

[automations.runner]
default_max_concurrent = 8
backstop_timeout_secs  = 3600

[scripts]

[scripts]
enabled   = true
directory = "config/scripts"
watch     = false

Scripts are reusable Lua helper modules loaded by scenes and automations via require(...). See Scenes and Automations.

[adapters]

Each enabled adapter gets its own block:

[adapters.open_meteo]
enabled            = true
latitude           = 51.5
longitude          = -0.1
poll_interval_secs = 90

[adapters.zigbee2mqtt]
enabled    = true
host       = "192.168.1.10"
port       = 1883
base_topic = "zigbee2mqtt"

[adapters.elgato_lights]
enabled = true

The fields inside each [adapters.<name>] block are defined by the adapter crate, not by core. See the plugin docs for the config reference for each official adapter.

Environment variables