Updated for 2026. This guide explains what Matterhub is, when to use it versus the built-in Home Assistant Matter integration, and how to set it up step by step.

Matterhub and Home Assistant: The Complete Setup Guide

If you’ve ever owned a HomeKit-only smart device and wished Home Assistant could see it natively, Matterhub is the bridge that solves the problem. Matterhub is an open-source project that takes HomeKit accessories and exposes them as Matter devices, which Home Assistant’s built-in Matter integration can then commission and control locally. This guide covers what Matterhub does, when to reach for it, how it differs from regular Matter setup in Home Assistant, and a step-by-step install.

For general Matter integration without HomeKit-specific needs, see our dedicated Home Assistant Matter Support 2026 guide.

What is Matterhub?

Matterhub is a community-built bridge that translates between two protocols: HomeKit Accessory Protocol (HAP), used by Apple HomeKit-certified devices, and Matter, the universal smart home standard. It runs as a server, pairs with HomeKit accessories using their HomeKit pairing codes, and presents those same accessories as Matter devices on your network. Home Assistant’s Matter integration then commissions the Matterhub bridge as if it were a regular Matter device, gaining access to all the HomeKit accessories behind it.

Practical use cases:

• You have a HomeKit-only smart lock or doorbell and want it in Home Assistant without a cloud bridge
• You’re moving away from Apple Home as your primary controller but still have HomeKit-only accessories
• You want HomeKit accessories controllable via Home Assistant automations alongside Zigbee, Z-Wave, and native Matter devices

Matterhub vs Home Assistant Matter Hub: What’s the Difference?

This naming confuses people, so let’s clarify:

• Home Assistant Matter integration: built into HA core. Commissions Matter-certified devices directly. Works with Thread Border Routers like the Connect ZBT-1 or HA Yellow.
• Matterhub (the project): third-party software that wraps HomeKit accessories so they look like Matter devices to other controllers. Solves a niche problem: HomeKit-only hardware.
• “Matter hub” in general: any device or software that acts as the central Matter controller. Home Assistant itself is a Matter hub when its Matter integration is active.

If you have native Matter devices, you don’t need Matterhub. Use the built-in HA Matter integration. If you have HomeKit-only accessories, Matterhub fills the gap.

Alternatives to Matterhub

Before installing Matterhub, check if simpler options work:

• HomeKit Controller integration (built into HA): pairs HomeKit accessories directly with Home Assistant. No Matter needed at all. If this works for your device, use it instead – much simpler.
• Matter Bridge in HA: Home Assistant can export its devices TO other Matter controllers. Different direction than Matterhub.
• homebridge-matter: similar concept, runs as a Homebridge plugin if you already use Homebridge.

Matterhub specifically wins when: HomeKit Controller integration doesn’t work for your accessory, you want consistent Matter handling in HA, or you’re consolidating multiple HomeKit accessories behind a single Matter bridge.

Prerequisites

Before installing Matterhub, you need:

• Home Assistant running a recent version with the Matter integration set up
• A Thread Border Router on the network (Connect ZBT-1, HA Yellow, HomePod Mini, Nest Hub, etc.)
• Docker available on your server, OR HACS installed for the HA add-on path
• The HomeKit pairing codes for the accessories you want to bridge
• The HomeKit accessory NOT currently paired to Apple Home (or unpaired first, since HomeKit only allows one controller)

Step-by-Step: Installing Matterhub

Option 1: Docker Compose

The most flexible install. Create a directory and a docker-compose.yml:

version: '3.8'
services:
  matterhub:
    image: ghcr.io/t0bst4r/matter-hub:latest
    container_name: matterhub
    restart: unless-stopped
    network_mode: host
    volumes:
      - ./data:/data
    environment:
      - MH_LOG_LEVEL=info

Run:

docker compose up -d

Matterhub will start on the default port (typically 8482 for its web UI). Open http://your-server:8482 to access the management interface.

Option 2: Home Assistant Add-on (if available)

If you’re running Home Assistant OS, check HACS or the community add-on repository for a Matterhub add-on. Add the repository URL in Settings > Add-ons > Add-on Store > Repositories, then install from there.

Pairing HomeKit Accessories to Matterhub

Once Matterhub is running:

1. Open the Matterhub web UI
2. Click “Add HomeKit accessory”
3. If the accessory was previously paired to Apple Home, unpair it from the Home app first
4. Put the accessory into HomeKit pairing mode (usually by following its manufacturer instructions)
5. Enter the HomeKit setup code (8-digit number on the accessory or its manual)
6. Wait for Matterhub to discover and pair the accessory
7. The accessory now appears in Matterhub as a bridged device

Commissioning Matterhub in Home Assistant

With HomeKit accessories paired to Matterhub, the next step is exposing them to Home Assistant via Matter:

1. In Matterhub’s web UI, open the “Matter Commissioning” section
2. Click “Open Commissioning Window” – this generates a Matter pairing code
3. In Home Assistant: Settings > Devices & Services > Add Integration > Matter
4. Choose “Add Matter device”
5. Enter the pairing code from Matterhub
6. Home Assistant commissions the bridge and discovers all bridged HomeKit accessories
7. Each accessory appears as a separate entity in HA

Using Matterhub Accessories in Home Assistant

Once commissioned, bridged accessories behave like any other Matter device in HA. A HomeKit smart lock becomes a lock entity. A HomeKit sensor becomes binary_sensor or sensor. You can use them in automations, dashboards, and scripts.

Example: trigger HA notification when a HomeKit-only smart lock is unlocked:

automation:
  - alias: "Notify on front door unlock"
    trigger:
      - platform: state
        entity_id: lock.front_door_matterhub
        to: "unlocked"
    action:
      - service: notify.mobile_app_my_phone
        data:
          message: "Front door unlocked"

Common Issues and Fixes

• “Accessory already paired” error: HomeKit accessories allow only one controller. Factory reset the accessory or unpair from Apple Home first.
• Matterhub commissioning fails in HA: confirm Thread Border Router is active. Matterhub commissioning uses the same Thread infrastructure as regular Matter devices.
• Bridged devices show as unavailable: Matterhub container restarted? Check Docker logs. Some accessories need re-pairing after Matterhub restarts.
• Matterhub UI not accessible: confirm network_mode: host is set in Docker Compose, since Matter requires direct network access for mDNS discovery.

When NOT to Use Matterhub

Matterhub adds complexity. Skip it if:

• Your devices are already native Matter – use HA’s built-in Matter integration directly
• Your HomeKit accessory works with HA’s HomeKit Controller integration – that’s simpler and doesn’t need a separate bridge
• You’re not running anything HomeKit-only – then there’s nothing to bridge

Conclusion

Matterhub is a niche but powerful tool for bridging the gap between Apple’s HomeKit ecosystem and the open Matter standard, with Home Assistant as the controller. For most users running standard Matter devices, the built-in HA Matter integration is enough. But if you’ve got HomeKit-only accessories you want fully integrated into HA with local control, Matterhub turns “impossible” into “30 minutes of Docker setup”. As more Matter-native devices ship, Matterhub becomes less necessary – but for now, it’s the cleanest solution to a specific problem.