What you'll need

  • Node.js 24.x (24.14.0 or later) or 26.x — the setup doctor warns about Node 25, which is end-of-life. That is the only hard install for the terminal path.
  • A modern desktop browser with WebGL — the globe is a heavy 3D scene; a machine with a real GPU makes the photorealistic mode worth it.
  • No API keys to start. Flights, military traffic, satellites, earthquakes, public cameras, radio, and launches work keyless. Photorealistic 3D takes a free Cesium ion token; voice control takes an OpenAI key or a local ChatGPT/Codex sign-in. Keys are upgrades, not prerequisites.
  • No terminal? Pinokio 8.2 or later installs and starts it with one click on Windows, macOS, and Linux.

1. Install it

The terminal path is four commands. Use Node 24.x (24.14.0+) or 26.x:

git clone https://github.com/bilawalsidhu/gods-eye-view.git
cd gods-eye-view
npm ci
npm run doctor
npm run dev

Open http://localhost:4173. Pick Live Contacts, Space Missions, or Environmental from the first-run panel. The README's measured cold start on an M5 Mac in Chrome was a median 1.86 seconds — treat that as the project's own baseline, not a promise for your machine.

2. Light up the sky and track a flight

Take the Live Contacts mission — or turn on Flights yourself — and the globe fills with thousands of live aircraft gliding on real telemetry (OpenSky plus adsb.lol, 11,000+ aircraft). Click one: the camera locks on, a fading trail draws behind it, and its live telemetry card comes up. Step through the 250 km roster of everything near your target and drop into any cockpit.

Then hit COCKPIT on your tracked plane and ride it down — the camera holds the terrain under you the whole way. Switch sensors mid-flight: NVG, then FLIR/thermal, then the detection overlay that draws bounding boxes and IDs on everything in view. This is the project's signature trick: it looks like a forbidden cockpit, and every line of code is inspectable.

3. Talk to it

A person speaking into a microphone while commanding a holographic 3D Earth globe ringed with flight paths and HUD overlays
Hands-free control: the voice agent knows what it is looking at — coordinates, layers, view scale — before it answers. AI-generated illustration for AI Frontier Post.

Voice is the project's second act. Click GEV MIC, grant the microphone, and just talk. Voice uses an OpenAI API key or, on the same machine, an opt-in ChatGPT/Codex OAuth session — the key still drives the AI HUD summary, a terse five-word intelligence-style readout of your current view that regenerates as you move. The agent pulls live scene context before answering, so “what city is this?” mid-flight actually works, and entity Q&A (“what's this?” on a clicked plane or ship) answers from that object's live telemetry.

Commands worth trying, straight from the project's playbook:

“Take me to Tokyo.”
“Show me the planes overhead.”
“How many flights are over Texas right now?”
“Which ships are headed to Oakland?”
“When does the ISS pass over next?”
“Switch to night vision and turn on the flights layer.”
“Outline the state of Texas.”

The last one demonstrates the voice whiteboard: it draws the actual enclosing boundary, not a circle. Prefer typing? The app is also an MCP server — point Claude Desktop, Codex, or ChatGPT desktop at it and ask from the chat (see docs/MCP_SETUP.md).

4. Stack the layers and power it up

A night-vision cockpit view over a glowing 3D city, with a tracked aircraft ahead and green HUD bounding boxes marking ground vehicles
Cockpit view over a live 3D city with the detection overlay reading the scene — sensor looks like NVG, FLIR, Noir, and Snow are GLSL skins over the same globe. AI-generated illustration for AI Frontier Post.

Twenty layers and map sources ship with the app, and seventeen have a keyless path. The heavy hitters:

  • Satellites — an 838-object catalog from CelesTrak, color-coded by class. Hit the DENSE chip to drop in the whole Starlink shell. Ask by voice when any loaded satellite next rises over you: rise, peak, and set times.
  • Weather — animated GFS or ECMWF forecast wind, observed radar, satellite clouds, lightning, and NHC/CPHC cyclone tracks on one timeline. No key needed.
  • Earthquakes (USGS, last 24h), live vessels (AISStream, free key), active fires (NASA FIRMS, free key), space launches rolling 30 days (Launch Library 2) — and a CCTV mesh of roughly 3,900 public cameras projected into the 3D city in Austin, London, California, Finland, Delaware, and more.

When you want the upgrades, click the POWER UP chip in the bottom-right: provider settings list every supported key, what it switches on, and where to get it. The first one worth grabbing is the free Cesium ion token (eligible personal, non-commercial use) for photorealistic 3D and world terrain; a Google Maps key is the direct, metered route plus Google place search. Terminal installs store keys in the repo-root .env; the app makes that file owner-only before writing a secret into it, and it is excluded from Git.

5. Direct a scene and share it

Open the Scene director to capture cinematic camera tours of the live globe — staged moves for clips and demos. Then hand the whole view to someone else: Share Links serialize the camera, style, layers, and even one tracked target into a URL. A live target is a handoff, not a bookmark — whoever opens the link gets your exact view, tracking the same aircraft.

What you built

A local, inspectable intelligence globe: live aircraft and ships, an 838-object satellite catalog, quakes, weather, cameras, and radio — all steerable by voice, all running on your machine against public feeds. The included Nepal flood scene shows the documentary side: replay the Bhote Koshi flood with flood path, witness sources, and before-and-after imagery.

Honest limitations

  • Photorealism costs a key. Without Cesium ion or a Google Maps key you get Esri satellite imagery and keyless terrain — good, but not the photorealistic 3D from the project's GIFs.
  • Traffic is simulated. Vehicles move along real OSM roads from aggregate location data; individual vehicle positions are not live observations, though TomTom flow speeds can drive the simulation if you add a key.
  • Some things are estimates. CCTV camera poses and rocket launch trajectories are coarse priors — the app labels them that way, and camera calibration is a drag-the-gizmo manual step.
  • Voice needs OpenAI. The key path is the default; the Codex OAuth path is experimental, and the README is upfront that token minting does not establish billing or support terms.
  • Keep it updated. Older versions queried public OpenStreetMap Overpass servers that now refuse them — traffic and ALPR layers stay empty until you update.

Start with the keyless layers, add the Cesium token when the flat basemap stops impressing you, and try one voice command before you decide whether the whole thing is a toy or a tool.