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.
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.
| 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.mddel 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.
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.
| 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:
Los tres tropiezos que te vas a encontrar
- "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.
- El servidor no ve los dispositivos Thread. Casi siempre es IPv6 o el border router. Revisa la red antes de tocar la integración.
- 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.