How to Connect Hermes Agent to Home Assistant

This was the fastest integration I had set up in Home Assistant. I added two environment variables, restarted the gateway, and tried one request.

I said “can you turn off all my lights” through Telegram and watched every light in the house go off in about two seconds. No automation, scene, or script. The agent called the Home Assistant API directly.

Prerequisites: Hermes Agent running as a gateway (setup guide), Home Assistant on your local network.

Get a Long-Lived Access Token

In Home Assistant, go to your profile → Long-Lived Access Tokens → Create Token. Name it “Hermes Agent” and copy it — you won’t see it again.

Add Two Lines to .env

On UGREEN, the env file is at /opt/data/.env (not ~/.hermes/.env as the docs show for non-NAS installs):

HASS_TOKEN=your-long-lived-access-token
HASS_URL=http://192.168.1.100:8123

HASS_URL is optional if your Home Assistant is reachable at homeassistant.local:8123. Use the IP if mDNS is unreliable on your network. Setting HASS_TOKEN is enough to activate the integration — the gateway picks it up automatically on restart.

Restart the Hermes container, then try it.

What the Agent Can Do

Hermes gets four tools against your Home Assistant instance:

That last one is what turns the lights off. The agent figures out the entity IDs and service calls on its own — you just describe what you want.

Choose Control or Monitoring

Turning off the lights is an interactive agent task: the request needs entity discovery and a service call. Watching the front door is different. Once I can state the whole rule, I use a script-only Hermes cron job: check every five minutes and alert only after the lock has stayed unlocked for ten. There is no reason to pay a model to reconsider that condition all day.

The watchdog must treat unknown, unavailable, an authentication error, or a failed delivery as a failure—not as a quiet success. It should exit non-zero when it cannot perform the check and update its alert state only after delivery succeeds. That keeps a broken Home Assistant connection from looking like a safely locked door.

Event Forwarding (Optional)

By default, Home Assistant events are not forwarded to the agent. To enable state-change awareness, add a filter to config.yaml:

platforms:
  homeassistant:
    enabled: true
    extra:
      watch_domains: [light, climate, binary_sensor]
      watch_entities: [sensor.front_door_battery]
      ignore_entities: [sensor.uptime, sensor.cpu_usage]
      cooldown_seconds: 30

Without this, the agent only acts on requests — it won’t proactively notify you when something changes.

Skill Conflicts with Other Smart Home Integrations

If you have other smart home skills loaded (like OpenHue), Hermes may route generic “lights” requests to the wrong one. I ran into this — it kept calling the OpenHue skill instead of Home Assistant even though I don’t have Philips Hue.

The fix is to edit the conflicting skill’s SKILL.md and narrow its trigger conditions. In /opt/data/skills/smart-home/openhue/SKILL.md, I replaced the generic “When to Use” entries with an explicit restriction:

Use this skill only when the user explicitly has Philips Hue/OpenHue,
asks for Hue-specific control, or mentions a Hue bridge. Do not use
this skill as the default for generic "lights" requests when Home
Assistant is available.

After that change, generic lighting requests routed correctly to Home Assistant.

What’s Blocked

For safety, a handful of service domains are blocked to prevent arbitrary code execution: shell_command, command_line, python_script, pyscript, hassio, and rest_command. Everything else is available.

The integration eventually grew into scheduled household checks. I audited that system in Five Hermes Agent Patterns I Wish I Had Started With.