Installing Stable 2.0.55

Choose an install method; do not assume everyone should deploy by hand

The upstream installation docs list the Home Assistant OS add-on as the preferred method. If you already run Home Assistant OS, start with the add-on: Supervisor handles starting, stopping and Ingress, and the add-on gets the connection details it needs through the Home Assistant API. Docker and global npm are for readers who can maintain a container or a Node.js service, a data directory, the network and a way to inject secrets on their own; they are not an inevitable upgrade to "more complete features".

Shared prerequisites: HA, IPv6, mDNS and the data directory

All three methods need a working Home Assistant, a correct clock, storage that persists, and a LAN the controller can reach. Matter depends on IPv6, mDNS and UDP; if you have VLANs, multicast and the return route both have to be handled correctly. A Web UI that loads is not the same as a network that works for commissioning.

• Home Assistant itself works, and you are allowed to create a long-lived access token dedicated to this service. Do not paste the token into a repository, a chat or a screenshot.
• The controller or home hub and the host running Matter Hub have a working IPv6 and mDNS path between them, and AP/client isolation is off.
• Docker uses host network; the pinned add-on config also sets host_network: true.
• Decide where data will persist and how you will back it up before you start. Docker always mounts the container's /data; npm defaults to an application folder under the user's home directory, or you name one with a start option.
• Do not expose the Web UI directly to an untrusted network. When you need a reverse proxy, Basic Auth or an IP allowlist, read Chapter 20 first; Basic Auth is not multi-account, RBAC or SSO.

Install the pinned Stable 2.0.55 add-on

The add-on facts in this guide are pinned to WOOWTECH mirror commit a68dc435da8eb206e9efd51388d5d1ce798aefe0. In it, hamh/config.yaml declares version 2.0.55, the slug hamh, a minimum Home Assistant of 2024.1.0, and support for aarch64 and amd64. It enables the Home Assistant API, host network and Ingress, the Ingress port is a dynamic value, and it mounts addon_config read-write.

1. Add the Stable repository

   In Home Assistant, open "Settings → Add-ons → Add-on Store", then use the repository menu in the top right to add the Stable add-on repository you have approved. Check that what shows up is Stable hamh, and do not pick the Alpha or Testing slug by mistake.

2. Cross-check the version and the architecture

   On the install card, first confirm the version is 2.0.55 and that the host architecture is one of the aarch64 or amd64 the pinned config lists. If it does not match, stop the install; do not substitute an unknown image.

3. Install it and review the configuration

   After you press "Install", go to the "Configuration" tab and leave the log level at info. Fill in mdns_network_interface only when Network Diagnostics points at an interface problem. Do not pick a Docker or Thread interface at random.

4. Start it and open it through Ingress

   Press "Start", check the add-on log to see whether the service finished initializing, then press "Open Web UI". A successful screen shows the Dashboard, with the HA connection Online.

5. Back up before you create a bridge

   Confirm that the Supervisor backup includes the add-on data before you go to the next chapter and create a bridge. Do not treat "the UI opens" as proof that the backup is done.

Docker: pin the image, use host network and /data

Docker suits readers who already operate containers. Stable 2.0.55 needs host network so that Matter and mDNS are not held back by an ordinary bridge network; data is written to the container's /data, so you must mount a persistent volume. For reproducibility this chapter uses an explicit version tag, not the moving latest.

docker run -d   --name home-assistant-matter-hub   --restart unless-stopped   --network host   -v <PERSISTENT_DATA_PATH>:/data   -e HAMH_HOME_ASSISTANT_URL="<HA_BASE_URL>"   -e HAMH_HOME_ASSISTANT_ACCESS_TOKEN="<HA_LONG_LIVED_ACCESS_TOKEN>"   -e HAMH_LOG_LEVEL="info"   ghcr.io/riddix/home-assistant-matter-hub:2.0.55

Do not write the real token into a Compose file you can commit; use a permission-protected env file, a container secret or your deployment platform's secret store instead. <HA_BASE_URL> has to be a Home Assistant HTTP(S) base URL the container can reach — do not copy someone else's hostname or private address.

1. Create a restricted data directory

   Create <PERSISTENT_DATA_PATH> on the host, make it readable and writable only by the account the service runs as, and add it to your backup. Do not sync that directory to a public location.

2. Prepare secret injection

   Create variables for the HA URL and the long-lived token in your secret store. If an env file is your only option, give the file the least privilege it needs and keep it out of version control.

3. Start the pinned-version container

   Run the command above; confirm that you are using --network host, version 2.0.55 and the /data mount. Do not remove the persistent volume just to get the container to start.

4. Verify health and the logs

   Check the container status and the startup log first, then open the Web UI from a controlled network. Share only a redacted error summary, never the list of environment variables or the full configuration.

5. Test that a rebuild keeps the data

   Before you build a production bridge, record the version and where the backup lives; an update drill should be able to rebuild the container against the same /data. Do not test by deleting the volume.

Global npm: only where you can manage a long-running service

A global npm install gives you none of the process supervision, network isolation or data mounts that Supervisor or a container layer provide. You maintain the compatible Node.js, the service account, systemd or another process manager, the restart policy, log rotation and the storage location yourself. If those responsibilities are unfamiliar, go back to the add-on or Docker.

npm install -g @riddix/[email protected]

home-assistant-matter-hub start   --home-assistant-url="<HA_BASE_URL>"   --home-assistant-access-token="<HA_LONG_LIVED_ACCESS_TOKEN>"   --storage-location="<PERSISTENT_DATA_PATH>"   --log-level=info

