Documentation › Home Assistant Integration

Home Assistant Integration

BunkerM is available as a native Home Assistant add-on. It runs the complete BunkerM stack - Mosquitto broker, web dashboard, and all backend services - managed by the HA supervisor. This is the recommended approach if you are already running Home Assistant OS or Supervised.

Prerequisites

  • Home Assistant OS or Home Assistant Supervised (Supervisor support required)
  • Internet access from the HA host (to download the add-on)
  • Access to the Home Assistant web interface

Step 1: Add the BunkerM Repository

Third-party add-on repositories must be added manually:

  1. In Home Assistant, go to Settings > Add-ons.
  2. Click Add-on Store in the bottom-right corner.
  3. Click the three-dot menu (top-right) and select Repositories.
  4. Enter the following URL and click Add:
https://github.com/bunkeriot/bunkerm-ha-addons

Click Close. The BunkerM add-on now appears in your Add-on Store.

Step 2: Install BunkerM

  1. In the Add-on Store, search for BunkerM.
  2. Click the BunkerM add-on card.
  3. Click Install and wait for the download to complete (a few minutes depending on your connection).

Step 3: Configure the Add-On

Before starting, set your credentials in the Configuration tab:

  • mqtt_username - username for MQTT broker connections (default: bunker)
  • mqtt_password - password for MQTT connections (default: bunker)
  • admin_email - login email for the BunkerM web UI (default: admin@bunker.local)
  • admin_password - login password for the web UI (default: admin123)
Change the default credentials before connecting any devices. The defaults are public and should not be used in production.

Click Save after updating the options.

Step 4: Start the Add-On

  1. Go to the Info tab of the BunkerM add-on.
  2. Click Start.
  3. Optionally enable Start on boot and Watchdog for automatic startup and crash recovery.

Step 5: Open the BunkerM Web UI

Once running, access the web interface at:

http://homeassistant.local:2000

Or using your HA host's IP address:

http://192.168.1.x:2000

You can also click Open Web UI from the add-on info page.

Step 6: Connect Home Assistant's MQTT Integration

  1. In Home Assistant, go to Settings > Devices & Services.
  2. Click Add Integration and search for MQTT.
  3. Enter the broker connection details:
    • Broker: homeassistant.local or your HA IP
    • Port: 1883
    • Username: the mqtt_username from your add-on config
    • Password: the mqtt_password from your add-on config
  4. Click Submit, then Finish.
Port note: The HA add-on uses the standard MQTT port 1883 (not 1900 as in the standalone Docker deployment) so that HA integrations and devices connect without extra configuration.

Persistence

All BunkerM data is stored in Home Assistant's /data directory for the add-on. MQTT clients, ACLs, web UI accounts, and BunkerAI settings all persist across add-on restarts and are included in Home Assistant snapshots/backups.

Troubleshooting

  • Add-on does not start - check the Log tab. Common cause: port conflict on 2000 or 1883.
  • Cannot access the web UI - verify the add-on is running (green status). Check that port 2000 is not blocked by a firewall.
  • HA MQTT cannot connect - verify the username and password match the add-on configuration. Check the BunkerM ACL Clients page to confirm the account is enabled.
← BunkerAI Setup Telegram →