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:
bun installbun run --cwd packages/surveillance-native build # the first build compiles the core: a few minutesbun dev:infrabun devThe 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.
Real wind and live flights
Section titled “Real wind and live flights”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.fican be chosen instead; its data is for personal, non-commercial use only. WithWORLD_SIM_LIVE_TRAFFIC_API_KEYset, world-sim sends that key to adsb.lol as itsx-api-keyheader; unset, it asks without one. Terminal’s/licensespage (About → Licences) lists these sources’ notices.
Switch either one in the Simulator UI under World (Live traffic, Real wind), or through world-sim:
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.
Terrain and geoid
Section titled “Terrain and geoid”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):
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.
Measure the air picture’s latency
Section titled “Measure the air picture’s latency”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:
bun services/fusion/scripts/latency.ts run --sensors vno-rot-n,jas-sector --targets 10 # a table per sensorbun services/fusion/scripts/latency.ts run --delay-ms 400 # each radar's processing delay set for the runbun 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.
Add a module
Section titled “Add a module”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.
A second stack on other ports
Section titled “A second stack on other ports”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:
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:migratebun run deploy render dev --ports 8788=18788,8787=18787,8799=18799 --out /tmp/stack-bMAINFRAME_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.tsMAINFRAME_PROXY_URL=http://localhost:18788 bun run --cwd apps/web dev -- --port 5174Point 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.
Check and stop
Section titled “Check and stop”bun run checkbun run check:smokeThe 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.