Skip to main content
The MQTT broker is the live-data layer of the cloud relay. The agent and the Mission Control browser meet on it: the agent publishes the MAVLink and MSP byte planes, answers WebRTC signaling and publishes vision detections and plugin streams, and the browser subscribes and sends its uplink. You only need this layer when the GCS and the drone are not on the same LAN.
Fleet status does not go through the broker. The agent POSTs its heartbeat to Convex over HTTPS. The topic list is on Cloud infrastructure. The broker assets live in the Mission Control repository at tools/mqtt-bridge/deploy/: mosquitto.conf, acl.conf, the auth-sync scripts, and a compose file for a standalone broker.
The all-in-one stack and the deploy tool wire the same broker and auth sync for you. This page is for running the broker on its own.

Prerequisites

  • A self-hosted Convex backend. The auth sync reads its site origin (:3211). See Mission Control and Convex.
  • Docker and Docker Compose on the broker host. mosquitto_passwd ships inside the eclipse-mosquitto image.
  • A TLS front for the broker: a tunnel or a reverse proxy. The agent never dials plaintext, and an HTTPS GCS needs wss://.

The compose stack

tools/mqtt-bridge/deploy/docker-compose.yml runs two services: The repository has no forwarding service between the broker and Convex. Fleet status reaches Convex through the agent’s own heartbeat.

Listeners and TLS

mosquitto.conf declares two plaintext listeners and no TLS listener:
  • 1883, MQTT over TCP. Keep it on the host or the Docker network. The agent does not use it.
  • 9001, MQTT over WebSocket (protocol websockets). The TLS front forwards to it.
The agent always connects over TLS:
  • With the default server.mqtt_transport: websockets, the agent dials wss://<mqtt_broker>:443/mqtt. Put a TLS-terminating proxy or tunnel on 443 that forwards /mqtt to the 9001 listener.
  • With server.mqtt_transport: tcp, the agent speaks MQTT over TLS on mqtt_port. Add a TLS listener to mosquitto.conf, for example:
    and set the agent’s server.self_hosted.mqtt_port to 8883.
The browser connects over wss:// through the same front. Tell Mission Control where the broker is by setting MQTT_BROKER_URL on the Convex deployment to the full WebSocket URL, for example wss://mqtt.example.com/mqtt. The GCS reads it at run time through the public clientConfig query.

Broker authentication

The reference mosquitto.conf ships with authentication on: anonymous access is off, and the broker checks a password file and a deny-by-default topic ACL. An operator grant writes only the three uplink topics. A write grant on the whole subtree would also let a browser publish the agent’s own topics and fake telemetry for the aircraft. A publish the ACL refuses at QoS 0 is dropped silently, so confirm a publish by subscribing. The ados service account stays in the password file and the ACL. The auth sync writes it on every pass from BRIDGE_MQTT_USERNAME and BRIDGE_MQTT_PASSWORD.

Keep the password file and ACL in sync

Agent and operator credentials come from Convex, so passwd and acl.conf are generated, not hand-written. scripts/regenerate-passwd.sh fetches them from the /admin/mqtt-auth-entries HTTP action with Authorization: Bearer $MQTT_AUTH_RELAY_SECRET, rewrites both files in place and sends the broker a SIGHUP. It aborts if MQTT_AUTH_RELAY_SECRET is unset. MQTT_AUTH_RELAY_SECRET is required. Generate it once and set the same value in two places:
and in the broker host’s .env as MQTT_AUTH_RELAY_SECRET=<value>. How the sync runs:
  • All-in-one stack. The mqtt-auth-sync service in tools/selfhost/docker-compose.yml runs the script every 30 seconds (SYNC_INTERVAL_SECONDS). It shares the broker’s PID namespace to deliver the reload, so no Docker socket is mounted. A failed pass retries on the same interval, and a newly paired drone connects after the next good pass.
  • Standalone broker. Run regenerate-passwd.sh from a systemd timer or cron on the broker host, with CONVEX_HTTP_URL set to your site origin and BROKER_CONTAINER naming the broker container.
Before the broker’s first start, create the two files it mounts, or Docker creates directories at those paths. Seed acl.conf from tools/mqtt-bridge/deploy/acl.conf, then create passwd with the service account:
Re-pairing a device rotates its pairing key. The next sync picks up the new value.

Bench mode (no auth)

For a local bench or CI fixtures, mosquitto.conf carries a commented bench block that turns anonymous access on. Never run an internet-facing broker with allow_anonymous true.

Verify it works

Once the stack is up and passwd is populated, check each principal from inside the broker container:
The last command prints one message from a connected agent with a live flight controller, or exits after 5 seconds. Follow the sync from the all-in-one stack with:

Next steps

Video relay

Add live video alongside the data planes.

Ports and troubleshooting

Every port in the stack and the common failure modes.
Last modified on October 11, 2026