Summary

Setting HASS_TOKEN in the environment unconditionally enables the Home Assistant gateway platform in gateway/config.py, even when the user has explicitly set platforms.homeassistant.enabled: false in ~/.hermes/config.yaml. There is no documented or supported way to keep the HA tools (ha_list_entities, ha_call_service, etc.) working while disabling the gateway platform (real-time event listener), because they share the same HASS_TOKEN activation path.

This is the symmetric counterpart of #13827 (config-only setup is blocked by env-only checks); both share the same root cause: env vars and PlatformConfig are not unified, and env-only activation wins.

Affected code

• gateway/config.py:1351-1360 — the env-var loader for HA unconditionally sets enabled=True:

# Home Assistant
hass_token = os.getenv("HASS_TOKEN")
if hass_token:
    if Platform.HOMEASSISTANT not in config.platforms:
        config.platforms[Platform.HOMEASSISTANT] = PlatformConfig()
    config.platforms[Platform.HOMEASSISTANT].enabled = True   # <-- overrides config.yaml
    config.platforms[Platform.HOMEASSISTANT].token = hass_token
    hass_url = os.getenv("HASS_URL")
    if hass_url:
        config.platforms[Platform.HOMEASSISTANT].extra["url"] = hass_url

• gateway/platforms/homeassistant.py:122-125 — the gateway adapter then warns at every startup because no watch_* filters are configured:

[Homeassistant] No watch_domains, watch_entities, or watch_all configured.
All state_changed events will be dropped. Configure filters in your HA platform
config to receive events.

Why this is a bug

Per website/docs/user-guide/messaging/homeassistant.md, the tools and the gateway platform are two distinct integrations, both activated from the same HASS_TOKEN. A reasonable user need is "give me the four HA tools so the agent can control my home, but don't push real-time state_changed events into my chat platforms." Today there is no way to express that: the enabled: false knob in config.yaml is silently overwritten by the env-var loader.

Minimal reproduction

1. Set HASS_TOKEN and HASS_URL in ~/.hermes/.env.
2. Set in ~/.hermes/config.yaml:

   platforms:
     homeassistant:
       enabled: false

3. Restart the gateway: launchctl kickstart -k gui/$UID/ai.hermes.gateway (or equivalent).
4. Observe ~/.hermes/logs/gateway.log:

INFO  gateway.run: Connecting to homeassistant...
INFO  gateway.platforms.homeassistant: [Homeassistant] Connected to http://homeassistant.local:8123
WARN  gateway.platforms.homeassistant: [Homeassistant] No watch_domains, watch_entities, or watch_all configured. All state_changed events will be dropped.

Platform is connected. enabled: false was ignored.

Expected behavior

config.platforms[Platform.HOMEASSISTANT].enabled set explicitly to false in ~/.hermes/config.yaml should be honored — the gateway platform should not connect, while the LLM toolset (HASS_TOKEN-driven) continues to work.

Equivalently: if the env-var loader runs after config.yaml is parsed, it should not overwrite an explicit enabled: false.

Actual behavior

The env-var loader unconditionally sets enabled=True whenever HASS_TOKEN is set, silently overriding the user's config.yaml.

Current workaround

Configure a no-op filter to satisfy the warning's tri-condition (not domains and not entities and not all):

platforms:
  homeassistant:
    extra:
      watch_entities:
        - sensor.__hermes_noop__

This silences the warning and prevents any events from forwarding (the no-op entity never matches), but the platform still consumes a WebSocket connection to HA. Real fix should let users opt out of the gateway platform entirely while keeping the tools.

Suggested fixes (any of these)

1. Honor a user-set platforms.homeassistant.enabled: false even when HASS_TOKEN is present — i.e., only set enabled = True if it isn't already explicitly False.
2. Add a separate env var (HASS_GATEWAY_PLATFORM=0) that disables the gateway platform without disabling the tools.
3. Decouple the tools and the gateway platform so each can be enabled/disabled independently — HASS_TOKEN activates the tools, and a separate explicit opt-in activates the gateway platform.

Related

• #13827 — config-backed HA / Mattermost / Signal adapters blocked by env-only requirement checks (the symmetric direction)

Environment

• Hermes Agent v0.13.0 (2026.5.7)
• macOS 25.4.0 (Darwin)
• Python 3.11.14