Skip to content

Laptop demo

bun run demo runs the air picture’s continuous demo on your laptop: the demo staging runs all the time, but only while you need it. Start it about 15 minutes before a meeting and stop it afterwards. It is safe to run any number of times.

Terminal window
bun run demo # start, or attach to a running stack; reset the demo; wait; print the go/no-go table
bun run demo:check # the table alone, just before the meeting
bun run demo --threat-now # bring the next threat forward
bun run demo:down # back to the development defaults, then stop the stack demo started

The stack is the development stack (bun run dev, development fixtures on), switched into staging’s demo through world-sim’s API:

  • world-sim’s standing air world: the 17 sensors around Vilnius, IXL-4 VNO and RJ-120 VNO, and the continuous demo with staging’s numbers. The demo has lanes of cooperative traffic (Remote ID quads, the permitted inspection drone, a FLARM glider) and non-cooperative traffic (quads, a fixed-wing, a bird flock, a balloon). A threat flies into the VNO zone about every 10–13 minutes. A launcher reloads 60 s after its last engagement ends. Nothing engages by itself.
  • Ambient traffic off, as on staging, because the demo brings its own mix. When the demo stops, ambient traffic comes back.
  • Live ADS-B from adsb.lol, with your adsb.lol key sent as the x-api-key header.
  • The real wind from the weather module, with your Open-Meteo key (the customer endpoint).
  • Fusion on the Rust core and the DEM.
  • /licenses at http://localhost:5173/licenses.

Why the development stack and not staging’s Compose topology: it is the stack you already run. It needs no images, no deploy/.env and no Caddy. World-sim’s air world and demo are the same code as staging’s, so the picture is the same. The development extras do not change the air picture: the seeded fleet, the dev accounts, auto-cue on.

The stack runs in a detached screen session named terminal-demo, so the command returns once the demo is ready. Its logs go to logs/demo/stack.log (git-ignored).

  1. Docker, with Compose v2 (Docker Desktop or OrbStack), running.

  2. Bun 1.4.2, FFmpeg and Rust. Install Rust with rustup. On macOS also run xcode-select --install. bun run demo runs bun install and builds the Rust fusion core when needed. The first build takes a few minutes, so run it once ahead of time:

    Terminal window
    bun install
    bun run --cwd packages/surveillance-native build
  3. The DEM tiles, about 30 MB of downloads per 1° cell:

    Terminal window
    bun scripts/terrain/fetch-dem.ts --cache ~/.cache/terminal-dem

    Without them the demo runs on flat ground, and the check says so.

  4. The keys. Put them in .env.demo at the repository root. .env* is git-ignored. If you already have staging’s keys file, copy the two lines from it:

    Terminal window
    grep -E '^(WEATHER_API_KEY|WORLD_SIM_LIVE_TRAFFIC_API_KEY)=' deploy/.env.staging.air-picture-keys > .env.demo
    chmod 600 .env.demo

    The file has two lines, WEATHER_API_KEY=… (Open-Meteo) and WORLD_SIM_LIVE_TRAFFIC_API_KEY=… (adsb.lol). bun run demo reads only these two names and passes them to the stack’s environment. It never prints, logs or writes their values. It looks for the keys in this order:

    1. the file named by DEMO_KEYS_FILE;
    2. .env.demo;
    3. deploy/.env.staging.air-picture-keys.

    It checks both of these places first in this checkout, then in the main checkout, so a worktree finds your keys without a copy. Without keys the demo still runs: adsb.lol keyless and Open-Meteo’s free endpoint, with a warning.

  5. The VNO zone. The threats fly into the zone marking named VNO over the EYVI runway. On staging it is 0–150 m AGL with priority high. A zone with normal priority makes the threats score lower, so they read Medium rather than High. If the check warns about it, open Markings → VNO, set the priority to high and, if you like, the limits to 0–150 m AGL. The script never edits your markings.

About 15 minutes before:

Terminal window
bun run demo

It runs the preflight first. Each item prints a fix when it fails:

  • Docker is running, and the bun dev:infra services are up. If they are not, it runs bun dev:infra, which only starts containers and applies the schema; it never resets anything.
  • bun install is done.
  • The Rust core builds and loads.
  • The DEM tiles are present.
  • The keys file is found (it prints the key names, never the values).

