Skip to main content

Alpha Features Guide

This guide covers how to install and use the Alpha version of Home-Assistant-Matter-Hub.

[!WARNING] Alpha versions are for testing only and may contain bugs. Use at your own risk!

Installing the Alpha Version​

Home Assistant Add-on​

  1. Add the repository: https://github.com/riddix/home-assistant-addons
  2. Install Home-Assistant-Matter-Hub (Alpha) from the Add-on Store
  3. The Alpha add-on runs independently from the stable version

Docker​

Use the alpha tag instead of latest:

docker run -d \
  --name home-assistant-matter-hub-alpha \
  --network host \
  -v /path/to/data:/data \
  -e HAMH_HOME_ASSISTANT_URL=http://homeassistant.local:8123 \
  -e HAMH_HOME_ASSISTANT_ACCESS_TOKEN=your_token \
  ghcr.io/riddix/home-assistant-matter-hub:alpha

Current Alpha Features​

Alpha is ahead of Stable (v2.0.58) with a clearer mDNS IPv6 warning, a label query fix, a session log cleanup, a device list change log line, maps and floors for vacuum custom areas, a camera live view that can reach SmartThings, readable camera errors from HA, high resolution camera streams, a no keypad option for locks, colors sent right after On, a steady fan speed range while a fan is unavailable, a full clean from Apple Home for CLEAN_AREA vacuums, and the endpoint fixes for the coming matter.js 0.18 (second vacuum and EVSE mode, tilting shutters, unlock with timeout, long press, TVs without playback), the matter.js 0.18 RC with Matter 1.6.1 (unpatched since alpha.931), opt-in session rotation in server mode, and EVSE charging target commands. See the alpha notes for each release. Standalone Devices graduated to Stable in v2.0.47, see Standalone Devices.

For a complete list of all supported features and device types, see Supported Device Types.

Tips for Alpha Testing​

Backup Your Data​

Before upgrading to Alpha, backup your configuration:

# Docker
cp -r /path/to/data /path/to/data-backup

# Home Assistant Add-on
# Data is stored in /config/home-assistant-matter-hub

Run Alpha Separately​

You can run both Stable and Alpha versions simultaneously:

  • Use different ports (e.g., 8482 for stable, 8483 for alpha)
  • Use different data directories
  • Use different Matter ports for bridges

Reporting Issues​

When reporting Alpha issues, please include:

  • Alpha version number
  • Logs from the add-on/container
  • Steps to reproduce the issue
  • Controller type (Google, Apple, Alexa)

Common Alpha Issues​

Bridge not starting:

  • Check logs for specific errors
  • Verify port is not in use
  • Try factory reset of the bridge

Entities not appearing:

  • Verify filter configuration
  • Check entity is supported
  • Review logs for errors during device creation

Controller not connecting:

  • Ensure IPv6 is enabled
  • Check mDNS/UDP routing
  • Verify port is accessible

Reverting to Stable​

If you encounter issues with Alpha:

  1. Stop the Alpha add-on/container
  2. Install the Stable version
  3. Your paired devices should reconnect automatically
  4. Some new features may not be available

[!NOTE] Configuration data is compatible between versions. Your bridges and settings will be preserved.