Skip to main content

​
Home Assistant Integration

FERAL integrates with Home Assistant as a native add-on, giving your AI brain direct access to every device, entity, automation, and sensor in your smart home.

​
Installation

​
Add-on Installation

  1. Open Home Assistant → Settings → Add-ons → Add-on Store
  2. Click the three dots (top right) → Repositories
  3. Add the FERAL repository URL: 
    https://github.com/FERAL-AI/ha-addon
  4. Find “FERAL Brain” in the store and click Install
  5. Go to the add-on’s Configuration tab to set your LLM provider and API key
  6. Click Start

​
Manual Installation

If you prefer running FERAL alongside (not inside) Home Assistant: 
export FERAL_HA_URL="http://homeassistant.local:8123"
export FERAL_HA_TOKEN="your-long-lived-access-token"
feral start
Generate a long-lived access token from your HA profile page: Profile → Security → Long-Lived Access Tokens → Create Token.

​
Configuration

VariableDefaultDescription
FERAL_HA_URLhttp://homeassistant.local:8123Home Assistant instance URL
FERAL_HA_TOKEN(required)Long-lived access token
FERAL_HA_WEBHOOK_IDferal-brainWebhook ID for HA → FERAL events
FERAL_HA_AREAS(all)Comma-separated area filter (e.g. living_room,kitchen)
When running as an add-on, FERAL_HA_URL and FERAL_HA_TOKEN are auto-configured via the Supervisor API.

​
What Devices Become Accessible

Once connected, FERAL can see and control every entity exposed in Home Assistant:
CategoryExamples
LightsOn/off, brightness, color temperature, RGB
Switches & plugsSmart plugs, relays, power strips
ClimateThermostats, AC units, fans, humidifiers
SensorsTemperature, humidity, motion, door/window, energy
MediaSpeakers, TVs, media players
CoversBlinds, garage doors, curtains
LocksSmart locks, deadbolts
CamerasSnapshot and stream access
AutomationsTrigger, enable/disable existing automations

​
Usage Examples

"Turn off all the lights in the bedroom"
→ Calls service: light.turn_off for area bedroom

"What's the temperature in the kitchen?"
→ Reads sensor.kitchen_temperature → "72.4°F"

"Lock the front door and arm the alarm"
→ Calls lock.lock + alarm_control_panel.arm_away

"Run the 'movie time' automation"
→ Triggers automation.movie_time

​
Supervisor API

When running as an add-on, FERAL uses the Home Assistant Supervisor API for:
  • Auto-discovery — automatically finds the HA instance
  • Ingress — the FERAL dashboard is accessible through the HA sidebar
  • Add-on management — restart, update, and configure from the HA UI
  • Backup integration — FERAL’s memory and config are included in HA backups
The add-on communicates with HA over the internal Docker network using the Supervisor token, so no manual token configuration is needed.

​
Architecture

┌──────────────┐          ┌──────────────┐          ┌──────────────┐
│  Smart Home  │   Z-Wave │    Home      │  REST +  │  FERAL Brain │
│  Devices     │  Zigbee  │  Assistant   │  WS API  │  (Add-on)    │
│  (400+ int.) │  WiFi    │  (Supervisor)│ ◄──────► │              │
└──────────────┘ ───────► └──────────────┘          └──────────────┘

​
Event Streaming

FERAL subscribes to Home Assistant’s WebSocket event stream. When state changes occur (a door opens, temperature spikes, motion detected), FERAL receives them in real-time and can:
  • Log the event to memory
  • Trigger proactive alerts (“Your front door has been open for 10 minutes”)
  • Execute learned skills in response

​
Security

  • The long-lived access token is stored in FERAL’s encrypted credentials file (~/.feral/credentials.json, mode 0600)
  • When running as an add-on, the Supervisor token is ephemeral and rotated automatically
  • FERAL never exposes your HA token to external services

​
Troubleshooting

Verify the URL is reachable: curl http://homeassistant.local:8123/api/. Ensure the long-lived token is valid and hasn’t expired.
FERAL only sees entities exposed in HA. Check that your devices are not hidden in Settings → Entities. Try filtering with FERAL_HA_AREAS.
Check the add-on logs in Settings → Add-ons → FERAL Brain → Log. Common issues: missing LLM config, port conflicts.