---
name: homeassistant-integration
description: "Connect Home Assistant to Hermes — token setup, toolset enablement, and smart home control via Hermes tools."
version: 1.2.0
author: ray
platforms: [linux]
created_by: "agent"
metadata:
  hermes:
    tags: [smart-home, homeassistant, integration, ha]
  requires:
    env_vars: ["HASS_TOKEN", "HASS_URL"]
    toolsets: ["homeassistant"]
    gateway_restart: true
---

# Home Assistant + Hermes Integration

Connect a Home Assistant instance to Hermes so the agent can list entities, read sensor states, discover services, and control devices (lights, switches, climate, media players, etc.) via the `homeassistant` toolset.

## Prerequisites

- A running Home Assistant instance (local network or remote)
- A **Long-Lived Access Token** from your HA profile page (click your username → Security → Long-Lived Access Tokens)
- The HA server accessible from the Hermes host

## Setup

### 1. Get a Long-Lived Access Token

In Home Assistant: **click your user profile** (bottom-left) → **Security** → **Long-Lived Access Tokens** → **Create Token**.

The token is a JWT that looks like:
```
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOi...<rest of token>
```

You can decode it to verify:
```bash
python3 -c "
import base64, json
payload = base64.urlsafe_b64decode('PAYLOAD_SECTION' + '==')
data = json.loads(payload)
print(f'Issuer: {data[\"iss\"]}')
print(f'Expires: {data[\"exp\"]}')
"
```
HA long-lived access tokens typically expire in 10 years.

### 2. Set the Environment Variables

```bash
hermes config set HASS_URL http://YOUR_HA_HOST:8123
hermes config set HASS_TOKEN <your-long-lived-access-token>
```

`hermes config set` auto-detects secrets — the URL goes to `config.yaml`, the token goes to `.env`. The tool code reads **both** from environment variables, so if `HASS_URL` landed in config.yaml instead of `.env`, add it to `.env` as well:

```bash
echo 'HASS_URL=http://YOUR_HA_HOST:8123' >> ~/.hermes/.env
```

Verify they're in place:
```bash
grep HASS ~/.hermes/.env
```

### 3. Enable the Toolset

```bash
hermes tools enable homeassistant
```

Verify:
```bash
hermes tools list | grep homeassistant
# ✓ enabled  homeassistant  🏠 Home Assistant
```

### 4. Verify the Token Works

Test with a direct API call before restarting the gateway:

```bash
python3 -c "
import json, urllib.request, subprocess
token = subprocess.run(['grep', 'HASS_TOKEN', '$HOME/.hermes/.env'],
    capture_output=True, text=True).stdout.strip().split('=',1)[1]
req = urllib.request.Request('http://YOUR_HA_HOST:8123/api/',
    headers={'Authorization': f'Bearer {token}'})
data = json.loads(urllib.request.urlopen(req, timeout=10).read())
print(f'HA: {data.get(\"location_name\", \"unnamed\")}')
"
```

Also check entity count:
```bash
# Same pattern, hit /api/states instead and count by domain
```

If you get **HTTP 200**, the token is valid and the URL is reachable.

### 5. Restart the Gateway

Tool changes require a new session. Restart the gateway:

```bash
hermes gateway restart
```

After restart, the agent has access to four HA tools:

| Tool | Purpose |
|------|---------|
| `ha_list_entities` | List/filter entities by domain or area |
| `ha_get_state` | Get detailed state + attributes of one entity |
| `ha_list_services` | Discover available services (actions) per domain |
| `ha_call_service` | Control a device (turn_on, turn_off, set_temperature, etc.) |

## Security

The `homeassistant_tool.py` implementation blocks these high-risk service domains for safety:
`shell_command`, `command_line`, `python_script`, `pyscript`, `hassio`, `rest_command`

## Automation Patterns

### Cron-Based Condition Monitoring

Use Hermes cron jobs to poll an HA entity and act when a condition is met (e.g., turn off AC when temp drops to target). The cron job should self-terminate after acting.

**Recipe — trigger action on sensor threshold:**

```
cronjob(action='create',
  name='<descriptive name>',
  prompt='Check <entity_id> using ha_get_state. If <condition>, call ha_call_service to <action> and report success, then use cronjob to remove this monitoring job (job_id in context). If condition not met, report current state briefly and do nothing.',
  schedule='*/10 22-23,0-2 * * *',   # every 10 min from 10pm–2am (use CRON EXPRESSION, not "10m" — that's a one-shot)
  repeat=20,
  toolsets=['homeassistant', 'cronjob'])
```

Key details:
- **toolsets**: Must include both `homeassistant` and `cronjob` so the cron agent can check sensors, call services, and remove itself.
- **Schedule**: Use `*/N hour-range * * *` for time-windowed polling (e.g., `*/7 22-23,0-2 * * *` = every 7 minutes from 10 PM through 2 AM). Avoid starting monitoring before the user wants it — use the cron expression to delay first run.
- **CRITICAL — schedule format**: Simple time strings like `"10m"` or `"30m"` are parsed as **one-shot** ("once in 10 minutes"), NOT recurring. The cron will run exactly once and then stop. Always use cron expressions (`*/10 * * * *`) or `"every 10m"` for recurring jobs. A job that silently runs once and completes without acting is the #1 failure mode for HVAC monitoring.
- **Repeat limit**: Cap with `repeat` to prevent indefinite polling. With N-minute intervals, `repeat=20` covers ~N×20 minutes.
- **Prompt must include self-removal**: The job should call `cronjob(action='remove', job_id=...)` after acting so it doesn't keep polling indefinitely.
- **Schedule corrections**: Users often tweak poll intervals or start times after creation. Use `cronjob(action='update', job_id=..., schedule=...)` rather than deleting and recreating.

