deCONZ

Last reviewed Sep 13, 2026 · 768 words

deCONZ is a decision about hardware before it is a decision about software. It only drives the ConBee USB sticks and the RaspBee Raspberry Pi hats from dresden elektronik, so if you already own one of those this guide is for you, and if you own a Sonoff or SkyConnect dongle it is not. With the right stick, deCONZ gives you a Zigbee coordinator with a REST API modelled on the Philips Hue bridge, a web app called Phoscon for pairing, and a graphical map of the mesh that shows every link and its signal quality. That map is the thing no rival has, and it is why people stay.

The open part and the closed part

The repository on GitHub is deconz-rest-plugin, the BSD-licensed plugin that provides the REST API and holds the device definitions, at about 1,909 stars. The deCONZ core application that talks to the radio and draws the mesh editor is closed source and ships as a binary from dresden elektronik. In day-to-day use you install the whole bundle and never think about the split, but it matters for two reasons: only the vendor can fix a bug in the Zigbee stack itself, and the project's future is tied to one small German company's roadmap. Adding support for a new device, by contrast, is a JSON file in the open plugin (a DDF, in the project's terms), and the community does contribute those.

Docker with a USB device and a VNC port

The container needs the stick passed through, and the desktop GUI needs a way out.

services:
  deconz:
    image: deconzcommunity/deconz:stable
    devices:
      - /dev/ttyACM0:/dev/ttyACM0
    environment:
      - DECONZ_DEVICE=/dev/ttyACM0
      - DECONZ_VNC_MODE=1
      - DECONZ_VNC_PASSWORD=change-me
      - TZ=Europe/Berlin
    ports:
      - "8080:80"
      - "5900:5900"
    volumes:
      - ./deconz:/opt/deCONZ
    restart: unless-stopped

ConBee II and III show up as /dev/ttyACM0 on most Linux hosts; the original ConBee is /dev/ttyUSB0. DECONZ_VNC_MODE=1 exposes the desktop application over VNC on port 5900, which is how you reach the mesh editor from a headless server. Phoscon is on port 8080. Put the stick on a USB extension cable away from the host's USB 3 ports and any SSD enclosure; USB 3 interference is the number one cause of "devices keep dropping" and a 1-metre cable fixes it. Keep the stick firmware current from the Phoscon settings page, and budget the 256 MB the GUI wants; it is a Qt application and does not idle for free.

Phoscon for pairing, REST for everything else

Phoscon handles the human tasks: open the network for 3 minutes, pair a bulb, name it, put it in a group, bind a switch. The REST API on the same port does the rest, and because it clones the Hue bridge API, tooling written for Hue often works with minimal changes: GET /api/<key>/lights, PUT /api/<key>/lights/3/state with {"on": true}. Get an API key by authorising the app in Phoscon's gateway settings and posting to /api. A WebSocket, on port 443 in the container, pushes state changes, which is what Home Assistant subscribes to; the HA integration discovers the gateway automatically and exposes lights, sensors, switches and button events with no MQTT broker in between.

Zigbee2MQTT and ZHA moved faster

Here is the honest part. Zigbee2MQTT supports the same ConBee sticks, supports many more coordinators besides, and tends to gain support for new devices weeks or months before a deCONZ DDF appears. ZHA, built into Home Assistant, does the same with no separate service at all. Both have larger communities. deCONZ's remaining advantages are the mesh map, very stable behaviour with older Hue and IKEA gear, and the Hue-compatible API for people running automation outside Home Assistant. If you are starting fresh with a ConBee and Home Assistant, ZHA is fewer moving parts; the first month with Home Assistant walks that route. If you came here from a Hue bridge, deCONZ is the most familiar landing.

What I'd do

Own a ConBee and run 20 to 40 mostly mainstream devices: run deCONZ in the container above, open the map when a room goes flaky, and integrate with Home Assistant natively. Buying new: get whichever coordinator Zigbee2MQTT recommends this year and skip deCONZ, because the device catalogue gap only widens. And whichever you pick, back up the gateway configuration from Phoscon after every pairing session; a Zigbee network key you cannot restore means re-pairing 40 devices by hand.