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

> Run Gods Eye View locally with this complete setup guide. Clone the repo, configure your API key, install dependencies, and start the dev server in minutes.

- Repository: [Bilawal Sidhu/gods-eye-view](https://github.com/bilawalsidhu/gods-eye-view)
- Tags: how-to-guide
- Published: 2026-08-30

---

**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)](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](https://console.cloud.google.com/) |
| **OpenAI** | Voice-controlled AI HUD | No | [OpenAI Platform](https://platform.openai.com) |
| **AISStream** | Live vessel tracking data | No | [AISStream](https://aisstream.io) |
| **NASA FIRMS** | Active fire detection | No | [NASA FIRMS](https://firms.modaps.eosdis.nasa.gov) |
| **TomTom** | Real-time traffic overlay | No | [TomTom Developer](https://developer.tomtom.com) |


## 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)](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)](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)](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)](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:
   ```bash
   git clone https://github.com/bilawalsidhu/gods-eye-view.git
   cd gods-eye-view
   ```

2. **Configure environment variables** by copying the template file:
   ```bash
   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**:
   ```bash
   npm install
   ```

4. **Launch the development server** on localhost with the default port:
   ```bash
   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:

```bash
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)](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:

```bash
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)](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`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/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)](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)](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)](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.