Then it starts the stack, or attaches to a running one, and resets the drift. Each reset step runs only when needed:

  1. It stops a running scenario.
  2. It clears leftover scenario and harness targets, traffic flows, and sensor faults or biases, such as Jašiūnai’s from the Stage I rehearsal. This is the Simulator UI’s Clear Air Picture: ambient, live, fleet and demo targets stay.
  3. It switches ambient traffic off.
  4. It switches live traffic on from adsb.lol and the real wind on, and reads the wind again if the last read is old.
  5. It switches the demo on with staging’s numbers.
  6. It reloads a launcher that is short of full.

It then waits for each of these, with its own time limit, and prints the table:

  • fusion’s tracks;
  • the first live poll;
  • the wind;
  • the sensors;
  • live airliners on the radars;
  • a launcher’s reload.

Why 15 minutes: the picture needs a warm-up.

  • Fusion confirms the tracks.
  • Live airliners pick up the simulated radars.
  • Fusion’s per-radar bias and clock estimates settle against the ADS-B traffic.
  • The demo’s lanes fill in over the first five minutes.
  • The first threat comes about 3 minutes after the demo switches on, then every 10–13 minutes.

Just before the meeting:

Terminal window
bun run demo:check

What green means. GO means every row is ok. GO, degraded: … means the demo runs, but the named rows are worse than on staging, and the row says why. NO-GO: … names what stops the demo. The exit code is 1 only on NO-GO.

Row ok
Terminal, Simulator UI, Mainframe, Media indexer answering. Mainframe’s LiveKit and indexer checks are not needed.
Keys the keys file has both names, and the running stack uses them
Fusion ok, core rust
Terrain the DEM, with no fallback
Sensors all reporting. Silent means nothing is in that sensor’s cover, which is normal for vno-stare and, at night, for eyvi-adsb.
World-sim clock within 1 s of the wall clock
Live traffic adsb.lol keyed, polled within the last minute
Live airliners fused live airliners within ADS-B range that are fused with a simulated radar (a count and an example)
Demo on, its target count, the time to the next threat (or the threat flying)
Effectors IXL-4 VNO 4/4 ready, RJ-120 VNO ready
Weather the real wind read within 11 minutes, Open-Meteo keyed
Clean world no scenario, no leftover targets, sensors as built; Jašiūnai’s modelled bias 0, with fusion’s estimate beside it
VNO zone present, priority high
/licenses lists the Copernicus DEM, adsb.lol and Open-Meteo

The table ends with the URLs and the sign-in:

  • Terminal at http://localhost:5173, as the development operator full-operator@mainframe.local with password mainframe-full-operator;
  • the Simulator UI at http://localhost:5180.

Follow the demo script, dev-docs/mainframe/review/2026-11-06-air-picture-demo-script.md (its shot list and its Before recording look), and walkthroughs W1, W9, W11 and W12 in dev-docs/mainframe/review/2026-11-06-air-picture-walkthroughs.md. With the continuous demo running you do not spawn targets by hand. A short order:

  1. The live picture. Map over Vilnius: airliners fused from EYVI ADS-B and the simulated radars. Select one: Selection lists both sources.
  2. The mix. Tracks, sorted by threat: the Remote ID quads, the inspection drone, the glider (FLARM), the flock, the balloon, the radio-silent quads.
  3. A threat. When the demo’s threat comes (the check prints when), it leads Tracks, and Selection → Threat shows its time to VNO. Alerts counts down its entry. Then Engage With… → IXL-4 VNO → Engage. The launcher reads 3/4, reloads a minute after the engagement ends, and is full two minutes later.
  4. Replay: drag the timeline back to the engagement.
  5. /licenses: About Terminal → Licences.

The scripted MOGS Stage I rehearsal (W13) is a different session: you switch live traffic and the real wind off for it, and it runs its own threats and Jašiūnai’s bias. Afterwards bun run demo clears its leftovers and switches both back on.

A calmer picture over the bird flock and ground clutter. The default rules (Fast, for MOGS’ 2-second clock) show every radar track as pending at its first report and confirm it at the second, so a flock or a clutter patch fills the map with short-lived tracks. Before the meeting, set Mainframe Settings → Fusion → Confirmation → Track confirmation to Conservative (before AP4) and Save: tracks then appear only once confirmed (six reports from one radar, at once with two sensors or ADS-B/Remote ID) and an unlucky echo leaves again. The laptop stack and staging each read their own live fusion configuration document; set it on each. Fast puts the defaults back. See Pending and confirmed tracks.

  • Something looks wrong: run bun run demo again. It changes only what drifted and never restarts a running stack.
  • No threat for a while: bun run demo --threat-now brings the next threat forward. It spawns in its lane, so the kinds still take turns (quad on its control link, fibre FPV, enterprise quad) and the usual gap follows. While a threat flies it does nothing.
  • A launcher left empty: bun run demo reloads it (about 2 minutes). Or leave it: the demo starts a reload 60 s after the last engagement ends.
  • After the Mac slept: if the check’s World-sim clock row fails, run bun run demo --restart. It restarts a stack that bun run demo started.
  • The stack’s output: screen -r terminal-demo shows it live. Ctrl-A D leaves it running. Do not press Ctrl-C there unless you mean to stop the stack.

