Cómo instalar Matterbridge en Docker: Convierte tus dispositivos en Matter con un solo emparejamiento

Matterbridge | Matter | Docker

Matterbridge: Convierte tus dispositivos en Matter con un solo emparejamiento

Gestor de plugins Matter que permite exponer todos tus dispositivos inteligentes a Apple Home, Google Home, Alexa y cualquier ecosistema compatible con Matter.

¿Qué es Matterbridge?

Matterbridge es un gestor de plugins para Matter que te permite tener todos tus dispositivos inteligentes funcionando en Matter en cuestión de minutos, sin tener que emparejar cada dispositivo individualmente.

Simplemente empareja Matterbridge una vez con tu ecosistema favorito (Apple Home, Google Home, Alexa, Home Assistant, etc.) y todos los plugins registrados cargarán sus dispositivos automáticamente. Los desarrolladores pueden enfocarse únicamente en el desarrollo de dispositivos extendiendo las clases proporcionadas.

Filosofía del proyecto: Matterbridge crea un dispositivo Matter que puede emparejarse con cualquier ecosistema. No necesitas un hub dedicado ni una máquina nueva. Es ligero y funciona incluso en máquinas Linux con solo 512MB de RAM.

Características principales

Emparejamiento único

Empareja Matterbridge una vez y todos tus plugins cargan automáticamente sus dispositivos.

Frontend web completo

Interfaz web para gestionar plugins, dispositivos, configuración y logs desde el navegador.

Modo bridge y childbridge

Bridge expone Matterbridge como un solo dispositivo. Childbridge expone cada plugin individualmente.

Plugins oficiales y terceros

Shelly, Zigbee2MQTT, Home Assistant, Somfy Tahoma, webhooks, BTHome y más.

Sin dependencias complejas

No necesitas hub adicional, hardware dedicado ni configuraciones complicadas.

Ligero y eficiente

Funciona en máquinas con 512MB RAM, Raspberry Pi, NAS y cualquier sistema Linux/macOS/Windows.

Soporte IPv6

Matter está diseñado sobre IPv6. Matterbridge funciona nativamente con IPv6 en tu red local.

Multi-controlador

Empareja múltiples controladores simultáneamente (Apple Home + Google + Alexa).

Gestión de plugins desde UI

Instala, actualiza, habilita, deshabilita y configura plugins desde la interfaz web.

Basado en matter.js

Construido sobre la implementación oficial de Matter por project-chip.

Plugins oficiales disponibles

Shelly

Gen 1, 2, 3, 4 y BLU. Descubrimiento automático con mDNS.

Zigbee2MQTT

Todos los dispositivos y grupos Zigbee2MQTT expuestos a Matter.

Home Assistant

Expone entidades y dispositivos de Home Assistant a Matter.

Somfy Tahoma

Dispositivos de pantallas Somfy Tahoma.

Webhooks

Expone cualquier webhook a Matter.

BTHome

Dispositivos BTHome usando Bluetooth nativo del host.

Plugins de terceros: Loxone, Dyson Robot, AEG Robot, Airthings, Daikin AC, Roborock, Wyze Robot Vacuum, Litetouch 2000 y más en desarrollo.

Requisitos previos

• Docker y Docker Compose instalados
• IPv6 habilitado en tu red local (Matter requiere IPv6)
• Un controlador Matter: Apple Home, Google Home, Alexa, Home Assistant, etc.
• Evitar VLANs, VMs o firewalls que bloqueen comunicación entre controladores y Matterbridge
• Al menos 512 MB de RAM disponible

Importante sobre IPv6: Solo necesitas IPv6 en tu red local (LAN), no importa si tu ISP no proporciona IPv6 en Internet (WAN). La mayoría de routers modernos tienen IPv6 habilitado por defecto en la red local.

Instalación con Docker Compose

Paso 1: Crear el directorio del proyecto

mkdir ~/matterbridge cd ~/matterbridge

Paso 2: Crear docker-compose.yml

services: matterbridge: container_name: matterbridge image: luligu/matterbridge:latest restart: unless-stopped network_mode: host volumes: - ~/.matterbridge:/root/.matterbridge - ~/Matterbridge:/root/Matterbridge - ~/.mattercert:/root/.mattercert

