Skip to main content
Mission Control is a Next.js app you can build into a single Docker image and run on your own host. It talks to a Convex backend for sign-in, fleet management and the cloud command queue. Both halves live in ADOSMissionControlGCS under GPL-3.0: the root Dockerfile builds the GCS, and convex/ holds the functions and schema you push to the backend.
You do not need Convex to fly on the LAN. Served over plain HTTP, Mission Control connects straight to the agent and pairs over the local network with no backend. Convex is for the cloud relay (cross-network access) and for auth.

The two Convex origins

A self-hosted Convex backend exposes two origins that are not interchangeable:
  • The client API origin (:3210) serves the GCS browser bundle (NEXT_PUBLIC_CONVEX_URL) and every npx convex deploy and npx convex env set call.
  • The site origin (:3211) serves HTTP actions: the agent heartbeat and pairing (server.self_hosted.url, pairing.convex_url) and the broker auth sync.
Cross the two and the GCS loads but no drone ever appears, or sign-in works while commands never reach the agent. All published ports are in the port table.

Build and run the GCS image

The Dockerfile is a multi-stage build that produces a Next.js standalone server listening on port 4000. NEXT_PUBLIC_* values are inlined at build time, so pass the Convex client API origin the browser will reach as a build argument.
1

Build the image

Build arguments the Dockerfile accepts:
2

Run the container

The GCS is now at http://localhost:4000. The container sets PORT=4000 and HOSTNAME=0.0.0.0; map -p to any host port you want.
Cloud mode (relay through Convex and MQTT) only activates when the GCS is served over HTTPS. Over plain HTTP the GCS stays local and connects directly to agents on the LAN. Put the container behind a TLS proxy or a Cloudflare tunnel to reach a drone across networks.

Stand up a self-hosted Convex backend

You have two routes:
  • Convex Cloud is a hosted backend. In the ADOSMissionControlGCS directory run npx convex dev to create and link a deployment, then npx @convex-dev/auth to set up its auth keys.
  • Self-hosted runs the open-source backend image ghcr.io/get-convex/convex-backend in Docker. The rest of this page covers that route.
The all-in-one stack bundles the backend with its dashboard, the GCS and the relay layers in one compose file. To run the backend on its own:
1

Start the backend

Start the convex-backend service from the all-in-one compose file, or your own compose file using the same image:
2

Generate the admin key

Store the key in a secrets manager. The commands below use it as <admin-key>.
3

Push functions and schema

From a machine with the repo checked out, point the CLI at your own client API origin and admin key:
On a self-hosted backend every Convex CLI call needs your own --url and --admin-key. Without them the functions land on another deployment and sign-in fails with no visible error.
4

Generate the auth keys

A fresh backend has no signing keys. Convex Auth signs session JWTs with RS256. The helper script prints JWT_PRIVATE_KEY and JWKS lines; evaluate them into your shell:
5

Set the auth environment

Set the keys plus the GCS origin. SITE_URL is the origin the browser loads the GCS from, not a Convex origin:

Relay environment on Convex

Convex carries auth, fleet state and the cloud command queue. Live telemetry and browser video go through the MQTT broker and the video relay, and Convex needs four values for them:
Without VIDEO_RELAY_SECRET the GCS reports the relay as not configured. Without MQTT_AUTH_RELAY_SECRET the broker credential endpoint answers 503 and no device can log in to the broker.

Point the agent at the backend

Set the drone’s server.mode to self_hosted and point both server.self_hosted.url and pairing.convex_url at the site origin (:3211). The full procedure is on Self-hosting: Drone Agent.

Verify

  • curl https://convex.cloud.example.com/version returns a version, so the backend answers on the client API origin.
  • Sign-in works in the GCS, so the auth keys are on the right deployment.
  • A paired drone appears in the fleet, so its heartbeat reached the site origin.
Over plain HTTP the GCS stays local; serve it behind TLS to use the cloud relay. If the GCS loads but no drone appears, recheck the :3210 versus :3211 wiring above.

Next steps

Drone Agent

Install the agent and point it at your backend.

Ports and troubleshooting

The port table and the common failure modes.
Last modified on November 19, 2026