Home Assistant: let Hermes see and control your smart home

What Home Assistant is for

The Home Assistant plugin, maintained by Nous Research and installed from the plugin catalog, does two jobs. It adds a toolset that lets the agent list entities, read their state, list services and call them, for example turning on a light. It also connects to Home Assistant as a gateway platform, so state changes on entities you choose to watch can reach the agent, and replies come back as persistent notifications. It suits home automation, presence-based routines and status questions. Risky service domains such as shell_command and python_script are blocked by design. This is event ingestion plus notifications and device tools, not a generic phone messenger. These notes describe the official docs; the catalog plugin implementation is maintained in a separate repository.

What you need

• A running Home Assistant instance and a Long-Lived Access Token (short-lived session tokens do not work)
• The homeassistant plugin installed for each Hermes profile that needs it
• Network access from Hermes to the Home Assistant URL

Set it up

1. 1

   Run hermes plugins install homeassistant (or hermes -p <profile> plugins install homeassistant for another profile)

2. 2

   In Home Assistant, open your profile and create a Long-Lived Access Token

3. 3

   Add HASS_TOKEN and, if not the default http://homeassistant.local:8123, HASS_URL to ~/.hermes/.env

4. 4

   Set platforms.homeassistant.extra.watch_domains or watch_entities in config.yaml if you want state-change events, then start hermes gateway

5. 5

   Set HASS_HOME_CHANNEL for a bare deliver=homeassistant target, or use homeassistant:<notify target>. Keep watch filters for inbound events; service credentials differ from human-message allowlists.

Check it works

• hermes plugins list shows the plugin as installed and enabled
• Run curl -H "Authorization: Bearer <token>" <url>/api/ and expect an "API running" message
• After hermes gateway starts, Home Assistant appears as a connected platform

Limits and failure points

• No events are forwarded unless watch_domains, watch_entities or watch_all is set; watch_all is not recommended
• Home Assistant events bypass user allowlists and pairing
• Environment changes only apply after restarting the gateway; a 401 error usually means the wrong token type or URL

Messaging setup

All messaging platforms

• Hermes Agent messaging gateway explained

Spotted something wrong or out of date? Tell us on X at @HermesWatcher↗ (opens in a new tab) and we will fix it.