# Home Assistant

Fregata exposes the **same HTTP API and MQTT topics as upstream
Frigate**, so the official Frigate Home Assistant integration works
unchanged. You install it in HA, point it at your Mac's IP and port
8971, and Fregata's cameras, events, and detection state appear as
HA entities.

## What you'll get in HA

Once the integration is connected, each Fregata camera produces:

- **`camera.<name>`** — the live MJPEG/MSE feed for the dashboard.
- **`binary_sensor.<name>_motion`** — true while motion is in
  progress.
- **`binary_sensor.<name>_<object>`** — one per tracked class
  (`_person`, `_car`, etc.), true while that object is in frame.
- **`sensor.<name>_<object>_count`** — current count of that class.
- **`switch.<name>_detect`**, **`_recordings`**, **`_snapshots`** —
  toggles for the per-camera features.

Plus a global `update.frigate_server`, and a `media_source` for
playing back recordings and event clips inside HA.

## Setup

### 1. Install HACS in Home Assistant (if you haven't)

The Frigate HA integration ships through HACS, not core HA. Follow
[HACS installation](https://hacs.xyz/docs/use/) if you don't already
have it.

### 2. Add the Frigate integration to HACS

In HA: **HACS → Integrations → ⋮ → Custom repositories** and add:

```
https://github.com/blakeblackshear/frigate-hacs-integration
```

…as an "Integration" repository. Then search for "Frigate" in the
HACS Integrations list and install.

Restart HA.

### 3. Configure the integration

**Settings → Devices & Services → Add Integration → Frigate**.

In the URL field, enter the HTTPS address your HA instance can reach
Fregata at:

```
https://<mac-ip-or-hostname>:8971
```

For example, `https://10.0.1.42:8971` or `https://mac-mini.local:8971`.

Fregata serves HTTPS with a **self-signed** certificate by default, so
**turn off "Validate SSL"** in the integration's config — otherwise HA
won't trust the certificate. The Frigate integration has that checkbox
for exactly this case.

:::caution
Use the LAN IP / hostname, **not** `127.0.0.1` or `localhost`, unless
you're running HA on the same Mac as Fregata. HA needs to reach the
Mac from wherever it's running.
:::

:::tip[Reaching it from outside your LAN]
For remote access, front Fregata with a reverse proxy that has a real
certificate (see
[Network & remote access](/guides/network-and-remote-access/#putting-fregata-behind-a-reverse-proxy))
and point HA at the proxy's `https://…` URL — then you can leave
**Validate SSL** on.
:::

### 4. (Optional) MQTT

For best responsiveness you'll also want MQTT — HA gets push events
when objects appear and disappear instead of polling. Add an `mqtt`
block to `~/Fregata/config/config.yml`:

```yaml
mqtt:
  enabled: true
  host: 10.0.1.42      # your MQTT broker; HA's Mosquitto add-on is fine
  port: 1883
  user: fregata
  password: {FREGATA_MQTT_PASSWORD}
```

Set `FREGATA_MQTT_PASSWORD` in **Settings → Environment Variables**
(or paste it in plaintext if you're not the secrets-management type
— Fregata's config never leaves the Mac).

Restart Frigate from the tray to pick up the MQTT settings.

## Automations

The integration's docs at
[blakeblackshear.github.io/frigate-hacs-integration](https://blakeblackshear.github.io/frigate-hacs-integration/)
have a full walkthrough of automations. The two most useful starting
templates:

### Person on the front porch

```yaml
automation:
  - alias: Notify on front-porch person
    trigger:
      - platform: state
        entity_id: binary_sensor.front_porch_person
        to: 'on'
    action:
      - service: notify.mobile_app_my_phone
        data:
          message: "Person on front porch"
          data:
            image: "/api/frigate/notifications/{{ trigger.to_state.attributes.event_id }}/snapshot.jpg"
```

### Auto-disable detection while you're home

```yaml
automation:
  - alias: Pause Fregata detection when home
    trigger:
      - platform: state
        entity_id: person.you
        to: home
    action:
      - service: switch.turn_off
        target:
          entity_id:
            - switch.front_porch_detect
            - switch.driveway_detect
```

The second one is a common privacy ask — pause object detection on
indoor cameras when you're physically there. Recordings keep going
unless you also flip `_recordings`.

## Troubleshooting the integration

The most common failure modes:

- **Cameras don't appear** — the integration couldn't reach Fregata's
  `/api/config`. Open the URL you configured above in a browser on the
  same network as HA. If it doesn't load, the issue is between HA and
  your Mac, not in the integration.
- **Clips/snapshots fail to play in HA** — the integration uses
  `media_source` URIs that point back at the Fregata HTTP server.
  HA needs to be able to reach those URIs from whichever browser
  you're viewing HA on. If you're on a VPN or different subnet, you
  may need to expose Fregata via your reverse proxy too.
- **Counts stay at zero** — MQTT isn't connected. Check the Frigate
  log via the tray's **Settings → Open Frigate Logs**; an MQTT
  connection failure appears prominently.