bilawalsidhu/gods-eye-view

▲ 318 stars today★ 64,034⑂ 12,615

A spy satellite simulator in your browser, except the data is real. Live open source spatial intelligence on a photorealistic 3D globe.

About bilawalsidhu/gods-eye-view

bilawalsidhu/gods-eye-view is an open-source project on GitHub, mainly written in JavaScript. A spy satellite simulator in your browser, except the data is real. Live open source spatial intelligence on a photorealistic 3D globe. It currently holds 64,034 stars and 12,615 forks with 403 open issues, and was last pushed on 2026-11-10 (repository created 2026-06-22).

Project Overview

Git Homed tracks it on the Today's Trending board, currently at rank #21 with 318 new stars today.

GitHub Repository Details

Repository bilawalsidhu/gods-eye-view · default branch main · size 202620 KB · watchers 1,146 · source: GitHub REST API and repository README

README

🌐 God's Eye View

CI Reached #1 on GitHub Trending

A spy-satellite simulator in your browser — then you realize the sources are public and the data is real.

Photorealistic 3D globe. Live aircraft, ships, satellites, earthquakes, traffic, and public cameras. Hands-free voice control powered by a realtime AI agent.

_No place left behind._

Orbital HUD, a tracked live globe, FLIR terrain — then OPEN SOURCED

https://github.com/bilawalsidhu/gods-eye-view/blob/HEAD/The God's Eye View video series on YouTube

▶️ From the project behind the viral God's Eye View series _(formerly WorldView)_ — 5M+ on YouTube · 25M+ across socials

🏆 Reached #1 on GitHub Trending, daily and weekly · August 2026

#8 Product of the Day · Hunted by Chris Messina, creator of the hashtag

_“pretty cool”_ — Brendan Eich, creator of JavaScript and co-founder of Mozilla and Brave · Featured on Pinokio

⚡ Start without API keys. Install with Pinokio or run locally from the terminal. Add optional keys inside the app. → Quick Start

---

Quick Start · First Five Minutes · Talk to It · What's Live · Under the Hood · Keys & Costs · Contributing

---

🌍 Why This Exists

God's Eye View brings public signals into one explorable globe. Track the world live. Talk to it. Break it. Extend it.

Flight transponders, ship beacons, orbital elements, seismographs, and public cameras already tell us a lot about the world. God's Eye View puts them in the same place, so you can move between a global picture and an individual aircraft, ship, or street. It runs locally in your browser, with source code you can inspect and extend.

Half the magic is that it looks like a forbidden cockpit. The other half is that every line of code is inspectable.

Most feeds are live or regularly refreshed. Traffic is simulated along real roads using aggregate location data. CCTV camera poses and rocket launch trajectories are coarse estimates.

Start with the included data sources, then add your own. Each layer is a separate module.

---

🎛️ What This Thing Does

---

YouTube video about the God's Eye View open source release

▶️ The full walkthrough of everything below, on YouTube

⚡ Quick Start

Local setup needs no account or API keys. The app opens with Esri satellite imagery and keyless terrain. OSM is the fallback if Esri is unreachable. Flights, military traffic, satellites, earthquakes, public cameras, radio, and launches are available without keys.

For photorealistic 3D, add a Cesium ion token for eligible personal, non-commercial use, or a Google Maps key for the direct, metered route and Google place search. Provider terms and quotas apply. Add keys through the app's POWER UP panel; Keys & Costs explains the options.

Already installed? Update to the latest version. Older versions query
public OpenStreetMap Overpass servers, which now refuse them, so Traffic,
Mapped Installations and ALPR stay empty until you update.

Path 1 — One click, no terminal

1. Install or update Pinokio to 8.2 or later. 2. Open God's Eye View in Pinokio. 3. Click Install, then Start.

Available on Windows, macOS, and Linux. The Pinokio maintainer reports cross-platform testing of the fixed installer. The launcher installs the locked dependencies, finds a free local port, and opens the app in your system browser. The Server menu item keeps the launcher console available.

Tried before and installation failed? Update Pinokio and try again. Version 8.2 fixes the launcher installation issue; details from the Pinokio maintainer.

Using an older launcher or opening the embedded view manually? If the globe is very choppy, before treating that as a GPU compatibility or minimum-hardware problem, copy the local server URL shown by Pinokio and open the same URL in your normal hardware-accelerated browser. One Pinokio 8.2.0 user reported severe stutter in Pinokio's embedded view that went away when the same running server was opened in an external browser (#365). That points to the embedded browser rather than the app server or your hardware; it does not establish a minimum GPU requirement.

Path 2 — Terminal / coding agent

