Do not assume everyone should deploy by hand

The upstream installation docs list the Home Assistant OS add-on as the preferred method, and there is a reason for that beyond convenience: if you already run Home Assistant OS, Supervisor takes over starting, stopping and Ingress, and the add-on gets its connection details straight from the Home Assistant API — you never type a URL or a token in by hand. Docker and global npm exist 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.”

flowchart TD
  A["Do you run Home Assistant OS,
and want Supervisor to manage this?"] -->|"yes"| B["Stable add-on.
Supervisor handles start, stop and Ingress"]
  A -->|"no"| C{"Can you operate a container,
host networking and a persistent volume?"}
  C -->|"yes"| D["Docker, pinned to 2.0.55.
You own the token, the volume, the tag"]
  C -->|"no"| E{"Can you manage a compatible Node.js,
a system service and every start option?"}
  E -->|"yes"| F["Global npm.
You own the process, storage and rollback"]
  E -->|"no"| G["Go back to Home Assistant OS.
The add-on needs the least from you"]

HA, IPv6, mDNS and the data directory — before any of the three methods

All three methods need a working Home Assistant, a correct clock, storage that persists, and a LAN the controller can actually reach. Matter depends on IPv6, mDNS and UDP; if you run VLANs, both multicast and the return route have to be handled correctly. A Web UI that loads is not the same claim as a network that works for commissioning — that second claim is the one Chapter 4 needs, and it is worth confirming now rather than after you have built a bridge.

• 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. Basic Auth is not multi-account, RBAC or SSO — treat it as a speed bump, not a lock.

flowchart TD
  A["Add-on shows Started,
or the container is Up"] --> B{"Does the Web UI load
and show HA Online?"}
  B -->|"no"| C["Fix the HA URL, the token,
or the network path first"]
  B -->|"yes"| D{"Is host networking on,
with a working IPv6 and mDNS path?"}
  D -->|"no"| E["The service is running,
but commissioning will still fail"]
  D -->|"yes"| F["Ready for the next chapter:
creating a bridge"]

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. Step 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. Step 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. Step 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. Step 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. Step 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.

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.

The full command is docker run -d followed by these flags, in order:

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. Step 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. Step 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. Step 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. Step 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. Step 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.

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.

The installation docs at the same v2.0.55 tag still print 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, not the docs page's literal text. 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 a real long-running service should 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. For a first run, though, the start command is:

The environment-variable rule is to uppercase the option, turn hyphens into underscores and add the HAMH_ prefix — so --storage-location maps to HAMH_STORAGE_LOCATION.

flowchart LR
  A["CLI option, e.g.
storage-location"] --> B["Uppercase every letter"]
  B --> C["Turn every hyphen
into an underscore"]
  C --> D["Add the HAMH prefix"]
  D --> E["HAMH_STORAGE_LOCATION"]

The complete Stable 2.0.55 yargs CLI / environment list

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 — the same rule from the previous section. 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, in that order and no other

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. Step 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. Step 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. Step 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. Step 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. Step 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.

flowchart TD
  A["Take a consistent backup
of the persistent data"] --> B["Record the current
version and method"]
  B --> C["Change one layer only:
the image or the package"]
  C --> D{"Do all four layers verify:
process, HA, bridge, controllers?"}
  D -->|"yes"| E["Done.
Back up the new known-good state"]
  D -->|"no"| F["Stop the new version,
restore backup and old version"]

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.

flowchart TD
  A["How much RAM does
the host have free?"] -->|"about 2 GB"| B["One or two bridges,
about 50 entities total.
Turn off autoComposedDevices"]
  A -->|"about 4 GB"| C["Two to four bridges,
about 100-200 entities"]
  A -->|"8 GB or more"| D["No special setup per the docs,
still watch endpoint count"]

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.

The failures that actually happen at install and first start

Questions people ask before their first start

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

Where to go from here