Matter · Home Assistant · Docker

Matter Server en Home Assistant con Docker: guía local sin nube

Si quieres Matter Server en Home Assistant sin pasar por el add-on oficial, el camino es el repositorio python-matter-server: clonas, construyes y conectas por WebSocket. No es soportado por Home Assistant, y aquí está qué significa eso en la práctica.

Servidor Matter en una Raspberry Pi con cable de red y una pantalla mostrando logs del servidor, sobre un banco de trabajo
El Matter Server corriendo fuera del add-on oficial, listo para hablar con Home Assistant por WebSocket.

Matter local, sin nube: qué estás montando

Matter es un protocolo de aplicación que corre sobre IP, no un protocolo de radio. Un enchufe Matter over Wi-Fi habla IPv6 por tu LAN; un sensor Matter over Thread habla a través de un border router. Ninguno necesita que la nube del fabricante valide cada orden, y Home Assistant puede mandárselas directamente. Por eso Matter encaja en una casa sin nube: el control es local por diseño.

El servidor Matter es la pieza que traduce: por un lado habla el protocolo Matter con los dispositivos, por el otro expone una API por WebSocket que entiende Home Assistant. En una instalación Home Assistant OS funciona como add-on y está soportado. En Docker, tú montas el servidor aparte y la integración de Home Assistant se conecta a él. Eso es exactamente lo que hacemos aquí, con sus consecuencias.

Comparativa: add-on soportado frente al Matter Server en Docker
Aspecto Add-on oficial (HAOS) Docker (este montaje)
Soporte Soportado por Home Assistant No soportado; el Docker oficial es "as-is"
Supervisor Integrado No lo necesitas, pero tampoco lo tienes
Comunicación HA↔server Automática WebSocket por IPv4 o IPv6
Sistema recomendado Home Assistant OS Linux con IPv6 habilitado; evita NAS
Copiar y pegar Poca configuración Más pasos, más control

Lo que necesitas antes de empezar

  • Linux con Docker, no un NAS. El propio docs/docker.md del repositorio advierte que no intentes correrlo sobre un sistema operativo de propósito específico tipo NAS. Las necesidades de red de Matter y Thread no encajan ahí.
  • IPv6 funcional. Matter se apoya en IPv6. Si tu red local no lo tiene activo, el servidor no verá los dispositivos Thread y puede dar problemas con dispositivos Wi-Fi.
  • El WebSocket accesible desde Home Assistant. El servidor y Home Assistant se entienden por WebSocket (ws), que funciona sobre IPv4 o IPv6.
  • Paciencia con la falta de soporte. Nada de esto lo mantiene Home Assistant; si un release lo rompe, lo arreglas tú o vuelves al add-on.
Vista detallada de una placa de circuito Raspberry Pi con microchips y componentes
Foto de Alessandro Oliverio en Pexels

Paso 1: clonar y construir el servidor Matter

El repositorio es matter-js/python-matter-server. La versión 8.1.2 fue la última de la línea Python antes de reescribirse como matterjs-server, así que mira siempre el README del release que vayas a usar. El flujo que se repite en la documentación y en el hilo de Reddit es:

git clone https://github.com/matter-js/python-matter-server.git
cd python-matter-server
docker build -t matter-server .

No copies el docker run de este artículo a ciegas: el comando exacto cambia entre releases. En el docs/docker.md del repositorio está el ejemplo canónico con los parámetros de red y volúmenes. Úsalo como fuente de verdad.

Paso 2: arrancar el contenedor con la red correcta

Matter necesita que el contenedor vea la red local, sobre todo IPv6 y los border routers Thread. La documentación del repositorio resuelve esto, normalmente con red host o con una red Docker configurada para IPv6. Lo importante no es el flag concreto, sino que verifiques desde el contenedor que ves la red local.

Después de arrancarlo, comprueba que responde por WebSocket. La URL tendrá la forma ws://IP_DEL_SERVIDOR:PUERTO. El puerto por defecto está en el docs/docker.md; si no llega, revisa que no lo esté bloqueando el firewall.

Paso 3: conectar la integración Matter de Home Assistant

En Home Assistant ve a Ajustes → Dispositivos y servicios → Añadir integración → Matter. La integración te preguntará por la URL del WebSocket; ahí pegas la de tu contenedor. Si todo está bien, Home Assistant empezará a ver los dispositivos que entren en la red Matter.

No es el add-on, así que todo lo que pase por aquí (actualizaciones de firmware del servidor, caídas, incompatibilidades) lo llevas tú. A cambio, no dependes del supervisor para mover el servidor a otra máquina o versionarlo tú mismo.

Comprobaciones antes de buscar un dispositivo Matter
Comprobación Qué ver
WebSocket levantado La integración conecta sin error de URL
IPv6 activo en el host ip -6 addr muestra una dirección global o link-local
Border router Thread El contenedor puede alcanzarlo por la red local
Sin doble NAT raro Los dispositivos Matter over Wi-Fi obtienen IPv6

Añadir tu primer dispositivo Matter

Con el servidor conectado, el alta de dispositivos se hace desde la propia integración Matter de Home Assistant, escaneando el código QR o el código numérico del dispositivo. El paso a paso visual lo enseña este vídeo en español, y la documentación oficial mantiene los requisitos al día:

Vídeo: Aprende a agregar dispositivos Matter a tu Home Assistant fácilmente, de Home Assistant fácil - Juan isytec en YouTube

Los tres tropiezos que te vas a encontrar

  1. "No puedo usar la imagen de Docker de Home Assistant". Es lo primero que salta en Reddit: la imagen oficial de Home Assistant Docker no sirve para esto porque exige supervisor. No es un bug; es diseño. Por eso clonas el repositorio aparte.
  2. El servidor no ve los dispositivos Thread. Casi siempre es IPv6 o el border router. Revisa la red antes de tocar la integración.
  3. Lo intentaste en un NAS y no arranca. El propio repo lo desaconseja. Si estás en un NAS con Docker, valora una Raspberry Pi o un mini PC Linux.

Este montaje funciona y deja todo el control en tu red, pero no es soportado. Si prefieres la tranquilidad del camino oficial, usa el add-on en Home Assistant OS. Si quieres documentar y versionar el servidor a tu manera, Docker es el camino.