Ship Home Assistant OS logs to Grafana Loki using Grafana Alloy — the modern replacement for the deprecated Promtail add-on.
The official Promtail add-on (v2.2.0) bundles Promtail 2.6.1, which cannot read the compact journal format introduced in systemd 252+ (HAOS 11+). This means Promtail silently fails to ship logs on modern HAOS installations.
Grafana Alloy is the official successor to Promtail, Grafana Agent, and Grafana Agent Flow. It uses a component-based pipeline architecture and has native systemd journal support that works with all journal formats.
- Open Settings > Add-ons > Add-on Store
- Click the overflow menu (three dots, top-right) > Repositories
- Paste:
https://github.com/AlanJohnWilliams/ha-addon-alloy - Click Add > Close
- Find Grafana Alloy in the store and click Install
This fork is the sole sanctioned install source. Do not add the upstream
ecohash-corepository — the binary is pinned + SHA256-verified only here.
Set loki_url to your Loki push endpoint. Prefer https://; if you must ship
over plaintext HTTP with a bearer token (e.g. a trusted-LAN Loki proxy), you must
also set allow_insecure_bearer: true (see below).
loki_url: "https://loki.example.com:3100/loki/api/v1/push"
site: boulder
loki_bearer_token: "<your-loki-bearer-token>" # stored as a secret, never logged
log_level: infoThe bearer token is written to a 0600 file and referenced via Alloy's
bearer_token_file — it never appears in the generated config, the debug UI, or
the logs. Because the token rides in /data/options.json, encrypt your Home
Assistant backups. See RUNBOOK.md and SECURITY.md.
All systemd journal entries from HAOS, including:
- Home Assistant Core logs
- Add-on/app container logs
- Supervisor logs
- Host system logs (kernel, networkd, etc.)
Labels applied: unit, hostname, syslog_identifier, transport, container_name, level, host (homeassistant-<site>).
The Alloy pipeline inspector listens on 12345 inside the container (used by the watchdog) but is not published to the host/LAN by default. Map the port temporarily via the add-on Network panel if you need it.
MIT