Skip to main content

Add a Worker Node

The worker is the only Superhome node that runs as a plain Docker container (the master runs as the HAOS app). It is typically a separate small computer, such as a Raspberry Pi 5 or a mini-PC. Any machine that can run Docker works.

The camera is configured on the master

You do not set the camera URL on the worker. The worker reads its rtsp_url and other settings from the configuration of the Superhome app in Home Assistant. Remember to set inference_mode to master-worker there (see Master-Worker Cluster).

Prerequisite: Docker​

The worker runs as a Docker container, so the worker machine needs Docker (with the Compose plugin) installed. Verify with docker --version and docker compose version.

If it isn't installed yet:

  • Linux (Pi 5, Debian/Ubuntu, etc.): the official convenience script installs Docker + Compose in one go — curl -fsSL https://get.docker.com | sh. See docs.docker.com/engine/install.
  • Windows / macOS: install Docker Desktop, which bundles Compose.
Run Docker without sudo (Linux)

After installing, add your user to the docker group so you don't need sudo: sudo usermod -aG docker $USER, then log out and back in.

Steps​

1. Generate an enrollment PIN on the master​

Open the Superhome panel in the Home Assistant left sidebar (this is the Hub), go to the Cluster section, and click Generate PIN. A 6-digit PIN is displayed, along with a short master fingerprint. The PIN is single-use and expires automatically after a short time, so do this step right before you launch the worker.

2. Launch the worker container​

On the worker machine, create a docker-compose.yml:

services:
  superhome-worker:
    image: ghcr.io/superhome-vision/superhome-worker:latest
    ports:
      - "8765:8765"
    restart: unless-stopped
    user: "1000:1000"
    cap_drop:
      - ALL
    environment:
      SUPERHOME_ROLE: worker
      SUPERHOME_MASTER_HOST: "192.168.1.X:8765"     # IP of your HA host, then :8765 (see note below)
      SUPERHOME_ENROLLMENT_PIN: "123456"            # PIN from step 1
      SUPERHOME_MASTER_FINGERPRINT: "a1b2c3d4"      # fingerprint shown next to the PIN
    volumes:
      - superhome-worker-data:/data                 # persistent worker data
      - /etc/machine-id:/etc/machine-id:ro

volumes:
  superhome-worker-data:

Start it:

docker compose up -d
Getting SUPERHOME_MASTER_HOST right

Use the form <HA_IP>:8765 (e.g. 192.168.1.50:8765):

  • <HA_IP> — the bare IP of your Home Assistant host, with no http://, https://, or trailing slash.
  • :8765 — Superhome's own port, not Home Assistant's 8123. Leave it as 8765.

3. Approve the worker on the master​

After the worker starts and enrolls, it appears in the master Hub → Cluster. Approve it there. A newly enrolled worker stays inactive until you approve it.

4. Restart the worker​

Once approved, restart the worker container so it picks up its credentials and configuration:

docker compose restart

5. Verify​

In the master Hub → Cluster, the worker should now show as connected. The PIN is single-use and is no longer valid once enrollment completes.

No PIN needed after a restart

Restarting or updating the worker container does not require a new PIN; it reconnects on its own. You only need a fresh PIN if you recreate the worker from scratch.