Set up WebRTC live view with TURN

Written by Cedric Verstraeten Created Aug 19, 2026 Updated Aug 19, 2026

WebRTC gives Kerberos Hub its most interactive live path: low-latency H.264 video, camera audio and the two-way talk backchannel. It prefers a direct Agent-to-browser connection, but NAT and enterprise firewalls often make a TURN relay the only reliable path.

This tutorial provisions a coturn endpoint, configures the Hub Helm chart and Agent with the same credentials, then proves both normal ICE negotiation and TURN fallback.

Understand the path

MQTT carries WebRTC signalling, not media. The browser sends an SDP offer and ICE candidates through the broker, and the Agent returns its answer and candidates on the reverse topic. ICE then selects the best working media path: direct UDP first, TURN relay when direct connectivity fails.

No public inbound port is opened on an Agent. Agents, browsers and TURN all establish outbound or statefully returned traffic. The TURN server is the only additional public media service.

Before you start

You need:

• A self-hosted Hub and at least one connected Agent.
• A public VM or host for coturn. The Hub chart configures TURN but does not deploy it.
• A DNS name such as turn.example.com pointing to the TURN host.
• Firewall control for the TURN listener and relay port range.
• A camera with an H.264 stream for broad browser interoperability.
• MQTT connectivity between Hub frontend and Agent for SDP/ICE signalling.

For two-way talk, the browser also needs microphone permission and the camera must support a compatible backchannel, normally G.711 µ-law (PCMU) through its ONVIF or RTSP talk path.

Configure coturn

listening-port=3478
min-port=49160
max-port=49200

realm=turn.example.com
fingerprint
lt-cred-mech
user=kerberos:replace-with-a-long-random-password

# Set this when the host is behind one-to-one NAT.
external-ip=203.0.113.20

no-multicast-peers
no-cli

turnutils_uclient \
  -y \
  -u kerberos \
  -w 'replace-with-a-long-random-password' \
  -p 3478 \
  turn.example.com

Configure Hub

Add TURN and live-view settings to the values file used by your Hub release:

turn:
  host: "turn:turn.example.com:3478"
  username: "kerberos"
  password: "replace-with-a-long-random-password"

kerberoshub:
  frontend:
    features:
      liveview:
        liveStreamMode: "webrtc"
        hlsEnabled: "true"
        moqEnabled: "false"

The chart renders only TURN_SERVER into the public frontend configuration. It gives TURN_USERNAME and TURN_PASSWORD to Hub API, which returns them through authenticated /runtime/config after login; the credentials are not written to the public env.js file.

Keeping HLS enabled gives operators a TCP/HTTPS fallback when WebRTC is blocked entirely.

Apply the values:

helm repo add kerberos https://charts.kerberos.io
helm repo update
helm upgrade hub kerberos/hub \
  --namespace kerberos-hub \
  --values values.yaml
kubectl -n kerberos-hub rollout status deployment/hub-api
kubectl -n kerberos-hub rollout status deployment/hub-frontend

Use your actual Helm release and namespace names if they differ.

Configure each Agent

The Agent must use the same coturn listener and credentials:

env:
  - name: AGENT_STUN_URI
    value: "stun:turn.example.com:3478"
  - name: AGENT_TURN_URI
    value: "turn:turn.example.com:3478"
  - name: AGENT_TURN_USERNAME
    value: "kerberos"
  - name: AGENT_TURN_PASSWORD
    valueFrom:
      secretKeyRef:
        name: agent-turn
        key: password

Factory-managed Agents persist the STUN URI, TURN URI, username and password from their camera configuration. Prefer that durable configuration path. For a direct Kubernetes test, set the variables on the Agent Deployment and then move them into the owning template or Secret:

kubectl -n <agent-namespace> set env deployment/<agent-deployment> \
  AGENT_STUN_URI=stun:turn.example.com:3478 \
  AGENT_TURN_URI=turn:turn.example.com:3478 \
  AGENT_TURN_USERNAME=kerberos \
  AGENT_TURN_PASSWORD='replace-with-a-long-random-password'
kubectl -n <agent-namespace> rollout status deployment/<agent-deployment>

Avoid command-line secrets in production because they can enter shell history. The explicit command is useful only for a short-lived test.

Verify the normal ICE path

1. Open Hub in a browser, select a camera, choose Live, then choose WebRTC from the transport menu.
2. Hover the live status indicator and open its Signalling and Network tabs.
3. Confirm the signalling phases progress through offer, candidate gathering, connecting and connected.
4. Inspect the selected connection type:

The browser console also emits structured messages prefixed with [WebRTC-diag]. Chromium’s chrome://webrtc-internals page provides the selected candidate pair, codec, bitrate, RTT, jitter and packet-loss history.

Agent logs should show a WebRTC request and the configured TURN URI:

kubectl -n <agent-namespace> logs deployment/<agent-deployment> \
  --follow | grep -i -E 'webrtc|turn|ice'

Prove TURN fallback

A successful direct connection does not prove the relay works. Temporarily force the Agent to publish relay candidates only:

kubectl -n <agent-namespace> set env deployment/<agent-deployment> \
  AGENT_FORCE_TURN=true
kubectl -n <agent-namespace> rollout status deployment/<agent-deployment>

Reconnect the WebRTC stream and confirm Hub reports Relay (TURN) and relay candidates. Then return to normal ICE selection unless policy requires every stream to use TURN:

kubectl -n <agent-namespace> set env deployment/<agent-deployment> \
  AGENT_FORCE_TURN=false

Factory does not currently emit AGENT_FORCE_TURN, so place a permanent setting in the deployment mechanism that owns the Agent or expect Factory reconciliation to remove a manual override.

Test two-way talk

With WebRTC video connected:

1. Grant microphone permission to Hub.
2. Press and hold the talk control.
3. Confirm audio reaches the camera speaker without stopping video.
4. Check the Agent logs for backchannel codec or camera-write errors if it does not.

Talk is a separate camera capability. A healthy WebRTC video path does not guarantee that the camera accepts backchannel audio.

Troubleshoot common failures

TURN bandwidth is approximately one inbound and one outbound media stream per relayed viewer. Monitor both directions and size the host, relay range and network egress for peak simultaneous live views.

For an HTTPS-only alternative that needs no ICE or TURN, continue with Set up HLS live view. For a protocol comparison, read Choose a live-stream transport: MoQ vs HLS vs WebRTC.