Install Mission Control

Mission Control is a Next.js application. You can use the hosted version at command.altnautica.com, install the desktop app, or run it from source as described here.

Requirements

Requirement	Value
Node.js	20 or newer
Browser	Chrome or Edge for USB Serial and Bluetooth. Other browsers can use the network methods only.
Shell	macOS or Linux shell, or Git Bash or WSL on Windows

The npm scripts use POSIX shell syntax (rm -rf, cp -R and inline VAR=value). On Windows, run them from Git Bash or WSL; they fail in cmd and PowerShell.

Run from source

Clone the repository

git clone https://github.com/altnautica/ADOSMissionControl.git
cd ADOSMissionControl

Install dependencies

npm install

Start the dev server

npm run dev

The server listens on port 4000.

Open it

Go to http://localhost:4000. The Dashboard opens. On first run a setup wizard asks for language, accepts the operator disclaimer, and sets units, region and theme.

Demo mode

Demo mode replaces real links with a simulated fleet, so every panel has something to show.

npm run demo

npm run demo sets NEXT_PUBLIC_DEMO_MODE=true and starts the dev server on port 4000. You can also add ?demo=true to any Mission Control URL, or turn Demo Mode on in Settings → General. The simulated nodes are listed on Dashboard and fleet.

npm scripts

Command	What it does
`npm run dev`	Dev server on port 4000 with Turbopack. No demo data.
`npm run demo`	Dev server on port 4000 with the demo fleet.
`npm run build`	Production build.
`npm run start`	Serve the production build on port 4000.
`npm run copy:cesium`	Copy the Cesium assets into `public/cesium`. Runs before `dev`, `demo` and `build`.
`npm run lint`	ESLint.
`npm run typecheck`	Type-check the app, the Convex functions, the Electron main process and the bundled tools.
`npm test`	The Vitest suite.
`npm run test:node`	The `*.node-test.ts` files under the Node test runner.
`npm run convex:dev`	Start the Convex dev backend and code generation.
`npm run convex:deploy`	Deploy the Convex functions.
`npm run deploy`	Run the self-host deploy tool. See Deploy tool.
`npm run desktop:dev`	Run the desktop app against the dev server. Build commands are on Desktop app.

There is no browser end-to-end test harness in the repository. Cesium assets are self-hosted from /cesium/, copied from node_modules by npm run copy:cesium before dev, demo and build, so the 3D mission preview works offline.

Environment variables

Every variable is optional. Mission Control runs standalone with none of them set. .env.example in the repository is the reference. The variables split in two because two different runtimes read them.

Next.js variables

Set these in .env.local in the project root.

Variable	Effect
`NEXT_PUBLIC_DEMO_MODE`	`true` starts in demo mode. `npm run demo` sets it for you.
`NEXT_PUBLIC_CONVEX_URL`	Your Convex deployment URL. Enables sign-in, cloud fleet and community features.
`GITHUB_TOKEN`	Raises the PX4 releases API budget from 60 to 5000 requests an hour. Read server-side only; no scopes are needed. Prefer exporting it in your shell over writing it to a file.
`GROQ_API_KEY`	Enables AI PID tuning suggestions.
`NEXT_PUBLIC_ANALYTICS_SCRIPT_URL`	Script URL for any cookieless script-tag analytics. Off by default.
`NEXT_PUBLIC_ANALYTICS_WEBSITE_ID`	Site id for the same. Both analytics variables must be set or the script does not load.

Convex server variables

These run inside Convex functions, not in Next.js, so a .env entry does nothing for them. Set them in the Convex dashboard under Settings, Environment Variables, or from the CLI:

npx convex env set KEY value

Variable	Effect
`JWT_PRIVATE_KEY`	RSA private key for signing session tokens. `npx @convex-dev/auth` sets it.
`JWKS`	JSON Web Key Set for token verification. Same setter.
`SITE_URL`	The public origin you serve Mission Control from, for example `https://mc.example.com`.
`ADOS_BOOTSTRAP_ADMIN_EMAILS`	Comma-separated emails. When the first profile is created and its email is on this list, it becomes admin.
`ADOS_ALLOW_FIRST_USER_ADMIN`	`1` makes the first profile admin when `ADOS_BOOTSTRAP_ADMIN_EMAILS` is empty. Ignored when the list is set.
`CESIUM_ION_TOKEN`	Cesium ion token for 3D terrain in the mission preview.
`GROQ_API_KEY`	AI changelog summaries and PID tuning.
`GITHUB_TOKEN`	GitHub API access for changelog sync.
`AI_PID_WEEKLY_LIMIT`	Maximum AI PID analyses per user per week. Default 3.
`MQTT_BROKER_URL`	MQTT WebSocket URL for cloud telemetry, for example `wss://mqtt.example.com/mqtt`.
`VIDEO_RELAY_URL`	Video relay WebSocket URL, for example `wss://video.example.com`.
`VIDEO_RELAY_SECRET`	Shared secret the video relay also holds. Used to mint its short-lived viewer tokens.

Without either admin variable, every new profile stays pending until an existing admin approves it. Role details are on Cloud features.

Run your own backend

Cloud features need a Convex backend. Running your own (Convex, MQTT broker, video relay) is covered in the self-hosting guide, which starts with a one-command deploy tool.

Self-hosting

Deploy Convex, the MQTT broker and the video relay on your own machine.

Update a source checkout

git pull origin main
npm install
npm run dev

Troubleshooting

Port 4000 is already in use

The npm scripts pin port 4000, so PORT is ignored. Free the port, or start Next.js on another port directly:

npm run copy:cesium && npx next dev --turbo --port 4001

USB Serial shows Chrome or Edge

Web Serial and Web Bluetooth exist only in Chromium browsers. Use Chrome or Edge, or the desktop app.

npm run dev fails on Windows

Run it from Git Bash or WSL. The scripts use POSIX shell commands.

Next steps

Connect to a drone

Reach a flight controller directly or through the Drone Agent.

Dashboard and fleet

Find your way around the main screen and the demo fleet.

Desktop app

Native UDP and TCP sockets and packaged installers.

Test with SITL

Fly a simulated ArduPilot vehicle with no hardware.

Get started

Fly

Plan and review

Firmware support

Configure the flight controller

Nodes

Test without hardware

Cloud, AI and settings

Android GCS

Requirements

Run from source

Demo mode

npm scripts

Environment variables

Next.js variables

Convex server variables

Run your own backend

Self-hosting

Update a source checkout

Troubleshooting

Next steps

Connect to a drone

Dashboard and fleet

Desktop app

Test with SITL

​Requirements

​Run from source

​Demo mode

​npm scripts

​Environment variables

​Next.js variables

​Convex server variables

​Run your own backend

Self-hosting

​Update a source checkout

​Troubleshooting

​Next steps

Connect to a drone

Dashboard and fleet

Desktop app

Test with SITL

Requirements

Run from source

Demo mode

npm scripts

Environment variables

Next.js variables

Convex server variables

Run your own backend

Update a source checkout

Troubleshooting

Next steps