A Home Assistant custom integration for Gatus - a health check and monitoring tool.
This integration connects to your Gatus instance and creates binary sensors for each monitored endpoint using the Problem device class. This means:
- Off (OK): The endpoint is healthy and passing checks
- On (Problem): The endpoint is failing or unreachable
One sensor is created for each endpoint monitored by Gatus:
Device Class: problem
- Off: Service is healthy (check passed)
- On: Service has a problem (check failed)
Attributes Available:
endpoint_group: The group name from Gatus (e.g., "media", "external")endpoint_name: The endpoint name from Gatus (e.g., "plex", "google")hostname: The hostname being monitoredstatus_code: HTTP status code from the health check (e.g., 200, 404)duration_ms: Response time in millisecondstimestamp: ISO timestamp of the last health check
Since these are problem sensors, they work by waiting for the to turn 'on' for alerting:
# Example: Alert when a service has a problem
alias: ESP Connect down
description: Alert when ESP Connect service is unreachable
triggers:
- trigger: state
entity_id:
- >-
binary_sensor.home_automation_espconnect
to:
- "on"
conditions: []
actions:
- action: notify.notify
metadata: {}
data:
title: ESP Connect is down!
message: >-
Status code: {{
state_attr('binary_sensor.home_automation_espconnect',
'status_code') }}
mode: singleThe easiest way to install this integration is with HACS. First, install HACS if you don't have it yet. In Home Assistant, go to HACS -> Integrations, click on + Explore & Download Repositories, search for Gatus, and click download. After download, restart Home Assistant.
Once the integration is installed, you can add it to the Home Assistant by going to Configuration -> Devices & Services, clicking + Add Integration and searching for Gatus or, using My Home Assistant service, you can click on:
- Copy the
custom_components/gatusfolder to your Home Assistantcustom_componentsdirectory - Restart Home Assistant
- Go to Settings → Devices & Services
- Click + Add Integration
- Search for "Gatus Integration"
- Enter your Gatus URL (e.g.,
https://gatus.example.com) - The integration will automatically discover all endpoints from your Gatus instance
Gatus URL: https://gatus.apps.openshift.ullberg.family
This will create binary sensors like:
binary_sensor.adsb_dump978- Shows "Problem" if ADSB dump978 is downbinary_sensor.external_google- Shows "Problem" if Google is unreachablebinary_sensor.media_plex- Shows "Problem" if Plex is down- etc.
All sensors will show "OK" when services are healthy and "Problem" when they fail health checks.
The integration polls Gatus every minute to update the status of all endpoints.
This integration was built using the Home Assistant integration blueprint.
- Open this repository in Visual Studio Code devcontainer
- Run
./scripts/developto start Home Assistant for testing
See LICENSE file for details.
Gatus and other names are trademarks of their respective owners.