Skip to content

Local development

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

The fusion module’s core is Rust, loaded into Bun as a native addon (packages/surveillance-native). Install Rust with rustup; packages/surveillance-native/rust-toolchain.toml pins 1.97.1 with rustfmt and clippy, and rustup fetches that toolchain the first time cargo runs there. On macOS cargo also needs the Xcode command-line tools (xcode-select --install).

From the repository root:

Terminal window
bun install
bun run --cwd packages/surveillance-native build # the first build compiles the core: a few minutes
bun dev:infra
bun dev

The build writes packages/surveillance-native/native/fusion.<platform>-<arch>.node. bun dev, bun run check and fusion’s tests build it as well when a Rust source changed (Turbo caches it otherwise), so the explicit step only moves the first, slow compile out of the way. A fusion that cannot load the addon refuses to start; FUSION_CORE=ts runs the TypeScript core instead.

The infrastructure command starts Postgres, RustFS (S3-compatible storage), and MediaMTX in Docker, creates the blob bucket, and applies the database schema. The development command runs Mainframe, its media indexer, the simulator, the fusion module, the weather module (the simulator’s wind, which follows the real wind), the Simulator UI and Vite on your host.

Surface Address
Terminal http://localhost:5173
Mainframe health http://localhost:8788/api/health
Simulator UI (truth against detections, scenarios, world controls) http://localhost:5180 (development); world-sim serves its build at http://localhost:8787/, and /admin leads there
Media indexer health http://localhost:8789/api/health
Fusion health http://localhost:8799/api/health
Weather health http://localhost:8791/api/health
This documentation http://localhost:4321/, after bun run docs:dev

For a demo before a meeting, bun run demo starts this stack in staging’s continuous air picture demo and checks it; see Laptop demo.

The development world uses two outside sources, both on by default:

  • Real wind. The weather module asks Open-Meteo for the DWD ICON-EU model’s wind by height over EYVI (10, 80, 120 and 180 m, then the pressure levels up to 500 hPa), falling back to ECMWF IFS 0.25° when ICON-EU fails. The simulator flies that profile and the weather module reads it back, so the simulator, fusion and the Weather panel share one wind. Weather data by Open-Meteo.com, CC BY 4.0. The free API is for non-commercial use only.
  • Live flights. The simulator asks adsb.lol every 10 seconds for the aircraft within 135 NM of EYVI and flies each one as a target, so the simulated ADS-B receivers, the SSR and the radars see real traffic. adsb.lol data is licensed under the ODbL 1.0. adsb.fi can be chosen instead; its data is for personal, non-commercial use only. With WORLD_SIM_LIVE_TRAFFIC_API_KEY set, world-sim sends that key to adsb.lol as its x-api-key header; unset, it asks without one. Terminal’s /licenses page (About → Licences) lists these sources’ notices.

Switch either one in the Simulator UI under World (Live traffic, Real wind), or through world-sim:

Terminal window
curl -X POST localhost:8787/api/sim/air/live -d '{"enabled":false}'
curl -X POST localhost:8787/api/sim/air/wind -d '{"mode":"manual"}'

The setting is saved with the world. Offline, nothing breaks: the standing world keeps flying, live aircraft fly on by dead reckoning and leave a minute after their last report, and the wind stays as it last was. Unit tests never call either service, and the browser smoke suite switches both off for its run and restores them afterwards.

Fusion and the simulator stand on the same ground: the EGM2008 geoid (committed as data/geoid/egm2008-lt.json) and a terrain model you fetch once (about 30 MB of downloads per 1° cell, kept with --cache):

Terminal window
bun scripts/terrain/fetch-dem.ts --cache ~/.cache/terminal-dem # data/terrain/ (git-ignored)

It resamples Copernicus DEM GLO-30 into map tiles: about 88 m over the area of operations, about 22 m within 20 km of each standing site. Restart the stack to load it. With it, heights above ground follow the terrain, simulated radars and cameras lose targets behind hills and the forest canopy, and the map draws each sensor’s masked coverage. Without it both fall back to flat ground (FUSION_GROUND_MSL, the simulator’s 198 m) and the geoid grid still applies; fusion’s /api/health → heights and world-sim’s /api/health → ground say what each loaded. FUSION_TERRAIN_DIR and WORLD_TERRAIN_DIR point elsewhere (empty turns the terrain off). Copernicus DEM: produced using Copernicus WorldDEM-30 © DLR e.V. 2010-2014 and © Airbus Defence and Space GmbH 2014-2018 provided under COPERNICUS by the European Union and ESA; free of charge for any use with this attribution. EGM2008: US NGA, public; GeographicLib’s grid, MIT/X11.

