Ports
Every default port in the stack, what binds it and who connects to it.3210 and 3211 are two origins on the same Convex host. The browser and
convex deploy use :3210; the agent and the auth sync use :3211. See
Mission Control and Convex.server.mqtt_transport: websockets it connects to wss://<mqtt_broker>:443/mqtt
(a configured 8883 is rewritten to 443). With tcp it speaks MQTT over TLS
on server.self_hosted.mqtt_port. See
Self-hosting: the agent.
Common failures
The GCS loads but no drone ever appears
The GCS loads but no drone ever appears
The agent’s heartbeat is not reaching the backend. The usual cause is a
crossed Convex origin: the agent’s
pairing.convex_url (or
server.self_hosted.url) points at the client API origin (:3210)
instead of the site origin (:3211), so the register and heartbeat calls
return 404.- Confirm both agent keys end in
:3211. - Confirm
server.modeis exactlyself_hosted. Any other value keeps the agent local and silent. - On the agent, check
journalctl -u ados-cloud -o json(orados logs queryif you enabled the logging store) for the failed call and the URL it tried.
Sign-in works but commands never reach the agent
Sign-in works but commands never reach the agent
Auth is wired, so
:3210 is correct for the browser, but the cloud command
path is broken.- The agent is not reaching the site origin.
pairing.convex_urlwins; inself_hostedmode the relay falls back toserver.self_hosted.urlwhen it is empty. Set both so every component agrees. - Mission Control was built against the wrong Convex origin.
NEXT_PUBLIC_*values are inlined at build time, so a wrongNEXT_PUBLIC_CONVEX_URLcannot be fixed by a run-time env change. Rebuild the image with the right:3210origin.
The GCS connects locally but not across networks
The GCS connects locally but not across networks
The cloud relay path is used only when Mission Control is served over
HTTPS. On
http://localhost the GCS connects straight to the agent over
the LAN and does not use Convex, MQTT or the video relay. Put the GCS
container behind a TLS-terminating proxy or tunnel so it is served over
https://.The drone shows in the fleet but there is no live data
The drone shows in the fleet but there is no live data
Fleet status arrives through the agent’s HTTPS heartbeat, so a drone can
appear while the broker path is broken. Live MAVLink, video signaling and
plugin streams need the broker.
- The agent dials TLS only. With the default
websocketstransport, a TLS front on 443 must forward/mqttto Mosquitto’s 9001 listener. Withtcp, Mosquitto needs a TLS listener on the agent’smqtt_port. - The browser needs
wss://too, through the same front. - Mission Control reads the broker URL from the
MQTT_BROKER_URLenv var on your Convex deployment. If it is unset, the GCS falls back to a broker it cannot reach. Set it to your ownwss://URL. - The broker denies anonymous access. An agent missing from
passwdcannot connect. Check thatmqtt-auth-syncis running and thatMQTT_AUTH_RELAY_SECRETmatches on Convex and on the broker host. See Self-hosting: MQTT broker.
The video pane stays black
The video pane stays black
The relay spawns an ffmpeg process per stream on the first viewer
connect, and that process needs a live RTSP source.
- Confirm the relay’s
RTSP_URL_PATTERNresolves to a reachable RTSP server. The compose default isrtsp://host.docker.internal:8554/{deviceId}; when the source is on a different host, point the pattern at it. - Confirm the drone serves RTSP at that stream name. The
{deviceId}placeholder is replaced with the WebSocket path segment, which must match[a-zA-Z0-9_-]+or the upgrade is rejected with a400. curl http://localhost:3001/returns a JSON status withactiveSessionsand a per-device viewer count. A session that never appears means no viewer reached the relay; one that appears then vanishes means ffmpeg could not pull the RTSP source.- Over HTTPS the relay must be reachable over
wss://, so3001needs TLS in front of it.
The agent does not respond on the LAN
The agent does not respond on the LAN
LAN pairing and direct status use the agent REST API on
8080.- From a machine on the same LAN,
curl http://<agent-host>:8080/api/versionreturns the agent version without a key. A refused connection means the agent is not up; runados statuson the box. - Mission Control reaches
8080through its own LAN-pair proxy, so it can resolve.localnames server-side. If Add-a-Node pairing fails, confirm the agent is reachable from the machine running the GCS, not only from your laptop.
Connectivity checklist
When something does not connect, walk the path one hop at a time:1
Backend reachable
2
Site origin reachable
:3210 answers and
:3211 does not, your proxy or tunnel forwards only one origin.3
Broker subscribe over WebSocket
4
Video relay health
{"status":"ok",...}. Anything else means the relay is not up.5
Agent REST on the LAN
Security hardening
The defaults suit a private LAN. Before you expose anything beyond it, work through this list.Choose how to expose each service
None of these services has to be public. On a single LAN you expose nothing. For cross-network access, a tunnel keeps inbound ports closed and terminates TLS for you, while port forwarding opens a router port and you terminate TLS at a reverse proxy such as nginx or Caddy. Pick one per service and keep the rest LAN-only.TLS on every public origin
Browsers block mixed content, and the agent dials the broker over TLS only:- Convex behind
https://on both origins. Forward both:3210and:3211; forwarding one is a common cause of the no-drone failure above. - Mosquitto’s
9001WebSocket listener behindwss://. - The video relay’s
3001listener behindwss://.
MQTT authentication
The referencemosquitto.conf ships with allow_anonymous false, a password
file and a deny-by-default ACL.
- Keep
allow_anonymous false. The commented bench block is for a local bench or CI only. - Each device logs in as
ados-<deviceId>with its own pairing key, scoped toados/<deviceId>/#. Never share one broker account across devices. - Keep
mqtt-auth-sync(or a timer runningregenerate-passwd.sh) running, so a re-paired device’s new key reaches the broker within one interval.
Firewall rules
- Do not publish
1883to the internet. Nothing remote uses it. - The agent REST API on
8080is a LAN surface. Cross-network access goes through the cloud relay, not a forwarded8080. - Publish only the origins a remote browser or agent needs: the Convex origins, the broker’s TLS front, the video relay and Mission Control.
Rotate the keys you generate
- The Convex admin key prints once on first boot. Keep it in a secrets manager, never in a committed file.
- The auth signing keys (
JWT_PRIVATE_KEYandJWKS) come fromscripts/generate-auth-keys.mjs. Keep the private key off shared hosts. - A leaked device pairing key is both its broker password and its HTTP credential. Rotate it by re-pairing the device; the next auth sync replaces its broker entry.
- Treat
MQTT_AUTH_RELAY_SECRETandVIDEO_RELAY_SECRETlike the admin key. The auth relay secret reads every device credential.
Next steps
Self-hosting overview
How the layers fit together.
MQTT broker
The broker, the ACL and the auth sync.
Cloud infrastructure
The relay architecture and the MQTT topic list.
Hardening
Lock down the nodes that join your stack.