The installation docs at the same v2.0.55 tag still use the old package name, but the release workflow rewrites it to @riddix/hamh at publish time; go by the upstream release workflow and the published package. The executable after installation is still home-assistant-matter-hub. Command-line arguments can end up in shell history or in a process listing, so for a real long-running service inject the token as HAMH_HOME_ASSISTANT_ACCESS_TOKEN from a protected service environment or secret file, rather than leaving it on the command line. The environment-variable rule is to uppercase the option, turn hyphens into underscores and add the HAMH_ prefix — --storage-location maps to HAMH_STORAGE_LOCATION.

Every Stable 2.0.55 yargs CLI / environment start option

Every entry below comes from start-options-builder.ts at the exact commit, and is the complete yargs CLI / environment list. Those environment variables are produced by the yargs .env("HAMH") call: uppercase the long option, turn hyphens into underscores and add the prefix. Boolean, number and array values still have to match their type, and the IP allowlist can carry only one value in its environment-variable form.

HAMH_MATTER_SESSION_MAX_AGE_HOURS is a runtime-only exception: it is not a yargs option and has no CLI equivalent. --http-port still answers to its old alias --web-port, but the exact source explicitly marks that deprecated, so new deployments should use http-port. Start options are not the same as everything visible on the add-on configuration page; the pinned add-on exposes only the options listed in its schema, and the rest are managed by the add-on entrypoint, Supervisor or the fixed packaging.

Backup, upgrade and rollback order

Bridge configuration, Matter operational state, mappings and other application data have to be managed together with the version. Backing up only the compose file or the add-on configuration page is not enough; the real storage or addon_config is what makes a restore work. Take a consistent backup before any upgrade, then record the current image or package version, and only then stop the service.

1. Take a consistent backup

   For the add-on, use the Home Assistant backup and confirm it includes that add-on. For Docker or npm, stop writes or stop the service first, then back up the whole persistent data directory. Encrypt the backup itself and limit who can reach it.

2. Record the version you can roll back to

   Record Stable 2.0.55 and the deployment method, not the token. For Docker, keep an explicit tag you can pull again; for npm, record the package version; for the add-on, record the repository and the version.

3. Change one layer at a time

   When you upgrade the image or the package, leave the bridge filter, the port, the network interface and the HA token alone, so that a failure still tells you where it came from.

4. Verify four layers after it starts

   Confirm the process, the HA connection, that the bridge is running, and the state of your existing controllers, in that order. Do not rebuild a bridge because the version display has not updated; deal with the front-end version mismatch first.

5. Restore both the data and the version on failure

   Stop the failed version first, then restore the matching data backup and the original version. Do not hand a data directory that a newer version has already written to straight to an older version, unless the pinned-version docs explicitly support it.

A conservative setup for a 2–4 GB host

The upstream low-resource guide estimates: Node.js and the Matter cluster definitions take about 200–300 MB; the HA registry about 50–150 MB, growing with the entity count; each Matter endpoint about 1–3 MB; and a typical steady state for a medium install about 400–600 MB. These are estimates, not a guarantee or a hard minimum specification.

Since v2.0.25 the application sets the Node heap dynamically at 25% of available memory, clamped to 256–1024 MB. The add-on entrypoint handles this automatically and you cannot override it from the add-on configuration page; with Docker or npm you can adjust it through NODE_OPTIONS, but you have to leave enough room for the system and for HA. If the last line is Killed, or the container exits 137 or is OOMKilled, first reduce entities and turn off heavy add-ons, then reassess RAM and swap. Do not rely on raising the heap without limit.

Troubleshooting install and first start

1. The add-on store does not show Stable

   Check the repository URL, refresh the store, and identify the slug hamh; do not accept hamh-alpha or hamh-testing instead. Then cross-check that the host runs HA OS on a supported architecture.

2. HA authentication failed

   Do not paste the token into a log or a ticket. Check whether the secret is complete, whether the URL is a base URL the service can reach, and whether the token has been revoked; if you need to, create a new token, swap it in safely, and revoke the old one immediately.

3. The bridge is gone after a Docker rebuild

   Stop the container and check whether <PERSISTENT_DATA_PATH>:/data still points at the original data with the right permissions. Do not initialize an empty volume and carry on commissioning; restore from the backup first.

4. The UI opens but commissioning finds nothing

   Confirm host network, IPv6, mDNS and the network path to the controller. Open Network Diagnostics under Health to see which interface is actually bound; do not just change the HTTP port.

5. The process keeps getting killed

   Look at the container status, the exit code and the host OOM records. If it is low memory, reduce endpoints and turn off automatic composition you do not need or other heavy services, then handle swap and RAM according to your platform's policy.

6. A start option change has no effect

   Cross-check the name, the type, the HAMH_ prefix, and whether the service restarted fully. The add-on can only use the fields its pinned schema exposes; do not assume every CLI option can be pasted straight into the add-on configuration.

FAQ

Pinned-version official and source-code references

• v2.0.55 release workflow: the npm package is renamed to @riddix/hamh at publish time
• v2.0.55 official installation docs (the npm package name is overridden by the release workflow)
• v2.0.55 source for every yargs start option
• v2.0.55 runtime-only session age parser, clamp and Server Mode default
• v2.0.55 low-resource device guide
• v2.0.55 README: Stable releases and the Docker entry point
• Pinned add-on Stable config.yaml
• Pinned add-on Stable changelog