Skip to content
ChannelWatch

mDNS Auto-Discovery

ChannelWatch can automatically find Channels DVR servers on your local network using mDNS (also called Bonjour or Zeroconf). When you open Settings > DVR Servers for the first time, a Discover DVRs on my network button scans for Channels DVR instances advertising themselves on the LAN.

How it works

Section titled “How it works”

Channels DVR advertises itself on the local network using the mDNS service type _channels._tcp.local.. ChannelWatch listens for these announcements and presents any discovered servers in a list. You can then add a discovered server with a single click rather than typing in the host and port manually.

Discovery is triggered on demand — ChannelWatch does not continuously scan the network in the background. Each time you click Discover DVRs on my network, a fresh scan runs and the results are shown immediately.

Network mode requirement

Section titled “Network mode requirement”

mDNS relies on multicast UDP packets, which only work when ChannelWatch and Channels DVR are on the same network segment. This has a direct impact on how you deploy ChannelWatch:

Section titled “Host networking (recommended for discovery)”

With network_mode: host in your compose file, ChannelWatch shares the host’s network stack and can receive mDNS multicast packets from the LAN. Discovery works automatically.

services:
  channelwatch:
    image: coderluii/channelwatch:latest
    network_mode: host
    volumes:
      - /your/config/path:/config

Bridge networking (discovery unavailable)

Section titled “Bridge networking (discovery unavailable)”

With bridge networking, Docker places ChannelWatch in an isolated network namespace. Multicast packets from the LAN do not reach the container, so mDNS discovery cannot find any servers.

When ChannelWatch detects it is running in bridge mode and discovery returns no results, it shows a clear message:

Auto-discovery requires host network mode. Add your DVR server manually below.

This is a graceful fallback — ChannelWatch does not crash or show an error. The Add Server form appears immediately below the message so you can enter the host and port directly.

Kubernetes and Tailscale

Section titled “Kubernetes and Tailscale”

mDNS multicast does not cross Kubernetes pod network boundaries or Tailscale tunnels. In these environments, discovery will return no results and the manual-add fallback applies.

For Kubernetes deployments, configure DVR servers via the YAML config file or environment variables. See YAML and Env Var Config for details.

First-run wizard

Section titled “First-run wizard”

On a fresh install, the first-run wizard includes a discovery step as the first option. If you click Discover DVRs on my network and your deployment uses host networking, any Channels DVR servers on the LAN appear in a list within a few seconds. Selecting a server from the list pre-fills the host and port fields.

If discovery finds nothing (bridge mode, no DVR on the LAN, or DVR not advertising via mDNS), the wizard falls back to the manual entry form automatically.

Troubleshooting discovery

Section titled “Troubleshooting discovery”

Discovery finds nothing but my DVR is running

  • Confirm ChannelWatch is using network_mode: host in your compose file
  • Confirm Channels DVR is running and reachable from the same machine (try curl http://dvr-host:8089/status)
  • Some older Channels DVR builds may not advertise via mDNS — use manual entry in that case

Discovery finds the wrong IP

If your DVR server has multiple network interfaces, mDNS may advertise a different IP than the one you expect. Use the manual entry form to specify the exact IP address you want ChannelWatch to connect to.

Discovery works but the connection test fails

Discovery only finds the host and port — it does not verify that ChannelWatch can actually reach the DVR API. If the connection test fails after selecting a discovered server, check firewall rules and network routing between the ChannelWatch container and the DVR host.

Next steps

Section titled “Next steps”