Use Node.js 24.x (24.14.0 or later) or 26.x; 24.22.1 or later (26.12.1 or later on 26) includes the October 21, 2026 security fixes, among them CVE-2026-111497. The setup doctor warns about Node 25, which is end-of-life.

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. Choose Live Contacts, Space Missions, Environmental, or Explore Manually from the first-run panel.

Startup performance

A point-in-time M5/Chrome capture measured a median 1.86-second cold start. This is a comparison baseline, not a guarantee for your machine or connection. See docs/PERFORMANCE.md.

macOS shortcut: ./scripts/dev-fresh.sh clears the Vite cache and pulls any configured keys straight from the Keychain. It starts keyless too.

Path 3 — Docker

No Node install needed; the container publishes the same dev server.

git clone https://github.com/bilawalsidhu/gods-eye-view.git
cd gods-eye-view
docker compose up

Open http://localhost:4173 as above. Everything the app saves stays in the folder you cloned, so docker compose down never loses anything:

Back up that folder and you've backed up everything; delete .env to forget your keys. Source edits still hot-reload. The port is published to 127.0.0.1 only, so the default matches the native one.

The local MCP server and ChatGPT OAuth voice are not available under Docker; use an OpenAI API key for voice.

Publishing it wider is the Sharing an instance opt-in, and it hands out Provider Settings too: the launcher trusts the container gateway as this machine, and a wider publish delivers everyone else from that same address. For an instance you mean to share, put the keys in .env by hand instead. SECURITY.md has the detail.

When you widen the publish, also set GEV_KEY_SETUP_TRUSTED_PEERS=none so the launcher trusts no gateway address.

GEV_KEY_SETUP_TRUSTED_PEERS=none docker compose up

Compose forwards GEV_KEY_SETUP_TRUSTED_PEERS and GEV_ALLOWED_HOSTS from your shell or the project's .env; an exported shell value takes precedence. You can also put GEV_KEY_SETUP_TRUSTED_PEERS=none in .env for a persistent setting. Unset or blank trusted peers retain automatic gateway discovery; none explicitly disables it. The startup log confirms that no additional peers are trusted.

Running on Linux, a NAS, or behind a reverse proxy

Run it as the user who should own the files it writes. id shows the numbers; for yourself on Linux:

env UID=$(id -u) GID=$(id -g) docker compose up

On a NAS, clone onto the share you want the data on and use the share owner's ids:

cd /volume1/docker
git clone https://github.com/bilawalsidhu/gods-eye-view.git
cd gods-eye-view
env UID=1026 GID=100 docker compose up -d

Keep the env: bash treats UID as read-only, so a plain UID=1026 in front of a command is silently ignored. If the container can't write the checkout, it says so at start. Docker Desktop on macOS and Windows maps ownership for you.

On SELinux hosts (Fedora, RHEL), compose mounts the checkout with :z so the container may read it; Docker may relabel the checkout for container access, which can take a moment on a large checkout. Without that, the start fails with Cannot find module '/app/scripts/docker-start.mjs'.

Behind a reverse proxy, put your keys in .env or pass them as environment variables - Provider Settings refuses proxied requests on purpose - and add the hostname you serve it on, for example GEV_ALLOWED_HOSTS=globe.example.lan (see Sharing an instance). The map routes compare the browser's Origin with the Host the server sees, so the proxy must pass the original Host and, when it terminates TLS, X-Forwarded-Proto. Caddy does both by default; for nginx add proxy_set_header Host $http_host;, proxy_set_header X-Forwarded-Proto $scheme; and proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;. On an install outside Docker, that forwarding header also rate-limits the proxy's users apart from your own browser. Under the default Docker bridge network every client on the host, your browser included, reaches the container from its gateway address and shares one Overpass bucket.

IPv6-only networks, rebuilding, and the test suites

The launcher reads the IPv4 default gateway, so an IPv6-only Docker network finds none: it logs No default gateway; Provider Settings stays loopback-only and the panel refuses every save. Put your keys in .env by hand there, or name the gateway yourself with GEV_KEY_SETUP_TRUSTED_PEERS after reading SECURITY.md.

node_modules deliberately stays inside the image, so it survives in an anonymous volume across restarts: after a git pull that changes dependencies, recreate it with docker compose down -v && docker compose up --build. The image also skips Puppeteer's Chromium download, which keeps it small but leaves npm run test:track to the host — npm run build and npm test run fine in the container.

Path 4 — GitHub Codespaces (cloud, no local install)

Codespaces requires a GitHub account. Overpass queries and OpenAI voice token requests return HTTP 403 through its forwarded HTTPS URL, even with API keys in .env and GEV_ALLOWED_HOSTS configured. Use a local setup for these features.

