Agent stack build plans · № 6 · 4 of 6

Set it up

Two real paths in. Pick one, then wire events, safety, and the nightly cron.

Before anything

• A running Home Assistant install, reachable from wherever Hermes will live (same LAN is simplest; http://homeassistant.local:8123 in the examples below).
• In HA: create a dedicated, non-administrator user (e.g. hermes) and log in as it once to generate a long-lived access token (profile page → Security). The token inherits its user’s rights — this is the single cheapest safety decision in the whole build. Trap 1 if you’re tempted to skip it.
• A model API key for whichever provider you’ll route the gateway to. Hermes is model-agnostic — Nous Portal, OpenRouter, OpenAI, or your own endpoint.

Path A — the Home Assistant add-on

Hermes ships an official HA add-on; the docs’ claim is “zero to working agent in less than five minutes”, and it runs Hermes on the same box as HA with the wiring done for you. Follow the add-on instructions in the Hermes docs (Messaging → Home Assistant). Take this path if HA hardware is your only always-on machine. The rest of this page still applies — event filters, approvals and cron are the same config either way.

Path B — HASS_TOKEN on any machine

Take this path if Hermes should live on a home server, an old laptop, or anywhere that isn’t the HA box.

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

Setting HASS_TOKEN (plus optional HASS_URL) in ~/.hermes/.env auto-enables the homeassistant toolset — no further registration step.

hermes

In the session, ask: “Use ha_list_entities and tell me how many entities you can see, grouped by domain.” If the tool isn’t available, the token isn’t being read — check the .env path before anything else.

Turn on event awareness

Tools alone make a reactive assistant. The gateway makes it aware: HA is also a Hermes gateway platform, streaming state-change events over WebSocket. Configure the filters in ~/.hermes/config.yaml — the key structure is platforms.homeassistant.extra (as of v0.19.0):

# ~/.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

Do not start with watch_all: true. Every event that survives the filter and the cooldown becomes a model turn — watch_all on a hundred-entity house is a bill, not a feature (trap 2). Note what’s absent from watch_domains above: lock and alarm_control_panel. The agent shouldn’t even be narrating those.

hermes gateway

Watch it log an event or two (walk past a sensor), then install it as a background service — the gateway is systemd/launchd-installable; see the CLI reference for the service commands on your OS. Add Telegram (or Discord, Signal, ntfy…) as a second gateway platform per the messaging docs, so nudges reach your pocket. Gateway access is allowlist/DM-pairing based — approve your own account with hermes pairing approve when it introduces itself.

Safety rails before you leave it running

• Set approvals.mode to manual for the first weeks — every ha_call_service gets confirmed by you. Graduate to smart (LLM risk-assessment) once the house map and rules are solid. Never off for an agent with hands on your house.
• approvals.deny takes fnmatch globs over tool patterns — e.g. denying ha_call_service outright gives you a look-but-don’t-touch profile for guests or a kid’s profile (hermes profile create). Be honest about its shape: it matches tools, not tool arguments, so there is no documented glob for “ha_call_service but only on locks”. Lock/alarm safety = manual approvals + keeping those domains out of the watch lists.
• Your HASS_TOKEN lives in ~/.hermes/.env, which sits under Hermes’s protected paths — its own tools won’t read it back. Keep it that way: never paste the token into a chat session.

Schedule 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; jobs live in ~/.hermes/cron/ and can be paused, run on demand, or edited (hermes cron pause|run|edit). What the job should actually say is the substance of prompt 3.