Reachability and admin security are two separate problems

A Matter controller has to discover your bridge over mDNS and then open an operational session over IPv6 or a similar path. The admin browser you use to configure HAMH works through a completely different set of doors: its HTTP, REST and WebSocket interfaces. Putting the HTTP side behind a reverse proxy does not forward Matter's multicast traffic for you, and getting an mDNS reflector working does not add authentication to the admin interface. Draw “controller to bridge” and “admin to the Web UI and API” as two separate diagrams, because fixing one does not touch the other.

In the pinned Stable 2.0.55 release, the Home Assistant add-on mirror sets host_network: true, turns on Ingress, mounts addon_config for persistence, and exposes the app log level, disable-log-colors, mDNS interface and strip-global-IPv6 options in its own Configuration tab. Those are fixed facts about the add-on specifically. A plain Docker or npm install is driven by command-line start options instead, so do not assume the two ways of installing HAMH expose exactly the same fields in exactly the same place.

flowchart LR
  C["Matter controller
(phone, hub, or app)"] -->|"mDNS discovery,
then an operational session
over IPv6"| H["HAMH bridge process"]
  A["Admin browser"] -->|"HTTP, REST,
and WebSocket"| H
  H --> HA["Home Assistant
HTTP / WebSocket"]

Why crossing a VLAN takes more than opening a port

An IPv6 link-local address only works inside the same Layer 2 segment. It is not a routing plan for crossing VLANs — going across subnets needs a routable Unique Local Address (ULA), plus the right firewall and route entries on both sides. mDNS works the same way for a different reason: it announces and queries services over multicast, and most routers will not forward multicast across VLANs on their own. You need an explicit mDNS reflector or gateway policy, and the operational traffic between the controller and the bridge still has to be allowed in both directions once discovery succeeds.

On a host with several network cards, letting mDNS advertise on every interface invites the controller to pick the Docker bridge, a virtual interface, the Thread interface, or a global IPv6 address with no return path — and then discovery either fails outright or looks like it worked and then goes nowhere. Three options address this directly, and their names are exact:

An OpenThread Border Router (OTBR) can share a host with HAMH, but the Thread interface is not an ordinary LAN. Beyond not binding mDNS to it, check whether the IPv6 routes OTBR adds pull the cross-VLAN ULA return path into the Thread mesh by mistake. If a request arrives but the reply cannot get back, commissioning may show up as peer unresponsive; the fix is for the network admin to add a more specific LAN ULA route, not to turn IPv6 off.

flowchart TD
  A["Matter traffic needs
to cross a VLAN boundary"] --> B{"Is there a routable ULA,
not just an IPv6 link-local address?"}
  B -->|"link-local only"| C["Stop here.
Link-local only works inside
one Layer 2 segment"]
  B -->|"a routable ULA exists"| D{"Is mDNS forwarded
across that boundary?"}
  D -->|"no reflector or gateway"| E["Discovery fails, even though
the ULA route is fine"]
  D -->|"a reflector is in place"| F{"Is the operational port open
in both directions?"}
  F -->|"no"| G["Discovery may succeed,
then commissioning shows
No Response"]
  F -->|"yes"| I["Cross-VLAN commissioning
can work"]

Seven steps, in the order that keeps you from debugging two things at once

1. Step 1

   Draw the two data paths

   List the segments and boundaries for HAMH to HA, the controller hub to HAMH, and the admin browser to HAMH. Mark <LAN_INTERFACE>, the VLANs, the proxy and OTBR on the diagram — but keep real addresses, hostnames and identifying data out of anything you share.

2. Step 2

   Verify IPv6 and mDNS first

   In Health → Network Diagnostics, read off the available LAN interfaces, the IPv6 types, and the interface currently bound — without changing anything yet. Crossing VLANs needs a routable ULA, mDNS forwarding, and firewall rules in both directions; while all you have is link-local, do not cross VLANs yet.

3. Step 3

   Limit mDNS to the right interface

   On the add-on, set mdns_network_interface in Configuration to the LAN interface you just confirmed on that read-only screen; on a plain deployment, use the matching mdns-network-interface start option. Only turn on strip-global-IPv6 when the global IPv6 return path is unreliable, and only disable IPv4 once you are sure the IPv4 advertisement is unreachable and every controller you have supports IPv6.

4. Step 4

   Build the smallest firewall rule set

   Allow mDNS between the subnets that need it, plus the operational port each HAMH bridge is actually configured with, in both directions. Let admin HTTP in only from the management VLAN or the proxy. Do not assume a fixed list of bridge ports from a document — go by what the Bridges page actually says right now. If you run a bridge dedicated to the Camera Plugin, assess TCP on that same operational port as well.

5. Step 5

   Protect the Web UI, the API and the WebSocket

   Prefer add-on Ingress or a trusted reverse proxy over exposing HAMH directly. In v2.0.55 the WebSocket path does apply the base path, but the upgrade attaches straight to the raw HTTP server and bypasses HAMH's Basic Auth and IP allowlist entirely — the proxy itself has to authenticate and restrict the upgrade, and the backend must never sit reachable from an untrusted network. On a plain deployment, the path rewrite, the frontend assets, REST and the WebSocket all still have to agree on the same prefix.

6. Step 6

   Then add Basic Auth and the allowlist

   Supply the credentials through a secret manager or a restricted environment configuration — never in a compose example or your command history. List only the admin sources you actually need in the allowlist. Keep the monitoring requirement in mind: the code lets the health live and ready probes skip Basic Auth, which is exactly why you still need to restrict who on the network can reach them.

7. Step 7

   Verify one change at a time, and roll back if needed

   Change one thing at a time. After each restart, check Network Diagnostics, Health ready, the WebSocket live status, the bridge session, and one low-risk endpoint. If something fails, roll back to the last known-good configuration — do not change mDNS, VLANs, the proxy and authentication all in the same pass.

The admin interface, hardened in the right order

You can verify every option below in v2.0.55's start-options-builder.ts. The release channel is Stable, and the maturity of the command-line and environment configuration is Stable — but neither of those facts says anything about whether a particular controller supports IPv4, IPv6, or crossing VLANs. Server Mode, Camera and Security all appear in Stable too, and their product maturity is still experimental (experimental-in-Stable); do not confuse channel maturity with feature maturity, a distinction the plugins section below leans on again.

The pinned add-on mirror only exposes the options its own schema lists — do not write every plain start option up as an add-on UI field that may not exist. The other way round, the Ingress URL is managed by the Supervisor, so never hard-code an ingress token or a base path anywhere. In documents and support tickets, use explicit placeholders only, such as <INGRESS_PATH>, <LAN_INTERFACE> and <TRUSTED_PROXY> — never a real value, and never anything shaped like one.

Ingress, the base path, and the WebSocket exception

When a non-root base path is configured, WebApi redirects the root path to that prefix and mounts the API and the Web UI on the same app router. It also supports Home Assistant Ingress and proxy location headers. Because prefix headers change how URLs get rebuilt, a trusted proxy should strip any incoming header of the same name and then write a fixed value of its own — and the HAMH backend is best off never listening directly on an untrusted subnet in the first place.

The reverse proxy has to proxy both ordinary HTTP and the WebSocket upgrade. In v2.0.55 the upgrade does not inherit HAMH's Basic Auth or its IP allowlist at all — it is attached directly to the raw HTTP server, so a trusted proxy or network boundary has to authenticate and restrict the upgrade itself, and block direct connections to the backend from anywhere else.

flowchart TD
  R["A request arrives at
HAMH's web server"] --> Q{"Is it an ordinary HTTP
or REST request?"}
  Q -->|"yes"| P["Passes through Basic Auth
and the IP allowlist"]
  Q -->|"no, a WebSocket upgrade"| U["Attaches directly to
the raw HTTP server"]
  P --> X["Reaches the application"]
  U --> Y["Reaches the same application.
Neither check ran"]

If the page loads but the state never updates, and Live Event shows Offline, the usual cause is the WebSocket not being forwarded or the base path not matching on both ends — not a broken Matter session. Check the proxy configuration before you touch anything related to fabrics or bridges.

Basic Auth and the IP allowlist

Basic Auth can come from an environment option or from the stored settings in Settings; when the environment setting exists, the code treats the environment as the source of truth. Its semantics are one username and password pair — not tiered permissions for several users. Without TLS, Basic Auth does not give you enough transport confidentiality on its own; behind a proxy you also have to handle the source IP correctly, or the allowlist may only ever see the proxy's own address, or be swayed by a spoofed header.

Lock Credentials

Lock Credentials is a page in Stable 2.0.55 used to link a specific Home Assistant lock entity to a Matter PIN credential. When requirePinForRemoteOperation is on, a remote unlock or unbolt has to verify the PIN, while locking is still allowed without one. List responses come back redacted and the UI never echoes the secret; what is persisted is a PBKDF2 hash and a salt, not retrievable plaintext — but a short PIN still has low entropy, so you have to guard against offline guessing regardless. You can add, update, enable or disable, and delete entries. This is not a Matter commissioning credential, and it is not an ordinary website login password.

HA tokens and secret handling

The HA access token, the Basic Auth password, plugin secrets, Lock Credentials, and a full Matter identity backup all need a secret manager, a restricted environment, or a root-only config — with the HA permissions on that token and the list of people who can read the backups kept as small as possible. Protocol debug output, HTTP access logs and diagnostic exports need a short retention period and a manual check before you share them with anyone. Keep full backups encrypted and offline, and if you suspect a leak after a restore, run the matching credential rotation rather than only deleting a file.

In-process code, not a sandboxed extension

A plugin can register Matter devices, update cluster state, receive controller attribute writes, call external services, and use persistent storage. In v2.0.55 a plugin runs directly inside the HAMH backend process, with no OS-level sandbox around it. The error wrapper, the timeouts and the circuit breaker reduce how far a failure can spread, but none of them can make a malicious package safe. Installing a third-party plugin is the same act as authorizing it to run code with the permissions of the HAMH process itself.

Plugins are supported on standard bridges only. A bridge with Server Mode enabled builds no plugin manager and carries nothing at all, not even the built-in plugins; if every bridge you have is in Server Mode, the Plugins page shows the matching empty state. This has nothing to do with the release channel — Server Mode itself is still experimental (experimental-in-Stable), independent of the plugin question.

Lifecycle: what a plugin can hook into

The context object handed to a plugin gives it: register and unregister device, update state, domain mapping, plugin-scoped storage, a logger, the bridge ID, and an optional HA connection.

Enable / Disable versus Install / Uninstall

Enable and Disable are per-bridge, per-plugin state. Disable unmounts that plugin's mounted devices and persists the choice; Enable starts the plugin again. Settings can be saved while a plugin is disabled, and they take effect once you enable it later. Install and Uninstall work at the package level and usually need a bridge restart before they apply — do not confuse “the package is installed” with “the plugin is enabled on this bridge.”

The circuit breaker: SafePluginRunner

SafePluginRunner applies a default timeout to ordinary lifecycle calls, and when consecutive failures reach a threshold it opens the circuit breaker and disables the plugin automatically; a successful operation resets the failure count. The Reset button only clears the breaker so it can try again — it does not fix the root cause. Shutdown cleanup is still attempted even while the breaker is open, so resources are not leaked in the meantime.

stateDiagram-v2
  [*] --> Enabled
  Enabled --> BreakerOpen: consecutive failures reach the threshold
  BreakerOpen --> Disabled: the plugin is disabled automatically
  Disabled --> Enabled: Reset, then Enable, after you fix the cause

The v2.0.55 code and the pinned docs list the REST routes, the WebSocket messages and the response shapes — but nowhere in those sources does the project promise a public API versioning policy guaranteeing permanent compatibility. Unless another source guarantees it, do not describe this as a stable public contract. Any automation against it should pin a version, check status and schema, set timeouts, and run a smoke test before every upgrade.

A plugin manifest can declare hamhPluginApiVersion; the manager's own constant is currently version one, and a mismatch is recorded only as a warning. That warning is not a compatibility guarantee, and it does not upgrade a third-party package for you. A live matter.js EndpointType also has to come from the same matter.js instance running inside HAMH, so an external package is usually better off working with serializable device-type and cluster data instead.

1. Step 1

   Confirm the standard bridge and the isolation scope

   In Bridges, pick a standard bridge that does not have Server Mode enabled, and confirm first that it is running and that its fabric and health are normal. Give the experimental Camera and Security plugins — or any third-party plugin — a dedicated bridge; that narrows both the controller-compatibility surface and the blast radius of a failure.

2. Step 2

   Back up, then review the source

   Create a full identity backup and a record of the current plugin state. For npm, pin an explicit version and cross-check the package owner, the source repository, the manifest, the dependencies and the release integrity. A tgz has to be produced by a CI you trust and then verified; a symlink belongs only in an isolated development environment.

3. Step 3

   Install a package, or pick a built-in

   Do not type a built-in name into the npm field — the code rejects the reserved built-in names on purpose. Enable and configure a built-in straight from the Plugins page. For a third-party package, use the matching npm, Upload or Local tab, restart the target bridge when the prompt tells you to, then Refresh the list.

4. Step 4

   Configure the minimum the schema asks for

   Fill the required fields first, make sure every number parses, and leave any schema key you do not recognize at its existing setting. Fields marked secret are redacted by the backend and the stored value is never returned to you; leaving the redacted placeholder alone means keep the current value. Enter any token or password only through your own secret-management process — never into a document or a log.

5. Step 5

   Verify the endpoint and the controller

   Check the plugin's metadata, its enabled state, its devices and the breaker state, then open the bridge's endpoint tree and check the device types and clusters. Test state and a controller write with one low-risk device. Camera also needs you to assess the TCP firewall on its operational port; with Security you must not use a safety-critical entity for the first test.

6. Step 6

   Set up a fallback point for failure

   If errors start rising, Disable the plugin first so its mounted devices are removed cleanly, keeping the log and its settings intact. Only after you have fixed the external service or the schema should you Reset the breaker and Enable it again. If you are going to Uninstall, confirm first that no other bridge is still using it, keep the backup, then restart and verify the other plugins.

The interfaces you can verify today, not a promise for tomorrow

Camera Plugin

Camera exposes a chosen Home Assistant camera entity as a Matter camera device over a WebRTC transport flow. It registers no device until a camera entity is set; once one is set, it can be mounted dynamically. A custom HA URL and secret are optional, but the minimal configuration should just reuse the bridge's existing HA connection. A dedicated bridge isolates the effect of the Matter-over-TCP capability on your other controllers.

In Stable 2.0.55 it is still experimental — you cannot claim Apple Home support, and you cannot claim live view has been fully verified on any controller. A camera stream involves privacy, the network and the firewall all at once, and the Plugins page working is not the same thing as meeting the surveillance regulations or the access policy you are actually subject to.

Security Plugin

Security creates a Home / Away / Night / Vacation mode switch and an Alarm contact sensor, and runs on exit and entry delays, a trigger list, an alert list, setters, and a persisted armed state. It is not a synchronizing front end for an existing Alarmo or alarm integration — if both use the same set of sensors, you end up with two state machines that know nothing about each other.

This experimental plugin has no separate verification-code flow of its own; a controller that can operate the mode switch can also disarm it. Expose it only to controllers you trust, and do not treat it as a certified intruder alarm. Trigger events during a Home Assistant outage can also be lost, which is another reason it is not a safety system.

Schema secrets and the breaker

The v2.0.55 backend schema property has an explicit secret flag: a stored secret is replaced by a sentinel value in the listing, and if the value is still that sentinel when you save, the original value is kept untouched. The frontend also falls back to redacting by field name for older schemas, but the real protection has to come from the backend's own secret flag. If a third-party plugin does not mark its secrets correctly, the platform has no way of knowing on its own that a given string is sensitive.

REST surface

/api/plugins gives you the plugin metadata, the redacted config, the breaker state and the devices for each standard bridge; alongside it sit the installed list, npm install, binary tgz upload, local install, uninstall, enable / disable / reset, config schema and config update. The whole of /api also mounts matter, health, bridges export, images, mappings, settings, backup, HA, logs, system, diagnostic, metrics and network. This is a management plane, so it needs the same access controls covered earlier in this part — but the WebSocket carries the same auth-bypass boundary at this version, so do not assume REST protection extends to the upgrade.

WebSocket, logs, metrics, live and ready

The WebSocket path is mounted at /api/ws under the base path. It sends the initial bridge state on connect and can then broadcast bridge updates; a client can ping and pong, and subscribe to or unsubscribe from diagnostics, receiving a snapshot followed by the diagnostic events that come after it. As covered above, in v2.0.55 this upgrade is attached directly to the raw HTTP server, which bypasses HAMH's Basic Auth and IP allowlist entirely — a trusted proxy or network boundary has to authenticate, restrict the upgrade, and block direct backend reachability on its own. The client side also has to handle unknown message types and reconnect on its own.

The logs API supports level, search, category, facility and limit / offset, plus a level count, a clear action, and a Server-Sent Events stream; a low-memory system uses a smaller buffer. Metrics come in JSON and Prometheus form. Health live answers only whether the process is alive, and ready looks only at whether HA is connected. These endpoints cover different scopes, so a single 200 response from one of them is not a claim that the whole Matter topology is healthy.

The symptom you see, and the safe fix — not just a restart

Network and admin access

Plugins and the API

The ones that come up again and again

Where to go from here