Deploy a MoQ relay on Kubernetes

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

A self-hosted Media over QUIC (MoQ) relay gives Kerberos Agents and Hub viewers one low-latency meeting point. The Agent publishes each live camera broadcast to the relay; browsers subscribe to the same broadcast without opening a peer-to-peer connection to the Agent.

This tutorial deploys a single MoQ relay on Kubernetes, gives it a trusted TLS certificate and public UDP endpoint, then configures the Hub Helm chart and an Agent Deployment to use it.

Understand the path

The relay is on the media path; the Hub API is not. Hub tells the browser which relay and broadcast prefix to use, while the Agent and browser each create their own WebTransport connection to the relay over HTTP/3 and QUIC.

The https:// relay URL identifies a secure HTTP origin, but this media path is not TCP. Browser WebTransport uses HTTP/3 over QUIC and UDP. A conventional HTTP Ingress, TCP reverse proxy or TLS terminator is therefore not enough; UDP must reach the relay pod and the relay must terminate TLS itself.

Before you start

You need:

• A Kubernetes cluster where a LoadBalancer Service can expose UDP 443. Cloud UDP load balancers and MetalLB are common options.
• kubectl access to create a namespace, Deployment, ConfigMap, Secret and Service.
• A hostname such as moq.example.com that you can point at the LoadBalancer.
• A publicly trusted TLS certificate for that hostname. The example uses cert-manager with an existing DNS-01 ClusterIssuer.
• Helm access to your Hub release.
• An Agent image at v3.9.2 or newer. Older Factory defaults can predate the MoQ publisher.
• Chromium-based operator browsers with outbound UDP 443 access to the relay.

Deploy the relay

apiVersion: v1
kind: Namespace
metadata:
  name: moq
---
apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
  name: moq-relay
  namespace: moq
spec:
  secretName: moq-relay-tls
  dnsNames:
    - moq.example.com
  issuerRef:
    kind: ClusterIssuer
    name: letsencrypt-production

kubectl apply -f moq-certificate.yaml
kubectl -n moq wait certificate/moq-relay --for=condition=Ready --timeout=5m
kubectl -n moq get secret moq-relay-tls

kubectl create namespace moq
kubectl -n moq create secret tls moq-relay-tls \
  --cert=fullchain.pem \
  --key=privkey.pem

apiVersion: v1
kind: ConfigMap
metadata:
  name: moq-relay
  namespace: moq
data:
  relay.toml: |
    [log]
    level = "info"

    [server]
    listen = "[::]:4443"

    [server.tls]
    cert = "/etc/moq/tls/tls.crt"
    key = "/etc/moq/tls/tls.key"

    [web.http]
    listen = "0.0.0.0:8080"

    [internal]
    listen = "0.0.0.0:9101"

    [auth]
    public = "anon"
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: moq-relay
  namespace: moq
spec:
  replicas: 1
  strategy:
    type: Recreate
  selector:
    matchLabels:
      app: moq-relay
  template:
    metadata:
      labels:
        app: moq-relay
    spec:
      securityContext:
        runAsNonRoot: true
        runAsUser: 65532
        runAsGroup: 65532
        fsGroup: 65532
        seccompProfile:
          type: RuntimeDefault
      containers:
        - name: relay
          image: moqdev/moq-relay:0.14.7
          imagePullPolicy: IfNotPresent
          args:
            - /etc/moq/relay.toml
          ports:
            - name: quic
              containerPort: 4443
              protocol: UDP
            - name: debug
              containerPort: 8080
              protocol: TCP
            - name: internal
              containerPort: 9101
              protocol: TCP
          readinessProbe:
            httpGet:
              path: /health
              port: internal
            initialDelaySeconds: 3
            periodSeconds: 10
          livenessProbe:
            httpGet:
              path: /health
              port: internal
            initialDelaySeconds: 10
            periodSeconds: 20
          resources:
            requests:
              cpu: 100m
              memory: 128Mi
            limits:
              memory: 1Gi
          securityContext:
            allowPrivilegeEscalation: false
            readOnlyRootFilesystem: true
            capabilities:
              drop:
                - ALL
          volumeMounts:
            - name: config
              mountPath: /etc/moq/relay.toml
              subPath: relay.toml
              readOnly: true
            - name: tls
              mountPath: /etc/moq/tls
              readOnly: true
      volumes:
        - name: config
          configMap:
            name: moq-relay
        - name: tls
          secret:
            secretName: moq-relay-tls
            defaultMode: 0440
---
apiVersion: v1
kind: Service
metadata:
  name: moq-relay
  namespace: moq
spec:
  type: LoadBalancer
  selector:
    app: moq-relay
  ports:
    - name: webtransport
      protocol: UDP
      port: 443
      targetPort: quic

kubectl apply -f moq-relay.yaml
kubectl -n moq rollout status deployment/moq-relay
kubectl -n moq get pods,service