The codespace runs the dev server in a cloud workspace, so Node and the dependencies never touch your machine. The globe still renders in your own browser, so it needs the same graphics there as any other path. GitHub Free includes 120 core-hours a month with no card on file — about 60 hours on the default 2-core machine. Org and Enterprise plans include no free quota; current terms and quotas apply.

1. Fork this repository, then open your fork on GitHub. 2. Click the green Code button, the Codespaces tab, then Create codespace on main. 3. In the codespace terminal:

   nvm install 24 && nvm use 24
   npm ci
   npm run doctor
   GEV_ALLOWED_HOSTS="$CODESPACE_NAME-4173.$GITHUB_CODESPACES_PORT_FORWARDING_DOMAIN" npm run dev
   
4. Open the Ports tab, find 4173, and click the globe icon to open it in the browser. The port is private by default, so the URL asks for your GitHub login. Keep it private: a public port lets anyone use the app and the keys in your .env.

GEV_ALLOWED_HOSTS there is required, not optional. The dev server answers only the hostnames it trusts, and a forwarded port arrives on $CODESPACE_NAME-4173.$GITHUB_CODESPACES_PORT_FORWARDING_DOMAIN. Without it the page is Blocked request. This host is not allowed. Leading-dot wildcards are ignored on purpose, so pass that exact name.

⚠️ A codespace is reachable from the internet. Treat it as the wider-publish case in Sharing an instance. Provider Settings is unavailable on the forwarded URL. Never commit your workspace .env. SECURITY.md has the threat model.

Then power it up — in the app, not in a file

For a local setup, keys are upgrades, not prerequisites. When you want one, click the POWER UP chip in the bottom-right corner: Provider Settings lists every supported key, what it switches on, and where to get it. Paste, hit SAVE KEYS, and the app restarts itself with the new capability on. Once everything is configured the chip reads POWERED UP — and if a compact layout hides it, ?setup=1 reopens the same panel.

terminal clone → the repo-root .env. Either file is made owner-only _before_ a secret is written into it. These are local plaintext files, excluded from Git; the app uses your keys to contact the providers. Keychain show as _configured externally_ and are read-only to the panel. (eligible personal, non-commercial use; current terms and quotas apply) for photorealistic 3D and world terrain; a Google Maps key only for the billing-enabled, metered route + Google place search; OpenAI when you want to talk to the world. Full map, costs included, in Keys & Costs.

Older Pinokio versions and credential storage

Do not enter credentials in Pinokio 8.0.40's native Configure panel: that release does not save this nested app file correctly, and it logs submitted values. Use POWER UP → Provider Settings inside GEV instead. The Pinokio 8.2 announcement fixes installation; it does not establish that this separate Configure issue is resolved. On macOS, the Keychain via ./scripts/dev-fresh.sh remains the stronger storage option.

The server binds to localhost on both paths, and Provider Settings answers requests only from your machine. Browser-side keys (Google Maps, Cesium ion) must be restricted at their providers — SECURITY.md shows how, and it carries the LAN-sharing rules alongside Keys & Costs.

---

🕐 The First Five Minutes

Choose a first-run mission, or try these in order. The GIFs show Google Photorealistic 3D; your starting basemap depends on the keys you've added.

1. Light up the sky. Take the Live Contacts mission (or turn on Flights yourself) — thousands of live aircraft, gliding on real telemetry, detection mesh already reading the scene. Click one: the camera locks on, a trail draws behind it, and its live telemetry card comes up. 2. Take the controls. Hit COCKPIT on your tracked plane and ride it down, switching sensors mid-flight: NVG into Ironbow FLIR.

Riding with a live aircraft in cockpit view while switching sensor modes

3. Drop into a busy airport. Search one and descend to the taxiways with 3D aircraft on — grounded contacts, taxi trails, the whole apron working in real time.

Moving from a full airport overhead down to close taxiway inspection with 3D flight models

4. Look through a public camera. Turn on Cameras over Austin, London, California, Finland, or Delaware (live video). The feeds aren't webcam embeds — they project _into_ the 3D city. Cycle coverage to VIEWSHED and every camera draws its estimated coverage volume — where it reaches, and where it goes blind.

Diving into an Austin intersection with a live public camera projected into the 3D scene

5. Track something in orbit. Turn on Satellites and click the ISS — you ride along at orbital distance, orbit ring and all.

Tracking the ISS along its orbital path as it crosses over Ukraine

6. Switch the optics. Tap 1–6 — CRT, NVG, FLIR — and the whole live planet re-renders through a different sensor.

Cycling a dense live globe through CRT, FLIR, and NVG in one continuous view

7. Talk to it _(needs an OpenAI key)_: _"Take me to LAX and select the nearest airborne aircraft."_ 8. Come home. Hit Reset Globe — or just say _"zoom out to a globe view."_

