Skip to content

App Configuration

This page covers the Python side of app configuration: defining AppConfig subclasses, typed fields, defaults, and environment variable injection. For how to register apps and supply config values in hassette.toml, see Application Configuration.

Defining Config Models

Inherit from AppConfig to define your configuration schema. AppConfig extends Pydantic's BaseSettings (from the pydantic-settings package), which adds environment variable injection on top of standard Pydantic validation. If you've used Pydantic's BaseModel, the syntax is the same — BaseSettings just adds env var support.

from hassette import App, AppConfig


class MyAppConfig(AppConfig):
    # Define fields with types and optional defaults
    location_name: str
    threshold: float = 25.0
    notify_target: str = "mobile_app_phone"


# Pass the config class to the App generic
class MyApp(App[MyAppConfig]):
    async def on_initialize(self):
        # self.app_config is typed as MyAppConfig
        self.logger.info("Starting %s monitoring", self.app_config.location_name)

The App generic parameter (App[MyAppConfig]) tells Hassette which config class to instantiate. Inside your app, self.app_config is typed as MyAppConfig, giving you full IDE completion and type checking.

Base Fields

The base AppConfig includes standard fields available to all apps:

  • instance_name: str = "" - Used for logging and identification.
  • log_level: LOG_LEVEL_TYPE - Log-level override for this app instance; defaults to INFO or the global log_level setting.

Secrets & Environment Variables

AppConfig inherits from Pydantic's BaseSettings, so it supports environment variable injection out of the box. Define a custom env_prefix on your config class to control which environment variables it reads:

from pydantic_settings import SettingsConfigDict

from hassette import AppConfig


class MyAppConfig(AppConfig):
    model_config = SettingsConfigDict(env_prefix="MYAPP_")

    api_key: str

Now you can set MYAPP_API_KEY in your environment or .env file. TOML values and environment variables are merged; environment variables take precedence.

See Also