How to Connect Hermes Agent to Home Assistant

This is the fastest integration I've set up in Home Assistant. Two environment variables, restart the gateway, and natural language device control works immediately.

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, no scene, no script — just the agent calling 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:

Tool	What it does
`ha_list_entities`	Query entities by domain or area
`ha_get_state`	Get current state and attributes of an entity
`ha_list_services`	List available actions for a device
`ha_call_service`	Execute a command

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.

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.