The check says what is degraded; the demo keeps running.

  • adsb.lol unreachable. Live aircraft fly on by dead reckoning and leave a minute after their last report. With no live aircraft left, the demo flies its fallback airliner: one simulated EYVI arrival or departure on ADS-B at a time, fused with the PSR and the C-UAS radars like a live one. The check reports it as the demo's fallback airliner demo-airliner-… is fused with a radar. Late at night adsb.lol may report a few aircraft, all beyond the ADS-B receiver’s 150 km. Then no airliner is in the picture, because the fallback flies only when there are no live aircraft at all. The check says so.
  • Open-Meteo unreachable. World-sim keeps flying the last real wind it read, and retries every minute. In this development topology the weather module reads world-sim’s wind, so the Weather panel shows the same wind. Its forecast cache is in memory (10 minutes). Staging’s file cache (data/weather-cache.json) is used only with WEATHER_SOURCE=open-meteo. A stack started offline flies the default wind until a read succeeds. The check says flying the default wind (no real profile since start).
  • The basemap needs the internet. Terminal draws Mapbox’s satellite and dark styles (apps/web/map-build.json). Without the internet the map shows its basemap unavailable notice, but every track, sensor, zone and effector layer still draws. Tiles you viewed recently may come from the browser’s cache, but this is not dependable. Pan over Vilnius and Lithuania once before the meeting anyway. A fully offline basemap needs the MapLibre build with local tiles (VITE_MAP_ENGINE=maplibre and bun scripts/mapctl.ts fetch --area lt --name lt --out apps/web/public/map, then assets --out apps/web/public/map). bun run demo does not set this up, and it has not been tried for the demo.
Terminal window
bun run demo:down # the Docker infrastructure stays up
bun run demo:down --infra # and bun dev:infra down (volumes kept)

demo:down first returns the world to what it was before the first bun run demo: the demo off and ambient traffic on, from logs/demo/state.json. It then stops the stack it started by sending Ctrl-C to the terminal-demo session, which is turbo’s own shutdown. If turbo’s tasks hang, it sends a second Ctrl-C, turbo’s forced exit. It never kills processes by pid.

If bun run demo attached to a stack you started yourself, demo:down restores the world but leaves the stack running. Stop it with Ctrl-C in its terminal. If you stopped the stack yourself before demo:down, the demo setting stays in world-sim’s saved world (services/world-sim/data/world.json). Start the stack again and run bun run demo:down to restore it, or switch the demo off in the Simulator UI.

  • It never runs bun dev:infra reset, a reseed or a factory reset.
  • It never deletes or edits Mainframe documents: your markings, missions, sensors and layouts stay.
  • It never kills processes by pid.
  • It never prints, logs or writes the key values.
  • It never touches staging, production or any remote host.
Symptom Fix
Docker is not running Start Docker Desktop or OrbStack, then run bun run demo again.
the Rust fusion core does not build Install Rust with rustup and run xcode-select --install. Then run bun run --cwd packages/surveillance-native build and read its output.
a partial stack runs (up: …) Some of the ports 5173, 5180, 8787, 8788, 8789, 8791 and 8799 answer, others do not: a crashed or half-stopped bun run dev. Stop it with Ctrl-C in its terminal, then run bun run demo.
the stack exited while starting The end of logs/demo/stack.log is printed. The earlier run’s log is in stack.prev.log.
Keys: … started without The running stack was started without the keys. If bun run demo started it, run bun run demo --restart. Otherwise restart your bun run dev with the two variables set.
Live airliners fused: none within range It is night, or adsb.lol answers with nothing near Vilnius. In the daytime there are dozens.
Fusion: core ts FUSION_CORE=ts is set in your shell. Unset it, then run bun run demo --restart.
World-sim clock fails Run bun run demo --restart.
The threat reads Medium Set the VNO zone’s priority to high (one-time setup).
The demo is on when you run plain bun run dev later You stopped the stack before demo:down. Run bun run demo:down with the stack up.