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 everynpx convex deployandnpx convex env setcall. - The site origin (
:3211) serves HTTP actions: the agent heartbeat and pairing (server.self_hosted.url,pairing.convex_url) and the broker auth sync.
Build and run the GCS image
TheDockerfile 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
Dockerfile accepts:2
Run the container
http://localhost:4000. The container sets PORT=4000
and HOSTNAME=0.0.0.0; map -p to any host port you want.Stand up a self-hosted Convex backend
You have two routes:- Convex Cloud is a hosted backend. In the
ADOSMissionControlGCSdirectory runnpx convex devto create and link a deployment, thennpx @convex-dev/authto set up its auth keys. - Self-hosted runs the open-source backend image
ghcr.io/get-convex/convex-backendin Docker. The rest of this page covers that route.
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
<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:
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: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’sserver.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/versionreturns 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.
: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.