How to Run God's Eye View Locally: Complete Setup Guide

Clone the repository, copy .env.example to .env and add your Google Maps API key, install dependencies with npm install, then start the development server with npm run dev -- --host localhost --port 4173.

God's Eye View is a browser-based geospatial visualization platform built with Vanilla JS, CesiumJS, and Vite. This guide explains how to run the gods-eye-view project locally, covering the architectural stack, mandatory API credentials, and the exact commands to launch the application on your machine.

Prerequisites and System Requirements

Before cloning the repository, ensure your environment meets the runtime constraints defined in the [package.json](https://github.com/bilawalsidhu/gods-eye-view/blob/main/package.json). The engines field specifies Node.js version >=24.14.0 || >=26.0.0, which is required for the modern ESM features and Vite plugins used throughout the codebase.

Running the application also requires valid API keys for third-party geospatial services. While several integrations are optional, the Google Maps API key is mandatory to render the photorealistic 3D globe tiles.

Service	Purpose	Required?	Obtained From
Google Maps	3D globe tiles and map rendering	Yes	Google Cloud Console
OpenAI	Voice-controlled AI HUD	No	OpenAI Platform
AISStream	Live vessel tracking data	No	AISStream
NASA FIRMS	Active fire detection	No	NASA FIRMS
TomTom	Real-time traffic overlay	No	TomTom Developer

Project Architecture Overview

Understanding the codebase structure helps diagnose issues when running the project locally. The application follows a modular Vanilla JS architecture orchestrated by Vite.

• Entry Point: [src/main.js](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/main.js) instantiates the Cesium viewer, loads the Google Photorealistic 3D Tiles, and registers all live data layers (flights, vessels, satellites).
• UI Layer: [src/ui.js](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/ui.js) handles panels, keyboard shortcuts, and user controls.
• AI HUD: [src/hud.js](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/hud.js) manages the optional voice-controlled assistant integration.
• Build Tool: [vite.config.js](https://github.com/bilawalsidhu/gods-eye-view/blob/main/vite.config.js) configures the dev server, build pipeline, and CesiumJS plugin settings.

The Vite development server provides hot-module replacement (HMR) and serves the application on a configurable host and port, proxying API requests to keep keys secure on the client side.

Step-by-Step Local Installation

Follow these commands in your terminal to get the application running.

1. Clone the repository and change into the project directory:

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

2. Configure environment variables by copying the template file:

   cp .env.example .env

   Edit the .env file and paste your Google Maps API key into the GOOGLE_MAPS_API_KEY field. Add any optional keys (OpenAI, AISStream, etc.) to enable additional data layers.

3. Install dependencies using npm:

   npm install

4. Launch the development server on localhost with the default port:

   npm run dev -- --host localhost --port 4173

5. Open the application in your browser at http://localhost:4173. The first-run onboarding card will appear, allowing you to enable layers such as Live Flights, CCTV cameras, and Traffic overlays.

Advanced Local Development Options

For testing on mobile devices or sharing within a local network, you must bind the server to all network interfaces.

Expose the dev server on your LAN using the --host flag:

npm run dev -- --host 0.0.0.0 --port 4173

Alternatively, macOS users can utilize the helper script [scripts/dev-fresh.sh](https://github.com/bilawalsidhu/gods-eye-view/blob/main/scripts/dev-fresh.sh), which clears the Vite cache and retrieves stored keys from the macOS Keychain before launching:

HOST=0.0.0.0 ./scripts/dev-fresh.sh

Warning: When using --host 0.0.0.0, any device on your network can access the dev server and potentially view your API keys. Ensure you have configured IP restrictions or key quotas in your provider dashboards before exposing the server publicly.

Summary

Running God's Eye View locally requires satisfying strict Node.js version constraints, configuring a Google Maps API key, and leveraging Vite for the development server.

• The [package.json](https://github.com/bilawalsidhu/gods-eye-view/blob/main/package.json) mandates Node.js >=24.14.0 || >=26.0.0 for compatibility.
• You must create a .env file from .env.example and populate GOOGLE_MAPS_API_KEY to render the 3D globe.
• Start the local server with npm run dev -- --host localhost --port 4173 and access it at http://localhost:4173.
• Use --host 0.0.0.0 or the dev-fresh.sh script for LAN testing, but be mindful of key exposure.

Frequently Asked Questions

What is the minimum Node.js version required to run God's Eye View locally?

The [package.json](https://github.com/bilawalsidhu/gods-eye-view/blob/main/package.json) specifies Node.js version >=24.14.0 || >=26.0.0 in the engines field. Versions below 24.14 lack the necessary ESM and WebSocket support required by the Vite development server and real-time data pipelines.

Why is a Google Maps API key mandatory for local development?

The application uses Google Photorealistic 3D Tiles as the base map layer, which is instantiated in [src/main.js](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/main.js). Without a valid key, the Cesium viewer cannot fetch terrain data, resulting in a blank globe or runtime errors. Other providers like Bing or OSM can be configured, but the codebase defaults to Google's tileset.

How do I access the application from another device on my network?

Append the --host 0.0.0.0 argument to the dev command: npm run dev -- --host 0.0.0.0 --port 4173. This binds the Vite server to all network interfaces, allowing you to access the app via your machine's LAN IP address (e.g., http://192.168.1.5:4173). Remember that this exposes your .env keys to the local network.

What should I do if the Vite cache causes build errors?

Clear the cache by running the provided helper script [scripts/dev-fresh.sh](https://github.com/bilawalsidhu/gods-eye-view/blob/main/scripts/dev-fresh.sh) on macOS, or manually delete the node_modules/.vite directory and restart the server. This forces Vite to rebundle dependencies and resolve stale module resolution issues.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}