# How to Set Up God's Eye View Locally: Complete Installation Guide

> Learn how to set up Gods Eye View locally with this complete installation guide. Follow simple steps to clone, install dependencies, verify your environment, and start the dev server. Get your local instance running quickly.

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

---

**Clone the repository, run `npm ci` to install dependencies, execute `npm run doctor` to verify your environment, then start the dev server with `npm run dev` to access the application at `http://localhost:4173`.**

God's Eye View (GEV) is a client-side, vanilla-JavaScript application that visualizes live, public-domain geospatial feeds on a 3-D globe using Cesium JS and Google 3D tiles. Because the architecture runs entirely in the browser with only a lightweight Node.js proxy for API calls, you can set up God's Eye View locally without complex server configuration or mandatory API keys. This guide walks you through the complete local installation process using the Vite-based build system implemented in the `bilawalsidhu/gods-eye-view` repository.

## Prerequisites and System Requirements

Before you begin, ensure your development environment meets the baseline specifications. The build system relies on **Vite** for fast bundling and hot-reloading, requiring **Node.js version 24 or higher** for optimal performance. While the application runs key-less by default, you will need a modern web browser to render the Cesium-based 3-D globe and optional API keys if you plan to enable premium features like high-resolution tiles or voice integration.

## Step-by-Step Local Installation

Follow these commands to install God's Eye View locally using the exact dependency versions locked in the repository.

### Clone the Repository

First, fetch the source code from GitHub to your local machine:

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

```

This creates the project directory containing [`src/main.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/main.js), [`package.json`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/package.json), and all data layer modules.

### Install Dependencies

Install the locked dependency tree using npm's clean-install command:

```bash
npm ci

```

This command reads the [`package-lock.json`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/package-lock.json) file and installs exact versions of Vite, Cesium, and other runtime dependencies without updating version constraints.

### Verify Your Environment

Run the built-in setup doctor to validate your Node version and network connectivity:

```bash
npm run doctor

```

According to the repository README, this script checks Node version compatibility, tests network reachability to provider endpoints, and reports any missing optional API keys without blocking the installation.

### Start the Development Server

Launch the Vite development server to serve the application locally:

```bash
npm run dev

```

The server starts on `http://localhost:4173` and watches source files for changes. In [`src/main.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/main.js), the application initializes the Cesium globe, registers data layers from `src/data/`, and starts the UI controllers defined in [`src/ui.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/ui.js).

## Optional Configuration for Premium Features

While God's Eye View operates entirely key-less using Esri satellite imagery and OpenStreetMap basemaps, you can unlock higher-resolution 3-D tiles and voice-activated tools by configuring API credentials.

### Adding API Keys via the POWER UP Interface

Navigate to `http://localhost:4173` in your browser and click the **POWER UP** chip in the interface. Select *Provider Settings* to paste API keys for Cesium ion, Google Maps, OpenAI, or AISStream. As implemented in [`src/keySetup.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/keySetup.js), these credentials store locally in a `.env` file for terminal clones or in Pinokio's `pinokio/ENVIRONMENT` for desktop installer users.

Alternatively, create a `.env` file manually in the project root:

```bash
cat > .env <<EOF
CESIUM_ION_TOKEN=your_token
GOOGLE_MAPS_KEY=your_key
OPENAI_API_KEY=your_key
EOF

```

Restart the dev server with `npm run dev` to load the premium 3-D tiles and enable the 28 voice-activated tools located in `src/voice/`.

## Understanding the Project Structure

Familiarize yourself with key source files to customize or debug the application:

- **[`src/main.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/main.js)** – Entry point that initializes the Cesium map and registers all geospatial layers.
- **[`src/ui.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/ui.js)** – Manages side panels, camera verbs, and HUD interactions.
- **`src/data/`** – Contains individual layer modules such as [`liveFlights.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/liveFlights.js) and [`satellites.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/satellites.js) that expose clean APIs for live feed consumption.
- **`src/voice/`** – Houses the OpenAI Realtime client and voice tool definitions.
- **[`scripts/dev-fresh.sh`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/scripts/dev-fresh.sh)** – macOS-specific helper script that clears Vite cache and retrieves stored keys from the system Keychain.

## Summary

- **Clone and install**: Use `git clone` and `npm ci` to fetch the repository and install locked dependencies.
- **Verify setup**: Run `npm run doctor` to check Node version and network connectivity before starting the server.
- **Start locally**: Execute `npm run dev` to serve the application at `http://localhost:4173`.
- **Configure optionally**: Add API keys via the POWER UP UI or `.env` file to enable high-resolution 3-D tiles and voice features.
- **Key architecture**: The application runs client-side with modules in [`src/main.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/main.js) and `src/data/`, using Vite for bundling and hot-reloading.

## Frequently Asked Questions

### Do I need API keys to run God's Eye View locally?

No. The application functions entirely without credentials, defaulting to Esri satellite imagery and OpenStreetMap basemaps. API keys for Cesium ion, Google Maps, or OpenAI are optional and only required to unlock high-resolution 3-D tiles and voice integration features.

### What Node.js version is required?

The repository recommends Node.js 24 or higher. Running `npm run doctor` validates your current version and reports compatibility issues without blocking the installation process.

### How do I clear the Vite cache if the dev server behaves unexpectedly?

macOS users can run the [`scripts/dev-fresh.sh`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/scripts/dev-fresh.sh) helper script, which clears the Vite cache and pulls stored API keys from the system Keychain. Linux and Windows users should manually delete the `node_modules/.vite` directory and restart the server with `npm run dev`.

### Can I run God's Eye View offline after the initial setup?

Yes. Once the Vite bundler serves the initial client-side assets, the application runs offline in your browser. Live data layers fetch from public APIs listed in [`DATA_SOURCES.md`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/DATA_SOURCES.md) when connectivity is available, but the core 3-D globe and UI remain functional without an internet connection.