Skip to content

Application Configuration

This page covers the TOML side of app configuration: registering apps in hassette.toml, supplying config values, and running multiple instances. The App Configuration page covers defining typed AppConfig models in Python.

Apps are registered and configured in the hassette.toml file under [hassette.apps.<name>].

App Registration

Each app block requires:

  • filename (or file_name): Path to the python file relative to apps.directory.

    • Should include the extension (e.g., .py), though Hassette will attempt to guess if missing.
    • Supports subdirectories (e.g., subdir/my_app.py).

  • class_name (or class, module, module_name): Name of the App subclass to load.

    • If multiple classes exist in the file, this field disambiguates which one to load.

Tip

Prefer class_name and filename in docs and new configs; the alternative keys exist for compatibility.

Optional fields:

  • enabled: Set to false to disable the app without removing the config block.
  • display_name: Friendly name for logs; defaults to the class name.

Single Instance

[apps.presence]
filename = "presence.py"
class_name = "PresenceApp"
config = { motion_sensor = "binary_sensor.hall", lights = ["light.entry"] }

App Configuration Parameters

You can pass configuration parameters to your apps using the config field.

  • Single instance: config = { key = "value" } or [hassette.apps.name.config]
  • Multiple instances: [[hassette.apps.name.config]] (recommended)

Paths

apps.directory is resolved to an absolute path at startup. Relative paths are resolved relative to the current working directory.

Filename extension

If filename has no extension, Hassette assumes .py.

Environment Variable Overrides:

You can override nested config values using environment variables. This merges with any TOML configuration (env vars take precedence).

  • Pattern: HASSETTE__APPS__<APP_NAME>__CONFIG__<KEY>
  • Example: HASSETTE__APPS__MY_APP__CONFIG__SOME_OPTION=true overrides some_option for my_app.

Multiple Instances

To run the same app multiple times with different configurations, use [[hassette.apps.<name>.config]] blocks.

[apps.presence]
filename = "presence.py"
class_name = "PresenceApp"

[[apps.presence.config]]
name = "upstairs"
motion_sensor = "binary_sensor.upstairs_motion"
lights = ["light.bedroom", "light.hallway"]

[[apps.presence.config]]
name = "downstairs"
motion_sensor = "binary_sensor.downstairs_motion"
lights = ["light.living_room", "light.kitchen"]

Typed Configuration

The config values supplied in TOML are validated against an AppConfig subclass that you define in Python. Hassette raises a configuration error at startup if any required field is missing or has the wrong type. For how to define that model, see App Configuration.

See Also