Skip to main content
Most self-host problems are wiring, not bugs: a call sent to the wrong Convex origin, a broker with no TLS front, or a relay pointed at an RTSP source that is not there. This page lists every port, the common failures and their fixes, and a hardening checklist for the day you expose a service beyond your LAN.

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.
The agent never dials the broker in plaintext. With the default 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 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.mode is exactly self_hosted. Any other value keeps the agent local and silent.
  • On the agent, check journalctl -u ados-cloud -o json (or ados logs query if you enabled the logging store) for the failed call and the URL it tried.
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_url wins; in self_hosted mode the relay falls back to server.self_hosted.url when 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 wrong NEXT_PUBLIC_CONVEX_URL cannot be fixed by a run-time env change. Rebuild the image with the right :3210 origin.
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://.
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 websockets transport, a TLS front on 443 must forward /mqtt to Mosquitto’s 9001 listener. With tcp, Mosquitto needs a TLS listener on the agent’s mqtt_port.
  • The browser needs wss:// too, through the same front.
  • Mission Control reads the broker URL from the MQTT_BROKER_URL env var on your Convex deployment. If it is unset, the GCS falls back to a broker it cannot reach. Set it to your own wss:// URL.
  • The broker denies anonymous access. An agent missing from passwd cannot connect. Check that mqtt-auth-sync is running and that MQTT_AUTH_RELAY_SECRET matches on Convex and on the broker host. See Self-hosting: MQTT broker.
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_PATTERN resolves to a reachable RTSP server. The compose default is rtsp://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 a 400.
  • curl http://localhost:3001/ returns a JSON status with activeSessions and 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://, so 3001 needs TLS in front of it.
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/version returns the agent version without a key. A refused connection means the agent is not up; run ados status on the box.
  • Mission Control reaches 8080 through its own LAN-pair proxy, so it can resolve .local names 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

A response means the client API origin is up.
2

Site origin reachable

The agent and the auth sync call this origin. If :3210 answers and :3211 does not, your proxy or tunnel forwards only one origin.
3

Broker subscribe over WebSocket

Press Ctrl-C after the first message. A connection error here is the browser’s failure; an empty wait means no agent is publishing.
4

Video relay health

Returns {"status":"ok",...}. Anything else means the relay is not up.
5

Agent REST on the LAN

Returns the agent version without a key.

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 :3210 and :3211; forwarding one is a common cause of the no-drone failure above.
  • Mosquitto’s 9001 WebSocket listener behind wss://.
  • The video relay’s 3001 listener behind wss://.

MQTT authentication

The reference mosquitto.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 to ados/<deviceId>/#. Never share one broker account across devices.
  • Keep mqtt-auth-sync (or a timer running regenerate-passwd.sh) running, so a re-paired device’s new key reaches the broker within one interval.

Firewall rules

  • Do not publish 1883 to the internet. Nothing remote uses it.
  • The agent REST API on 8080 is a LAN surface. Cross-network access goes through the cloud relay, not a forwarded 8080.
  • 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_KEY and JWKS) come from scripts/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_SECRET and VIDEO_RELAY_SECRET like 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.
Last modified on October 11, 2026