Beacon Home Assistant Add-on

Lightweight monitoring, alerting, and secure remote access agent for Home Assistant. Optional BeaconInfra cloud for multi-device dashboards, metrics, and tunneling.

Features

• Local dashboard embedded in the HA sidebar via Ingress
• Health check monitoring — HTTP, port, and command checks (HA health check pre-configured)
• System metrics — CPU, memory, disk, load average
• Alerts — Discord, Slack, webhooks
• BeaconInfra cloud — multi-device dashboard and secure remote tunnels (optional, requires API key)
• Fully offline mode — no API key means zero cloud connectivity or telemetry

Installation

BeaconInfra guided setup

If you are connecting Home Assistant to BeaconInfra, open HA Setup in the BeaconInfra dashboard first. It creates the API key, gives you the repository URL, and watches for the first heartbeat after you start the add-on.

Manual setup

1. In Home Assistant, go to Settings > Apps > Install Apps
2. Click the ... menu in the right upper corner and select Repositories
3. Add this repository URL:

   https://github.com/Bajusz15/beacon-home-assistant-addon
   

4. Find Beacon and click Install
5. Configure your options and click Start

For cloud mode, paste the full BeaconInfra API key into api_key. To expose Home Assistant remotely through BeaconInfra, enable tunnel_home_assistant.

Home Assistant OS proxy trust

When tunnel_home_assistant is enabled, Beacon forwards browser requests to Home Assistant Core through the add-on network. Home Assistant must trust those reverse-proxy headers. Add or merge this in /config/configuration.yaml, then restart Home Assistant Core:

http:
  use_x_forwarded_for: true
  trusted_proxies:
    - 172.30.0.0/16
    - 172.16.0.0/12
    - 127.0.0.1

Without this, the tunnel can connect but Home Assistant may return 400 Bad Request for proxied requests.

Configuration

Option	Default	Description
device_name	(hostname)	Friendly name for this device
api_key	(empty)	BeaconInfra API key for cloud features
heartbeat_interval	30	Seconds between cloud heartbeats (10-300)
metrics_port	9100	Local dashboard and metrics port

See DOCS.md for full documentation.

Supported Architectures

• aarch64 (Raspberry Pi 4/5)
• armv7 (Raspberry Pi 3)
• amd64 (x86_64)

Links

• BeaconInfra Cloud
• Beacon Agent Source