The Hermes Agent Home Assistant connection runs through one official plugin, and you can have it live in about ten minutes.
Install it, paste a long-lived token into your env file, start the gateway, then tell it which devices to watch.
Get Your Backlink Gameplan →Try Polar Rank Free for 3 Days →
If you want AI agents running your SEO and lead flow the same way, get your Backlink Gameplan with my team, or try Polar Rank free for 3 days.
Everything below comes from the Hermes Home Assistant docs and the plugin source on GitHub.
What the plugin gives you
The plugin is maintained by Nous Research in the hermes-official-plugins repo and is not part of Hermes core.
It adds two things at once.
- A gateway platform that subscribes to state changes over WebSocket and forwards matching events to the agent.
- A smart home toolset called homeassistant with four LLM-callable tools that talk to the REST API.
One token switches on both halves.
Step 1: install the plugin per profile
Run this on the machine that runs Hermes:
hermes plugins install homeassistant
Plugins install per profile, so a second profile needs its own install:
hermes -p <profile> plugins install homeassistant
The plugin declares its own aiohttp dependency.
The old hermes-agent[homeassistant] pip extra is gone, so skip any tutorial that still tells you to pip install it.
Upgrading from a release that bundled Home Assistant needs no action: hermes update installs the plugin for profiles that already used it.
Step 2: create the long-lived access token
In Home Assistant, open your Profile, scroll to Long-Lived Access Tokens and click Create Token.
Name it something you will recognise later, like Hermes Agent, and copy it once.
Short-lived UI session tokens will not work, which is the cause of most 401 errors.
Home Assistant explains token types on its authentication page.
Step 3: write the env file
Add these lines to ~/.hermes/.env under the active profile home:
HASS_TOKEN=your-long-lived-access-token
HASS_URL=http://192.168.1.100:8123
HASS_HOME_CHANNEL=mobile_app_my_phone
HASS_URL is optional and defaults to http://homeassistant.local:8123.
HASS_HOME_CHANNEL is the default notify target for a bare deliver: homeassistant line in cron jobs.
With the plugin installed, the toolset switches on automatically once HASS_TOKEN is set.
Step 4: start the gateway and check it connected
hermes gateway
Home Assistant then shows up as a connected platform next to Telegram, Discord or whatever else you run.
Get Your Backlink Gameplan →Try Polar Rank Free for 3 Days →
Env changes only load when the process starts, so restart the gateway after every edit.
🔥 Want the whole agent stack set up for you, not just the smart home piece? Inside the AI Profit Boardroom you get step-by-step video trainings, the installable Agent OS, four coaching calls a week and 3,400+ members building with Hermes. → Join the AI Profit Boardroom
Step 5: set event filters or nothing arrives
This is the gotcha that catches almost everyone.
By default no events are forwarded at all, and Hermes logs a warning and drops every state change.
Add at least one filter under the platform's extra block in ~/.hermes/config.yaml:
platforms:
homeassistant:
enabled: true
extra:
watch_domains:
- climate
- binary_sensor
- alarm_control_panel
watch_entities:
- sensor.front_door_battery
ignore_entities:
- sensor.uptime
- sensor.cpu_usage
cooldown_seconds: 30
| Setting | Default | What it controls |
|---|---|---|
| watch_domains | none | Only these entity domains reach the agent |
| watch_entities | none | Only these exact entity IDs reach the agent |
| watch_all | false | Every state change, which floods most setups |
| ignore_entities | none | Always dropped, checked before the other filters |
| cooldown_seconds | 30 | Minimum gap between events for one entity |
The docs suggest climate, binary_sensor and alarm_control_panel as the starting set, then adding domains as you need them.
The four tools and what they call
| Tool | Job | Example ask |
|---|---|---|
| ha_list_entities | List entities, filter by domain or area | List all lights in the living room |
| ha_get_state | Full state and attributes for one entity | What is climate.thermostat set to? |
| ha_list_services | Show the actions a domain accepts | What services exist for climate devices? |
| ha_call_service | Run an action on a device | Set the thermostat to 22 in heat mode |
A thermostat change resolves to a call like this one:
ha_call_service(domain="climate", service="set_temperature",
entity_id="climate.thermostat", data={"temperature": 22, "hvac_mode": "heat"})
If Tool Search is on, the ha_* tools sit behind tool_search and tool_call like every other plugin tool.
How events read once they arrive
The adapter turns raw state changes into plain sentences by domain.
Get Your Backlink Gameplan →Try Polar Rank Free for 3 Days →
- climate changes read like "HVAC mode changed from 'off' to 'heat'" with current and target values.
- binary_sensor changes read as triggered or cleared.
- light, switch and fan changes read as turned on or turned off.
The agent's replies land in Home Assistant as persistent notifications titled Hermes Agent.
Route cron jobs and webhooks to your phone
Scheduled jobs and webhook routes can deliver straight to Home Assistant:
deliver: homeassistant:mobile_app_my_phone
deliver: homeassistant
The bare form needs HASS_HOME_CHANNEL set.
Pair this with the cron docs to get a morning house report pushed to your phone, and with webhook routes for events from other services.
Security limits you cannot switch off
The tools block service domains that could run code on the Home Assistant host.
- shell_command and command_line
- python_script and pyscript
- hassio, which covers add-on control and host shutdown
- rest_command, which could make HTTP requests from the HA server
Entity IDs are also checked against a strict pattern before any call goes out.
Connection behaviour worth knowing
- The WebSocket keeps a 30-second heartbeat for live events.
- Reconnects back off from 5 to 10 to 30 to 60 seconds.
- Outbound notifications use a separate REST session so they never fight the WebSocket.
- Home Assistant events are always authorised, because the token authenticates the link and there is no human sender to pair.
📞 Running a local business and want this kind of automation behind your SEO? Get your Backlink Gameplan and my team will map where agents save you hours and where search traffic is leaking, or try Polar Rank free for 3 days. Backlink Gameplan or try Polar Rank free for 3 days
Three automations the docs walk through
The morning routine is a chain of three service calls: bedroom light to brightness 128, thermostat to 22, kitchen speaker on.
The security check reads every binary_sensor, the alarm panel state and every lock, then sends one line back.
The reactive one starts from an event: the front door triggers, the agent reads the sensor, turns on the hallway light and sends a note.
Build them in that order, because each one adds a new moving part.
Get Your Backlink Gameplan →Try Polar Rank Free for 3 Days →
The first only writes, the second only reads, and the third needs your watch list working.
Run the gateway as a service
Running hermes gateway in a terminal is fine for testing, but the connection dies when the terminal closes.
The gateway docs give two longer-lived options.
hermes gateway install
sudo hermes gateway install --system
The first installs a user service; the second is Linux only and starts at boot.
Run hermes gateway status if you suspect two copies are running, because duplicate gateways cause duplicate replies.
Display settings for notifications
The Home Assistant platform uses the minimal display defaults.
That means no tool-progress lines and no streaming chatter in your notification panel, just the final message.
If you want more detail while debugging, override it under display.platforms.homeassistant in config.yaml, then switch it back.
Multi-profile setups
Each Hermes profile keeps its own plugins, so a work profile and a home profile can run separately.
Install the plugin with hermes -p home plugins install homeassistant and keep HASS_TOKEN only in that profile's .env.
That way the agent that handles your client work never sees your house.
If you later remove the plugin from a profile with hermes plugins remove homeassistant, it stays removed and is not reinstalled on update.
Upgrade behaviour in detail
Profiles that already used Home Assistant get the plugin from the catalog during hermes update.
If that step could not run, Hermes installs it the first time the profile starts, as long as security.allow_lazy_installs is on.
A failed attempt, for example when the catalog is unreachable, retries at most once an hour on start, while hermes update always retries.
Your old HASS_TOKEN, HASS_URL, platform keys, toolset name and cron deliver syntax all carry over unchanged.
Other ways people connect the two
The official plugin is the clean route, but the results for this search show a few other patterns.
- Community custom integrations posted in Home Assistant forums go the other way, letting HA talk to Hermes. Treat anything labelled alpha as a test build.
- The API server exposes Hermes as an OpenAI-compatible endpoint on port 8642, so any client that speaks that format can reach it.
- A Home Assistant automation can POST to a Hermes webhook route, which then runs the agent with a prompt template.
Get Your Backlink Gameplan →Try Polar Rank Free for 3 Days →
Start with the plugin; reach for the others only when you need HA to start the conversation.
Writing prompts the tools understand
The tools match areas against friendly names, so name your rooms clearly in Home Assistant first.
"List all lights in the living room" works because ha_list_entities can filter by the area string.
For changes, give the agent the entity ID when you know it, such as light.living_room, and it skips a lookup call.
For colour and brightness, plain words work: the docs show a request for blue at 50% brightness turning into brightness 128 and color_name blue.
When a request touches several devices, ask the agent to list the calls it will make before it runs them.
That one habit catches wrong entity IDs before they switch the wrong thing.
Picking domains for the watch list
Think in terms of what you would want a message about.
climate covers thermostats and HVAC mode changes, which is useful for comfort and for spotting a heating fault.
binary_sensor covers doors, windows, motion and leak sensors, which is where most security value sits.
alarm_control_panel tells you when the alarm arms, disarms or triggers.
light and switch are usually noise, so leave them out unless a specific light matters.
Add single entities with watch_entities when only one device in a busy domain matters, such as a front door battery sensor.
Logs to check when debugging
The gateway logs a warning at startup when no filter is set, so read the first lines after every restart.
Connection drops show up as reconnect attempts with the backoff times above.
If a service call fails, the error usually names the domain or entity, which tells you whether it was blocked, missing or misspelled.
Keep the gateway running in a terminal while you test, then move it to a service once it is stable.
Troubleshooting checklist
- Platform or tools missing: run hermes plugins list in the active profile and reinstall if it is absent.
- Env not picked up: check the .env sits under the active profile home with no stray quotes around the URL or token.
- 401 Unauthorized: create a fresh long-lived token and confirm HASS_URL includes the scheme and port.
- Test reachability from the Hermes host with curl against /api/ and look for the API running message.
- Events silent: add watch_domains or watch_entities, then restart the gateway.
For more agent builds like this, the AI Profit Boardroom has the full Hermes training library.
Get Your Backlink Gameplan →Try Polar Rank Free for 3 Days →
FAQ: Hermes Agent Home Assistant Setup
Does Hermes Agent support Home Assistant out of the box?
Yes, through the official homeassistant plugin from the plugin catalog. Install it with hermes plugins install homeassistant and set HASS_TOKEN.
Why does my Hermes Agent ignore Home Assistant events?
No events are forwarded until you set watch_domains, watch_entities or watch_all in config.yaml. Add a filter and restart the gateway.
Which token does the plugin need?
A Long-Lived Access Token created from your Home Assistant user profile. Short-lived session tokens return 401 errors.
Can Hermes run shell commands through Home Assistant?
No. The plugin blocks shell_command, command_line, python_script, pyscript, hassio and rest_command service domains.
Where do Hermes replies show up in Home Assistant?
As persistent notifications titled Hermes Agent, or on a notify target such as your phone when a cron job uses deliver: homeassistant.
📺 Video notes + links to the tools 👉
🎥 Learn how I make these videos 👉
🆓 Get a FREE AI Course + Community + 1,000 AI Agents 👉
About Julian
I'm Julian Goldie, an SEO entrepreneur, author and founder of the AI Profit Boardroom, which has 3,400+ members.
I help business owners scale with AI agents, automation and SEO.
- I've built a 7-figure SEO and link building agency, Goldie Agency, with a team of 70+ SEO experts.
- I've grown a YouTube channel to 400,000+ subscribers.
- I wrote "Link Building Mastery".
- My Udemy courses have taught over 29,000 students.
→ Get my best AI training inside the AI Profit Boardroom
Install the plugin, set your filters and run the morning-routine test tonight.
Then get your Backlink Gameplan if you want the same agent thinking pointed at your rankings, and keep this page open as your Hermes Agent Home Assistant checklist, or try Polar Rank free for 3 days.