## Pitfalls

- **Home Assistant behind VPS reverse proxy:** When proxying HA through an external nginx (VPS + Tailscale), add the proxy's Tailscale IP to `trusted_proxies` in `configuration.yaml` or HA returns 400:
  ```yaml
  http:
    use_x_forwarded_for: true
    trusted_proxies:
      - 127.0.0.1
      - 100.86.68.23   # VPS Tailscale IP
  ```
  Restart: `docker restart homeassistant`. See `docker-service-deployment` skill, `references/vps-migration.md` for the full VPS setup pattern.
- **CRITICAL — Cron schedule format:** Bare duration strings like `"10m"` or `"30m"` are ONE-SHOT ("once in X minutes"). The job runs exactly once and silently completes — the #1 failure mode for HVAC monitoring. Always use **cron expressions**: `"*/10 * * * *"` (every 10 minutes), `"*/7 22-23,0-2 * * *"` (time-windowed). Alternative: `"every 10m"` shorthand. Verify with `cronjob(action='list')` after creation — `"once in Nm"` means it won't repeat.
- **Climate vs sensor entities:** Climate entities (`climate.upstairs`) are the thermostat — call `ha_call_service` to control them. Sensor entities (`sensor.upstairs_temperature`) are read-only readings. For threshold monitoring, check the sensor for the reading but control the climate entity.
- **HASS_URL must be in .env**: The tool reads `os.getenv("HASS_URL")`, not `config.yaml`. Add it to `.env` explicitly.
- **Docs 404**: The Hermes docs page for Home Assistant integration returns 404. Canonical reference: `tools/homeassistant_tool.py` and `gateway/config.py`.
- **Subprocesses don't inherit .env**: When testing with `python3 -c`, read secrets via `subprocess.run(['grep', ...])` instead of `os.getenv()`.
- **Gateway restart required**: Toolset changes need `hermes gateway restart`.
- **Internal vs proxy URL**: The tool needs the direct API URL (e.g., `http://192.168.50.98:8123`), not the external proxy port.
- **Entity registry may 404**: Use `/api/config/config_entries/entry` instead to discover integrations and device metadata.

### Two-Phase Monitoring (Wide → Narrow Polling)

When the target is far away, poll infrequently to save resources. When it nears the threshold, switch to tight polling automatically.

**How it works:** The cron job starts with a wide interval (e.g., every 30 min). When the sensor value enters a "close" zone, the job updates its own schedule to a tight interval (e.g., every 7 min). When the final threshold is hit, it acts and removes itself.

**Recipe:**

```
# Phase 1 — wide polling (every 30 min on the half-hour, 10pm–2am)
cronjob(action='create',
  name='Turn off AC when temp hits 78°F',
  prompt='Check climate.upstairs with ha_get_state. '
    'If temp > 79°F: report briefly, do nothing (stay in wide-poll mode). '
    'If temp ≤ 79°F and > 78°F: UPGRADE this job to tight polling — '
    'cronjob(action=update, job_id=THIS_JOB_ID, schedule="*/7 22-23,0-2 * * *"). '\
    'Report "now monitoring closely." '
    'If temp ≤ 78°F: ha_call_service(domain=climate, service=turn_off, '
    'entity_id=climate.upstairs), report success, remove this job.',
  schedule='0,30 22-23,0-2 * * *',
  repeat=20,
  toolsets=['homeassistant','cronjob'])
```

Once upgraded to Phase 2, the job's prompt should know it's in tight mode: check temp, act if ≤ target, otherwise report and wait. The prompt must handle both modes so it works correctly after a self-upgrade.

Key points:
- **Phase 1 prompt** must include the self-upgrade logic (wide → tight) AND the final action logic (act + self-remove).
- **Phase 2 prompt** (after upgrade) only needs: check, act-if-condition-met, otherwise report.
- **Use `repeat`** to cap total runs so the job doesn't poll forever if the condition never triggers.
- Users often specify multiple constraints (interval, start time, threshold-based frequency). Ask clarifying questions if the intent is ambiguous, and prefer the two-phase pattern when the target is expected to drift slowly.

## IoT Device Onboarding

For finding, identifying, and adding new WiFi IoT devices to the network and Home Assistant — WiFi setup, IP discovery, MAC vendor lookup, LAN mode enablement, and HA integration — see `references/iot-device-onboarding.md`.

## Identifying Devices & Integrations

### Thermostat Model / Integration Discovery

The entity states API (`/api/states`) doesn't expose manufacturer or model info. To find what integration provides a climate entity and what hardware it's connected to, query the HA config entries API:

```python
import json, urllib.request

# List all config entries (integrations)
req = urllib.request.Request(
    'http://HA_HOST:8123/api/config/config_entries/entry',
    headers={'Authorization': f'Bearer {token}'})
entries = json.loads(urllib.request.urlopen(req).read())

for entry in entries:
    if entry.get('domain') == 'honeywell':  # or 'ecobee', 'nest', etc.
        print(f"Title: {entry['title']}, State: {entry['state']}")
```

The `domain` field reveals the integration (e.g., `honeywell`, `ecobee`, `nest`). The entity registry endpoints (`/api/config/entity_registry/*`) may 404 depending on HA version or reverse-proxy setup — the config entries API is a reliable fallback.