Keyboard: 1–6 visual styles · H HUD · D detection · C CCTV · ` ` frame rate · Esc` out. Trackpad pinch zooms the globe.

---

🛩️ The Cockpit

Every plane should let you do this.

Real-time cockpit mode, built from live flight data: the camera rides your contact with real terrain holding underneath, all the way down — sensor styles come along for the ride, and Contacts keeps the 250 km roster one click away: jump plane to plane and fall straight into the next cockpit.

Jumping between live aircraft and falling straight into a cockpit view

The cockpit even carries its own briefing strip: nearby live signals, regional headlines, and real local weather — with an opt-in WX mode that renders volumetric clouds from actual observations around your aircraft.

A live military contact ridden through Normal, NVG, and Ironbow FLIR with dense detection

_Why cockpit mode exists: you're riding a real aircraft over real terrain — and you get to pick which sensor you see the world through._

---

🎙️ Talk to It

The standalone app offers OpenAI and Gemini under AI Provider in Settings, one choice shared by voice and chat. OpenAI is the initial default; your choice is saved in this browser. To use Gemini, add GEMINI_API_KEY in Provider Settings or your local .env file, then select Gemini. GEMINI_LIVE_MODEL defaults to gemini-3.8-live. The permanent key stays on the local server, which issues a constrained, single-use session credential.

Changing provider ends the current conversation. If voice is on, the new provider starts with the same open-mic or push-to-talk mode; a held Space key is not carried over. Gemini uses the same map actions and captions, but has no OpenAI cost meter or MINI tier. When Gemini reports that its session has expired, start voice again for a new conversation. The AI Provider setting does not change the OpenAI-backed AI HUD summary.

Next to the mic, CHAT opens a typed chat with silent replies. It uses the selected provider and the same map actions, and never asks for the microphone. OpenAI chat needs an API key (OPENAI_CHAT_MODEL), so it is off while GEV_PREFER_CODEX_OAUTH pins OpenAI to ChatGPT OAuth; Gemini chat uses a separate text model (GEMINI_CHAT_MODEL). Chat and voice panels share the left panels' glass surface and sit above the dock or dock to the right.

Voice can use an OpenAI API key or, on the same machine, an opt-in signed-in ChatGPT/Codex OAuth session. The API-key path remains the default. Selecting ChatGPT OAuth in Provider Settings reuses an existing local sign-in or starts the Codex browser sign-in flow and selects OAuth when it completes. The OpenAI key still drives the AI HUD summary: a terse, five-word intelligence-style readout of the current view that regenerates as you move.

The OAuth option is experimental. OpenAI documents ChatGPT plan usage for the Responses API; a supported third-party Realtime contract for reusing Codex tokens has not been confirmed. A successful token mint does not establish billing or support terms.

GEV reads Codex's file credentials but does not write or refresh them. It checks token shape and expiry, and reports expired sign-in as requiring re-authentication. The login button runs codex login, permits one pending attempt, and reports exit failures or a two-minute timeout. CODEX_HOME must match the directory that Codex uses. If CODEX_AUTH_JSON points elsewhere, sign in separately or fix that mismatch before using the button. Codex credential storage must use auth.json; Keychain-only and in-memory storage are not readable by GEV. On Windows, the login butt

GitHub Stars & Activity

64,034Stars
12,615Forks
403Open issues
JavaScriptLanguage

GitHub Popularity

GitHub stars64,034
Forks12,615
Open issues403
Primary languageJavaScript
LicenseNOASSERTION
Stars gained today318
Created2026-06-22
Last pushed2026-11-10

Trending History

Daily boardrank #21 · ▲ 318 stars

Related GitHub Projects

1

DietrichGebert / ponytail

JavaScript★ 188,055⑂ 10,437▲ 898 stars
→
2

addyosmani / agent-skills

JavaScript★ 114,755⑂ 11,993▲ 465 stars
→
3

cloudflare / security-audit-skill

JavaScript★ 68,554⑂ 4,515▲ 1,206 stars
→
4

chinese-poetry / chinese-poetry

JavaScript★ 54,227⑂ 10,931▲ 61 stars
→
5

Anil-matcha / Open-Generative-AI

JavaScript★ 33,758⑂ 6,417▲ 313 stars
→
6

conorbronsdon / avoid-ai-writing

JavaScript★ 5,542⑂ 477▲ 42 stars
→
7

DeanChensj / jiangshan-map

JavaScript★ 5,183⑂ 605▲ 265 stars
→
8

mattpocock / skills

Shell★ 320,257⑂ 26,819▲ 1,223 stars
→

More Trending Repositories