Z-Wave JS UI in Docker

Home Assistant's Z-Wave support runs on Z-Wave JS — and you get to choose where it lives. The default keeps it inside Home Assistant; the power move is Z-Wave JS UI, a standalone container with its own rich interface, its own network map, and a Z-Wave network that keeps running when Home Assistant restarts. On a Docker-first NAS it is the natural home for your Z-Wave stick. Here is the full setup.

Published Nov 17, 2026

Why run it separately

Z-Wave devices→USB stick→Z-Wave JS UI→WebSocket :3000→Home Assistant

Step 1 — the container

services:
  zwave-js-ui:
    image: zwavejs/zwave-js-ui:latest
    container_name: zwave-js-ui
    restart: unless-stopped
    ports:
      - "8091:8091"     # web control panel
      - "3000:3000"     # Z-Wave JS server (Home Assistant connects here)
    devices:
      - /dev/serial/by-id/usb-YOUR_ZWAVE_STICK:/dev/zwave
    environment:
      - TZ=America/New_York
    volumes:
      - ./zwave-js-ui/store:/usr/src/app/store

Two details carry the whole setup. First, the device path: use the /dev/serial/by-id/ path, never bare /dev/ttyACM0 — the by-id path survives reboots and other USB devices shuffling around, the tty name does not. Second, inside the container point the serial port at /dev/zwave (the name you mapped it to). Find your stick's exact by-id name with ls /dev/serial/by-id/ on the host.

Step 2 — security keys, and the backup that matters

On first launch, Z-Wave JS UI generates the network security keys (S0 and the S2 family) and stores them in its settings. Modern devices — locks especially — join with S2 and will not work without these keys. Back up the store volume, and copy the keys somewhere safe. Lose the keys and every securely-joined device must be excluded and re-included from scratch; with locks, that is an afternoon you will not enjoy. This is the Z-Wave equivalent of 'the keys are the network.'

Set a password on the web panel (Settings → General → authentication) before you consider this done: the panel can operate your door locks. It lives on your LAN only — never port-forward 8091.

Step 3 — connect Home Assistant

  1. In Z-Wave JS UI settings, make sure the Z-Wave JS server (WebSocket, port 3000) is enabled — it is by default.
  2. In Home Assistant: Settings → Devices & Services → Add Integration → Z-Wave. Untick 'Use the Z-Wave JS add-on' style options if offered, and enter the server URL: ws://YOUR-NAS-IP:3000.
  3. Your nodes flow in with their names from the UI. Add new devices from the UI's control panel (Add Node → inclusion), name them there, and Home Assistant inherits the names — one source of truth.

Keeping nodes healthy

Z-Wave is a mesh like the others: mains-powered devices (plugs, in-wall switches) route for battery ones, and the map in the UI shows who talks to whom. Three habits keep it boring: include new devices near their final location (or include, then let the mesh settle), run a network heal after moving furniture or devices around, and interview any node that shows as dead before assuming it died — a battery node asleep looks identical to a dead one until it wakes. Firmware updates for major brands are handled in the UI as well; do them one node at a time, on a quiet evening, not in bulk before guests arrive.

Troubleshooting

Migrating from another hub, without the tears

Most people arrive at Z-Wave JS UI from SmartThings, Wink's ghost, or a Ring Alarm base — and Z-Wave has one rule that governs the whole migration: a device can belong to exactly one network, and it must be excluded before it can be included elsewhere. The merciful part is that exclusion is promiscuous — any controller can exclude any device, so Z-Wave JS UI's own exclusion mode can free devices from a dead hub without the old hub's cooperation. Work device by device, mains-powered first (they build the new mesh's skeleton), battery devices after, locks last and closest to the stick. Rename each node as it lands and resist batch-including the whole house in one sitting; the hour you spend naming things properly is the hour that makes the network maintainable for years. And the standing warning bears repeating at exactly this moment: your fresh keys, generated in step 2, are this new network's crown jewels — back up the store volume before the migration, not after.

Gear for this build

Prices are editorial and change often; buttons show live prices. Some links may earn a commission at no cost to you — see the disclosure page.

Official documentation and references

Frequently asked questions

Z-Wave JS UI or the built-in add-on — which should a beginner pick?

If Home Assistant is your only system, the built-in path is simpler and fully supported. Choose Z-Wave JS UI when you run Docker anyway, want the better interface, or want Z-Wave independent of Home Assistant's lifecycle — you can also migrate later, since both speak the same Z-Wave JS underneath.

Does Z-Wave JS UI replace my hub (SmartThings, Ring Alarm)?

For Z-Wave devices, yes — that is the point: your stick plus this container becomes the hub, locally. Devices paired to another hub must be excluded from it first before they can join here.

How many devices can one stick handle?

Z-Wave networks support up to 232 nodes; real-world comfort ends earlier depending on chattiness and mesh quality. A few dozen well-placed devices is a normal, happy network.

Related guides