Skip to content
Terminal

Local development

You need Bun 1.4.2, Docker with Compose v2, and FFmpeg on your host. The simulator uses a native canvas package; Bun installs the matching package for your platform.

From the repository root:

Terminal window
bun install
bun dev:infra
bun dev

The infrastructure command starts Postgres, MinIO, and MediaMTX in Docker, creates the blob bucket, and applies the database schema. The development command runs Mainframe, its media indexer, the simulator, and Vite on your host.

Surface Address
Terminal http://localhost:5173
Mainframe health http://localhost:8788/api/health
Simulator administration http://localhost:8787/admin
Media indexer health http://localhost:8789/api/health
This documentation http://localhost:4321/, after bun run docs:dev

Sign in to Terminal as operator@mainframe.local with password mainframe-operator. The development admin is admin@mainframe.local with password mainframe-admin. These accounts and known service keys are enabled by MAINFRAME_DEV_FIXTURES=1, which the development scripts set. Never enable that flag on staging or production.

Add a module

Section titled “Add a module”

Run optional modules in another terminal:

Command What it adds
bun dev:feeds Weather and radar-net
bun dev:detections Vision analysis; requires an OpenRouter key
bun dev:tak TAK; requires generated certificates
AUTO_OPERATOR_SERIAL_PREFIX=VNG bun dev:automation Suggestions for the development simulator fleet
bun dev:autel Native Autel controller host; needs bun dev:infra autel for its managed broker and a provisioned native config
bun dev:vanagas Vanagas observer; bun dev:infra vanagas starts the vanago-akis stand-in broker it reads by default

Use bun run deploy modules to inspect the server profile catalog. The local development scripts and the deployment launcher start different topologies; keep their ports and environment files separate.

Check and stop

Section titled “Check and stop”
Terminal window
bun run check
bun run check:smoke

The first command runs static checks and unit tests. The smoke suite needs the local stack running and exercises the browser. Stop the host processes with Ctrl-C. Run bun dev:infra down to stop the Docker infrastructure while preserving its data volumes.

If a service is already running, inspect it before starting another copy. Mainframe holds a database advisory lock so two Core instances cannot share the same database accidentally.

Video after a network change

Section titled “Video after a network change”

MediaMTX uses the host candidate selected when bun dev:infra runs. Rerun that command after a network change, or use a stable hostname with CANDIDATE. Mainframe proxies WHEP signaling; browser media uses UDP/TCP 8189. The private API is localhost:9997, HLS is localhost:8888, and WHEP is localhost:8889.