feat(community): add Matter.js Server app#5046
Draft
yincrash wants to merge 2 commits into
Draft
Conversation
Matter.js Server is a Matter Controller WebSocket server built on the JavaScript Matter SDK. It is a drop-in replacement for the Python Matter Server, usable with Home Assistant and other Matter clients. Image: ghcr.io/matter-js/matterjs-server:0.7.1 Source: https://github.com/matter-js/matterjs-server The questions form exposes the upstream config (log level, primary interface, listen address, OTA provider directory, BLE proxy endpoint, BLE host adapter, DCL test-net, vendor/fabric ID overrides) plus the standard TrueNAS storage/networking/labels/resources sections. Notes on host networking + TrueNAS: - Matter.js needs UDP 5353 for mDNS device + Thread Border Router discovery, so host networking is the default. - TrueNAS's avahi-daemon ships with disallow-other-stacks=yes, which blocks Matter.js from binding 5353. The Host Network field help and Install Notes document the one-line avahi config change (does not disable avahi; just removes its exclusive lock so both can share via SO_REUSEPORT), plus an alternative macvlan recipe for users who'd rather not touch the host's avahi. - BLE_PROXY exposes /ble for a remote BLE proxy client (Home Assistant with ESPHome BT proxies aggregated is the recommended source). Host BLE (BLUETOOTH_ADAPTER) is exposed but de-emphasized in the form because TrueNAS SCALE does not ship Bluetooth drivers by default.
stavros-k
reviewed
May 29, 2026
Comment on lines
+25
to
+45
| ### Option A — Host networking + Avahi tweak (simplest) | ||
|
|
||
| With *Host Network* enabled (the default), Matter.js shares the host's | ||
| network namespace. TrueNAS's `avahi-daemon` already owns UDP `5353` with | ||
| `disallow-other-stacks=yes`, so on first start the app crashes with | ||
| `Cannot bind 0.0.0.0:5353 because port is already in use`. Fix once: | ||
|
|
||
| 1. SSH to the TrueNAS host and run: | ||
| ``` | ||
| sudo sed -i 's/disallow-other-stacks=yes/disallow-other-stacks=no/' /etc/avahi/avahi-daemon.conf | ||
| sudo systemctl restart avahi-daemon.service | ||
| ``` | ||
| 2. Persist across TrueNAS upgrades: *System Settings → Advanced → Init/Shutdown Scripts → Add*, | ||
| Type `Command`, When `Post Init`, Command: | ||
| ``` | ||
| sed -i "/disallow-other-stacks=yes/c\disallow-other-stacks=no" /etc/avahi/avahi-daemon.conf && systemctl restart avahi-daemon.service | ||
| ``` | ||
| 3. Restart this app. | ||
|
|
||
| Both daemons then coexist via `SO_REUSEADDR`. TrueNAS's own mDNS | ||
| announcements (SMB/Bonjour) keep working unchanged. |
Contributor
There was a problem hiding this comment.
That kind of changes cannot be on docs. The whole idea of doing funky things via CLI is something that we try to steer away.
I'm also considering not allowing host net for this app at all.
Author
There was a problem hiding this comment.
Is there a prescribed way to handle apps that require running mDNS? Asking users to disable it in Network -> Global Configuration?
Contributor
There was a problem hiding this comment.
Nope, its considered advanced and not recommended to disable mDNS.
So if thats whats required, I dont think this app belongs in the store.
stavros-k
reviewed
May 29, 2026
Comment on lines
+47
to
+98
| ### Option B — Macvlan network (no host changes) | ||
|
|
||
| Give the container its own LAN IP and its own port `5353`, fully separate | ||
| from TrueNAS's avahi. | ||
|
|
||
| 1. SSH and create the network (replace `eno1` with your NIC, plus your | ||
| subnet and gateway): | ||
| ``` | ||
| docker network create -d macvlan \ | ||
| -o parent=eno1 \ | ||
| --subnet=192.168.1.0/24 --gateway=192.168.1.1 \ | ||
| matter_lan | ||
| ``` | ||
| For Thread Matter devices (which require IPv6 end-to-end), add IPv6: | ||
| ``` | ||
| docker network create -d macvlan -o parent=eno1 \ | ||
| --subnet=192.168.1.0/24 --gateway=192.168.1.1 \ | ||
| --ipv6 --subnet=fd00:abcd::/64 --gateway=fd00:abcd::1 \ | ||
| matter_lan | ||
| ``` | ||
| 2. In the app form: turn **Host Network** off, then under *Networks* add | ||
| `matter_lan` with container `matterjs-server` and an IPv4 address | ||
| outside your DHCP range (e.g. `192.168.1.200`). | ||
| 3. Install/restart the app. Access the dashboard at the macvlan IP, e.g. | ||
| `http://192.168.1.200:5580/`. | ||
|
|
||
| Caveats: | ||
| - The TrueNAS host cannot reach the macvlan container by default. If you | ||
| run Home Assistant as a separate TrueNAS app on the same box, it won't | ||
| see this server without a shim macvlan interface on the host. | ||
| - Pick a static IP outside the DHCP range; compose macvlan doesn't do DHCP. | ||
| - IPv4-only macvlan works for Wi-Fi Matter commissioning, but Thread | ||
| device communication will be unreliable without the IPv6 subnet. | ||
|
|
||
| ## BLE commissioning on TrueNAS | ||
|
|
||
| TrueNAS SCALE does not ship Bluetooth drivers, so the `BLUETOOTH_ADAPTER` | ||
| option (host HCI) generally will not work even if you have a USB BT dongle | ||
| plugged in. | ||
|
|
||
| **Recommended setup:** enable **BLE Proxy Endpoint** in the app settings, | ||
| then run Home Assistant somewhere on your network (this can be the TrueNAS | ||
| Home Assistant app, a separate box, or HA OS). Add one or more ESP32-based | ||
| [ESPHome Bluetooth Proxy](https://esphome.io/components/bluetooth_proxy/) | ||
| devices. Once HA's Matter integration is pointed at this server, it | ||
| automatically forwards BLE traffic from the ESPHome proxies to the | ||
| `/ble` endpoint here — no extra config needed on this app. | ||
|
|
||
| If you do have a working host BT adapter and want to use it directly, set | ||
| `BLUETOOTH_ADAPTER` and change User/Group to `0` (root). This effectively | ||
| disables container isolation, so prefer the ESPHome proxy path when | ||
| possible. |
Contributor
There was a problem hiding this comment.
You can submit this in https://github.com/truenas/apps-web/
These notes are for very short things. not an entire guide
stavros-k
reviewed
May 29, 2026
Comment on lines
+23
to
+35
| maintainers: | ||
| - email: mikeyin@mikeyin.org | ||
| name: Mike Yin | ||
| url: https://mikeyin.org | ||
| name: matterjs-server | ||
| run_as_context: | ||
| - description: Container [matterjs-server] runs as any non-root user and group by | ||
| default. Run as root (0:0) is required only for BLE commissioning via a host Bluetooth | ||
| adapter. | ||
| gid: 568 | ||
| group_name: Host group is [apps] | ||
| uid: 568 | ||
| user_name: Host user is [apps] |
Contributor
There was a problem hiding this comment.
you need to run the metadata script.
stavros-k
reviewed
May 29, 2026
Contributor
There was a problem hiding this comment.
this file should not be commited
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
App Addition
AI
Description
Adds matterjs-server to the community train.
Matter.js Server is a Matter Controller WebSocket server built on the JavaScript Matter SDK. It is a drop-in replacement for the Python Matter Server, usable with Home Assistant and other Matter clients.
Image: ghcr.io/matter-js/matterjs-server:0.7.1
Source: https://github.com/matter-js/matterjs-server
The questions form exposes the upstream config (log level, primary interface, listen address, OTA provider directory, BLE proxy endpoint, BLE host adapter, DCL test-net, vendor/fabric ID overrides) plus the standard TrueNAS storage/networking/labels/resources sections.
This closes #240
App Information
Testing
Tested locally with:
All tests passed successfully.
Icons and Screenshots
Please upload the following to the CDN:
Special Notes
Notes on host networking + TrueNAS:
Matter.js needs UDP 5353 for mDNS device + Thread Border Router discovery, so host networking is the default.
TrueNAS's avahi-daemon ships with disallow-other-stacks=yes, which blocks Matter.js from binding 5353. The Host Network field help and Install Notes document the one-line avahi config change (does not disable avahi; just removes its exclusive lock so both can share via SO_REUSEPORT), plus an alternative macvlan recipe for users who'd rather not touch the host's avahi.
BLE_PROXY exposes /ble for a remote BLE proxy client (Home Assistant with ESPHome BT proxies aggregated is the recommended source). Host BLE (BLUETOOTH_ADAPTER) is exposed but de-emphasized in the form because TrueNAS SCALE does not ship Bluetooth drivers by default.
Any other important information
Checklist