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

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:

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

This creates the project directory containing src/main.js, package.json, and all data layer modules.

Install Dependencies

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

npm ci

This command reads the 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:

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:

npm run dev

The server starts on http://localhost:4173 and watches source files for changes. In 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.

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, 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:

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 – Entry point that initializes the Cesium map and registers all geospatial layers.
• src/ui.js – Manages side panels, camera verbs, and HUD interactions.
• src/data/ – Contains individual layer modules such as liveFlights.js and 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 – 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 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 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 when connectivity is available, but the core 3-D globe and UI remain functional without an internet connection.

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