kubectl -n moq get service moq-relay \
  -o jsonpath='{.status.loadBalancer.ingress[0].ip}{.status.loadBalancer.ingress[0].hostname}{"\n"}'

kubectl -n moq port-forward deployment/moq-relay 9101:9101

curl --fail http://127.0.0.1:9101/health
kubectl -n moq logs deployment/moq-relay --tail=100

Configure Hub

Add the MoQ settings to the values file used by your Hub release:

kerberoshub:
  frontend:
    features:
      liveview:
        liveStreamMode: "moq"
        hlsEnabled: "true"
        moqEnabled: "true"
        moqRelayUrl: "https://moq.example.com/anon"
        moqBroadcastPrefix: "devices"

liveStreamMode makes MoQ the initial transport for Live mode. moqEnabled exposes MoQ in the transport selector, and keeping hlsEnabled gives operators a TCP/HTTPS fallback on networks that block UDP.

Apply the values to an existing hub release in kerberos-hub:

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-frontend

If your release or namespace has a different name, use those values instead. The chart renders the relay URL and prefix into the frontend Deployment; browsers read them at runtime.

Configure each Agent

The Hub chart does not deploy edge Agents. Add the following variables to every Agent Deployment through the mechanism that owns it:

env:
  - name: AGENT_LIVE_MOQ_ENABLED
    value: "true"
  - name: AGENT_LIVE_MOQ_URL
    value: "https://moq.example.com/anon"
  - name: AGENT_LIVE_MOQ_BROADCAST_PREFIX
    value: "devices"

For an existing Kubernetes Deployment, you can test the settings directly:

kubectl -n <agent-namespace> set env deployment/<agent-deployment> \
  AGENT_LIVE_MOQ_ENABLED=true \
  AGENT_LIVE_MOQ_URL=https://moq.example.com/anon \
  AGENT_LIVE_MOQ_BROADCAST_PREFIX=devices
kubectl -n <agent-namespace> rollout status deployment/<agent-deployment>

Factory does not currently emit AGENT_LIVE_MOQ_* variables for managed Agents. Put these values into the durable Agent Deployment template or automation as well; a manual patch can be lost when Factory recreates or upgrades the Deployment.

By default the Agent publishes two video-only H.264 broadcasts when they have subscribers:

Set AGENT_LIVE_MOQ_QUALITY=high or low only when you intentionally want to publish one tier. A viewer that selects the omitted tier will find no broadcast.

Verify live playback

1. Watch the Agent logs while opening the camera in Hub:

   kubectl -n <agent-namespace> logs deployment/<agent-deployment> \
     --follow | grep -i moq

   Look for cloud.runLiveStreamMoQ() publishing the high or low stream to your relay. Connection errors usually point to DNS, UDP 443, TLS trust or relay authorization.

2. Inspect announced broadcasts through the relay’s private debug listener:

   kubectl -n moq port-forward deployment/moq-relay 8080:8080
   curl http://127.0.0.1:8080/announced/anon/devices

   The Agent publishes on demand, so open a MoQ live view before expecting both quality tiers to remain active.

3. In a Chromium-based browser, open Hub, select a camera and choose Live and MoQ. Confirm that the first frame appears after a fresh H.264 keyframe.

4. In browser developer tools, check for WebTransport or QUIC errors. A working Hub UI over TCP 443 does not prove that the browser can reach relay UDP 443.

Troubleshoot the common failures

Useful commands:

kubectl -n moq describe service moq-relay
kubectl -n moq get endpointslice -l kubernetes.io/service-name=moq-relay
kubectl -n moq logs deployment/moq-relay --follow
kubectl -n moq get events --sort-by=.lastTimestamp

Harden the deployment

The /anon route allows anyone who can reach the relay to publish and subscribe below that path. Agent keys make broadcast names harder to guess, but they are not authorization.

For a controlled trial, restrict LoadBalancer source ranges and firewall rules to known Agent and operator networks. For an internet-facing production service, replace anonymous access with short-lived, path-scoped publisher and subscriber tokens. That requires a credential flow which gives each Agent a device-scoped publisher URL and each browser a subscriber-scoped URL; the current static Hub Helm and Agent environment values do not provide that lifecycle by themselves.

Also add production controls appropriate to your environment:

• Scrape the private port 9101 /metrics endpoint and alert on restarts, resource pressure and failed sessions.
• Set CPU and memory after measuring concurrent publishers, subscribers and egress; the example values are starting points.
• Keep debug port 8080 private and protect it with a NetworkPolicy if other cluster tenants are untrusted.
• Back up the relay manifest and pin the image by digest when your release process requires immutable artifacts.
• Test certificate rotation. Relay v0.14.7 watches certificate files for new connections, while existing QUIC sessions keep their original identity.
• Keep HLS enabled as the operational fallback for networks that block HTTP/3 or UDP.

For the transport tradeoffs and complete firewall comparison, read Choose a live-stream transport: MoQ vs HLS vs WebRTC.