network_mode: host es necesario para el descubrimiento mDNS correcto. Esto significa que los puertos se comparten directamente con el host.

Paso 3: Iniciar el contenedor

docker compose up -d

Paso 4: Ver logs y obtener la URL del frontend

docker compose logs -f matterbridge

Busca en los logs una línea similar a:

Matterbridge is running on http://192.168.1.100:8283

Paso 5: Acceder al frontend

Abre tu navegador y ve a la URL proporcionada en los logs (ej: http://192.168.1.100:8283)

Configuración inicial

Elegir modo de operación

Desde el frontend puedes elegir entre dos modos:

Modo Bridge

• Matterbridge se expone como un solo dispositivo
• Todos los plugins y sus dispositivos aparecen dentro de ese bridge
• Solo necesitas emparejar Matterbridge una vez
• Límite de 150 accesorios en Apple Home por bridge

Modo Childbridge

• Cada plugin se expone como un dispositivo individual
• Debes emparejar cada plugin por separado
• Mayor flexibilidad y aislamiento entre plugins
• Recomendado si tienes muchos dispositivos

# Forzar modo bridge desde línea de comandos docker exec matterbridge matterbridge --bridge # Forzar modo childbridge desde línea de comandos docker exec matterbridge matterbridge --childbridge

Instalar plugins

Desde el frontend (Recomendado)

1. Abre el frontend en tu navegador
2. Ve a la sección de plugins
3. Busca el plugin que deseas (ej: matterbridge-zigbee2mqtt)
4. Haz clic en Install
5. Espera a que se complete la instalación
6. El plugin aparecerá en la lista de plugins registrados

Desde línea de comandos

# Instalar plugin docker exec matterbridge npm install -g matterbridge-zigbee2mqtt --omit=dev # Añadir plugin a Matterbridge docker exec matterbridge matterbridge --add matterbridge-zigbee2mqtt # Ver plugins registrados docker exec matterbridge matterbridge --list

Gestionar plugins desde CLI

# Eliminar plugin docker exec matterbridge matterbridge --remove matterbridge-zigbee2mqtt # Deshabilitar plugin (no se carga al inicio) docker exec matterbridge matterbridge --disable matterbridge-zigbee2mqtt # Habilitar plugin docker exec matterbridge matterbridge --enable matterbridge-zigbee2mqtt

Emparejar con tu ecosistema

Apple Home

1. Abre la app Home en tu iPhone/iPad
2. Pulsa el botón + (Añadir accesorio)
3. Escanea el código QR mostrado en el frontend de Matterbridge
4. Sigue las instrucciones en pantalla
5. Todos los dispositivos del bridge aparecerán automáticamente

Google Home

1. Abre la app Google Home
2. Toca el botón + (Añadir dispositivo)
3. Selecciona "Dispositivo nuevo" → "Matter"
4. Escanea el código QR de Matterbridge
5. Completa el proceso de emparejamiento

Amazon Alexa

1. Abre la app Alexa
2. Ve a Dispositivos → Añadir dispositivo
3. Selecciona "Matter"
4. Escanea el código QR
5. Completa el emparejamiento

Home Assistant

1. Ve a Configuración → Dispositivos y servicios
2. Haz clic en + Añadir integración
3. Busca "Matter"
4. Escanea o introduce el código de emparejamiento

Emparejar un segundo controlador

Puedes emparejar múltiples controladores simultáneamente:

Método 1: Desde el primer controlador

Busca la opción "Compartir" o "Activar modo de emparejamiento" en la configuración del dispositivo Matterbridge en tu primer controlador. Esto generará un nuevo código QR que puedes usar para emparejar el segundo controlador.

Método 2: Desde el frontend de Matterbridge

1. Abre el frontend de Matterbridge
2. Ve al panel Paired fabrics
3. Haz clic en Turn on pairing mode
4. Usa el código QR generado para emparejar el segundo controlador

Gestión del contenedor

Ver logs en tiempo real

docker compose logs -f matterbridge

Reiniciar Matterbridge

docker compose restart matterbridge

Detener Matterbridge

docker compose down

Actualizar a la última versión

docker compose pull docker compose up -d

Acceder al shell del contenedor

docker exec -it matterbridge /bin/sh

Reset y backup

Reset de emparejamiento (modo bridge)

Para volver a emparejar Matterbridge sin perder plugins:

docker compose down docker exec matterbridge matterbridge --reset docker compose up -d

Reset de un plugin (modo childbridge)

docker compose down docker exec matterbridge matterbridge --reset matterbridge-zigbee2mqtt docker compose up -d

Factory reset (elimina todo)

docker compose down docker exec matterbridge matterbridge --factoryreset docker compose up -d

Atención: El factory reset elimina toda la configuración, información de emparejamiento y desregistra todos los plugins.

Crear backup

Desde el frontend (menú de tres puntos):

1. Selecciona Create backup
2. Espera a que se complete
3. Selecciona Download backup

El backup es un archivo .zip que contiene los tres directorios de configuración.

Restaurar backup

Debe hacerse manualmente:

1. Detén Matterbridge: docker compose down
2. Extrae el contenido del backup ZIP
3. Reemplaza los directorios correspondientes en tu sistema
4. Asegura permisos correctos
5. Reinicia: docker compose up -d

Habilitar debug y logs

Desde el frontend

1. Ve a Settings
2. Habilita Debug mode para Matterbridge Logger
3. Habilita Debug mode para Matter Logger
4. Habilita Log on file en ambos
5. Reinicia Matterbridge

Descargar logs

Desde el menú de tres puntos en el frontend:

• Download matterbridge.log
• Download matter.log

Importante: Deshabilita el modo debug cuando no lo necesites. El tráfico de red y uso de CPU es muy alto en modo debug.

Habilitar HTTPS en el frontend

Proporcionar certificados propios

Coloca tus certificados en el directorio ~/.matterbridge/cert:

Certificados estándar

~/.matterbridge/cert/ ├── cert.pem ├── key.pem └── ca.pem (opcional)

Certificado PKCS#12

~/.matterbridge/cert/ ├── cert.p12 └── cert.pass

Modificar docker-compose.yml

services: matterbridge: command: ["matterbridge", "--ssl", "--frontend", "443"] # O con autenticación mutua (mTLS) # command: ["matterbridge", "--ssl", "--mtls", "--frontend", "443"]

Reiniciar

docker compose up -d

Ahora podrás acceder con https:// al frontend.

Casos de uso

• Migración desde Homebridge: Convierte tus dispositivos Homebridge a Matter sin recodificar
• Ecosistema unificado: Controla todos tus dispositivos desde cualquier controlador Matter
• Smart home multi-plataforma: Apple Home + Google + Alexa simultáneamente
• Home Assistant + Matter: Expone entidades de HA a controladores externos via Matter
• Dispositivos Zigbee a Matter: Convierte tu red Zigbee2MQTT a Matter sin hardware adicional
• Shelly a Matter: Todos tus Shellies en Matter con descubrimiento automático
• Desarrollo de plugins: Crea plugins Matter sin preocuparte por el emparejamiento

Issues conocidos por controlador

Apple Home

• HomePods con WiFi pueden tener errores de transmisión. Apple TV con cable es más fiable
• Los tipos de dispositivo Appliances no están soportados en versión 18.4.x
• Robot solo soportado como dispositivo individual o único en el bridge

Google Home

• En Android puede fallar el commissioning por bug de Android (no envía código de país)
• Workaround: Usa un iPhone para emparejar, luego funcionará en Android
• Issue conocido con conversión Fahrenheit/Celsius en termostatos

Alexa

• Máximo 50 dispositivos bridged por conexión
• La posición de covers/persianas se muestra invertida
• Switches solo se muestran si se exponen como light u outlet

SmartThings

Sin issues reportados hasta ahora.

Home Assistant

Único controlador con soporte completo de Matter 1.2, 1.3 y 1.4. Si no muestra todos los dispositivos, recarga la integración Matter Server o reinicia HA.

---

Referencias oficiales

• Repositorio oficial de Matterbridge - GitHub
• Matterbridge Official Website
• Imagen Docker - Docker Hub
• Documentación Docker - GitHub
• Discord Community
• matter.js - Proyecto base

Apoya el canal GENBYTE

Suscríbete al canal de YouTube Suscríbete a la newsletter semanal Invítame a un Ko-fi genbyte@proton.me

Sígueme en mis redes sociales

Telegram Discord YouTube GitHub Blog Twitter