Sign in to Terminal as operator@mainframe.local with password mainframe-operator for Fixed Layouts only, or as full-operator@mainframe.local with mainframe-full-operator for an operator who arranges panels (the browser smoke suites use it). 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.

The Simulator UI’s Latency tab lists, per target and sensor, when the target came into coverage, was first detected, first reported by the sensor, seen by fusion, held pending, confirmed and published, with the first report → confirmed time against its budget and histograms over the last 2–15 minutes. The fusion module’s /api/health carries per-stage percentiles under latency.stages (queue, decode, hold, step, tick, publish), and /api/sources each source’s calibrated received − measured.

The harness measures the whole budget against the running stack, switching live flights and the real wind off for its run and back on after it:

Terminal window
bun services/fusion/scripts/latency.ts run --sensors vno-rot-n,jas-sector --targets 10 # a table per sensor
bun services/fusion/scripts/latency.ts run --delay-ms 400 # each radar's processing delay set for the run
bun services/fusion/scripts/latency.ts gate --baseline dev-docs/mainframe/review/ap4-1-evidence/latency-gate.json # fails on a p95 > 110 % of the baseline (without one: past the budget)
bun services/fusion/scripts/latency.ts sizing --targets 500 --minutes 3 # four sizing radars 30 km east, then a run per delay

--out <dir> writes latency-<label>.json and .md. The limits live in packages/surveillance/src/metrics/latency-budget.ts. The sizing removes its targets, then the sizing radars’ devices, then their documents.

Which modules run is the development installation bun dev is given. deploy/installations/dev/ (the default) enables every module but Legacy’s and starts only those the module table marks startable: world-sim and sim-ui, weather and fusion. dev-base is Base alone. dev-all enables the same modules and starts every one that has a workspace. bun dev starts the installation’s Docker infrastructure first (--no-infra skips it); --print shows the commands and the environment without starting anything.

Command What it runs
bun dev Mainframe, Terminal, the indexer, the derivatives worker, world-sim, sim-ui, weather, fusion
bun dev dev-all Also radar-net, detections (an OpenRouter key), the assistant, TAK (generated certificates), Autel (a provisioned native config), Generic Drone and Front
bun dev <name> Any dev-kind installation under deploy/installations/; add one to try a combination
bun dev:vanagas, bun dev:vanagas-phones Legacy, by hand; bun dev:infra up dev vanagas starts the vanago-akis stand-in broker

Use bun run deploy modules to inspect the module catalog. The development stack and the deployment launcher start different topologies; keep their ports separate.

bun dev has no port option. A second stack beside a running one (another checkout, or another installation) is started by hand against the same Docker infrastructure, with its own database, because Mainframe holds a lock per database:

Terminal window
docker exec terminal-dev-postgres-1 psql -U mainframe -d mainframe -c "CREATE DATABASE mainframe_b"
DATABASE_URL=postgres://mainframe:mainframe@localhost:5432/mainframe_b MAINFRAME_DEV_FIXTURES=1 bun run --cwd apps/mainframe db:migrate
bun run deploy render dev --ports 8788=18788,8787=18787,8799=18799 --out /tmp/stack-b
MAINFRAME_INSTALLATION=/tmp/stack-b/installation.json MAINFRAME_DEV_FIXTURES=1 \
DATABASE_URL=postgres://mainframe:mainframe@localhost:5432/mainframe_b \
MAINFRAME_TRUSTED_ORIGINS=http://localhost:5174 bun apps/mainframe/src/index.ts
MAINFRAME_PROXY_URL=http://localhost:18788 bun run --cwd apps/web dev -- --port 5174

Point world-sim at the second Mainframe with PORT, MAINFRAME_URL and MAINFRAME_PROVIDER_URL and the rendered env/world-sim.env. World-sim and fusion also open SAPIENT (TCP 8635), the ASTERIX and ADS-B multicast groups, Remote ID and the netrid feed on 8787: shift every one of those (WORLD_SIM_*_ENDPOINT, FUSION_SAPIENT_LISTEN, …) and use other multicast groups, or the second simulator feeds the first stack. Fusion takes its listen endpoints from the seeded surveillance.sources documents, not from the environment, so rewrite their ports and groups in the second database (with Mainframe stopped) before fusion starts. Keep ffmpeg off world-sim’s PATH and WORLD_PERSIST empty so it publishes no video into the shared media server and writes no world state. Front’s development publicUrl is not shifted by --ports; set settings.base.modules.front.publicUrl in the rendered installation.json. Smoke specs run against such a stack with SMOKE_BASE_URL, SMOKE_MAINFRAME_URL and SMOKE_WORLD_URL.

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.

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.