Set it up

There are two ways to install it. Pick one, then set up events, safety and the nightly job.

Before you start

• An HA install Hermes can reach (the examples use http://homeassistant.local:8123).
• A non-admin HA user such as hermes. Log in once and make a long-lived access token (profile, then Security). The token has that user’s rights, so this is the cheapest safety step in the build (trap 1).
• A model API key (Nous Portal, OpenRouter, OpenAI or your own endpoint).

Path A: the add-on

The official HA add-on runs Hermes on the HA box with the wiring done. Follow the Hermes docs (Messaging, then Home Assistant). Use it if HA is your only always-on machine. Filters, approvals and cron below work the same way.

Path B: a token on any machine

For a home server or an old laptop.

curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash

(Windows PowerShell: iex (irm https://hermes-agent.nousresearch.com/install.ps1).)

# ~/.hermes/.env
HASS_TOKEN=eyJ...your-long-lived-token...
HASS_URL=http://homeassistant.local:8123

This alone turns on the homeassistant toolset.

hermes

Ask: “Use ha_list_entities and tell me how many entities you can see, grouped by domain.” If the tool is missing, check the .env path.

Events

Without events it only reacts when asked. Set the filters in ~/.hermes/config.yaml under platforms.homeassistant.extra (key structure as of v0.19.0), and start narrow:

# ~/.hermes/config.yaml (excerpt)
platforms:
  homeassistant:
    extra:
      watch_domains: [light, climate, cover, person, binary_sensor]
      ignore_entities: [binary_sensor.hallway_motion]   # your chattiest sensor
      cooldown_seconds: 60   # default is 30; higher = calmer and cheaper

Don’t start with watch_all: true (trap 2). lock and alarm_control_panel are left out on purpose.

hermes gateway

Walk past a sensor and watch it log an event, then install it as a service (see the CLI reference for your OS). Add Telegram or another platform per the messaging docs, and approve your own account with hermes pairing approve.

Safety

• Run approvals.mode on manual for the first few weeks so you confirm every ha_call_service, then move to smart. Never use off.
• approvals.deny can block ha_call_service entirely for a look-only guest or kid profile (hermes profile create). It matches tool names and can’t look at arguments, so it can’t single out locks.
• The token sits in ~/.hermes/.env, under Hermes’ protected paths. Never paste it into a chat.

The learning loop

hermes cron create "Every night at 23:30, review today's Home Assistant \
events and conversations, distill any new recurring household patterns, \
message me the proposed memory changes on Telegram, and apply the ones I \
approve"

Check it with hermes cron list; manage it with hermes cron pause|run|edit. Prompt 3 has the full wording.