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 with 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 key 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 Enrollment Key. A single key like 123456-a1b2c3d4 is displayed (a 6-digit PIN combined with the master fingerprint) with a Copy button. The key 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 dedicated folder (e.g. superhome-worker) and, inside it, a file named docker-compose.yml with this content:

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-a1b2c3d4"   # enrollment key from step 1
    volumes:
      - superhome-worker-data:/data                 # persistent worker data
      - /etc/machine-id:/etc/machine-id:ro

volumes:
  superhome-worker-data:

Then open a terminal inside that same folder and start it:

  • Linux / macOS: open a terminal in the folder.
  • Windows: open the folder in File Explorer, then either type powershell in the address bar and press Enter, or right-click inside the folder → Open in Terminal.
docker compose up -d

docker compose looks for docker-compose.yml in the current directory, so the command must be run from the folder you created.

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 enrollment key is single-use and is no longer valid once enrollment completes.

No enrollment key needed after a restart

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

Windows: Docker tips​

If Docker Desktop won't start on Windows, check the following from PowerShell:

  • WSL is running: wsl --status should report an active default distribution. If WSL isn't installed/updated, run wsl --install (or wsl --update) and reboot.
  • Virtualization is enabled: Docker Desktop needs hardware virtualization. Open Task Manager → Performance → CPU and confirm Virtualization: Enabled. If it's disabled, turn on virtualization (VT-x / AMD-V / SVM) in the BIOS/UEFI.

Something not working?​

If the worker enrolls but the live stream doesn't show, detections never trigger, or the cluster gets stuck, see the Troubleshooting page.