# Prerequisites for Running God’s Eye View: Complete Setup Guide

> Learn the essential prerequisites for running God's Eye View. Discover required Node.js and npm versions, plus optional upgrades for enhanced functionality.

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

---

**The only hard prerequisites for running God’s Eye View are Node.js 24.14 or newer (including 26.x) and npm; all other components like Pinokio, API keys, and .env files are optional upgrades.**

God’s Eye View is a browser-based simulator available in the `bilawalsidhu/gods-eye-view` repository that renders geospatial data in 3D. While the project offers multiple launch methods, understanding the prerequisites for running gods-eye-view ensures a smooth setup whether you choose the automated Pinokio path or manual installation. The requirements are minimal and well-documented in the source code, with strict version checks enforced by the setup doctor utility.

## Core System Requirements

### Node.js Runtime

The application requires a recent **Node.js** runtime. According to [`package.json`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/package.json), the engine constraint specifies `"node": ">=24.14.0 <27.0.0"`, meaning you need **Node.js 24.14.0 or later**, or **Node.js 26.x**. The project explicitly supports Node 26, and the `scripts/setup-doctor.mjs` file contains a `classifyNodeVersion()` function that validates your installation, printing warnings or errors for unsupported versions.

### Package Manager

You need **npm** to install the project’s dependencies. The setup process uses `npm ci` rather than `npm install` to ensure exact dependency locking according to the lockfile.

### Supported Platforms

The simulator is officially tested and supported on **Windows**, **macOS**, and **Linux**. The [`README.md`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/README.md) documents cross-platform compatibility in the quick-start section.

## Optional Components vs. Hard Requirements

### Pinokio Desktop Application

While not strictly required, **Pinokio 8.2 or later** provides a one-click launch experience. Pinokio handles the Node runtime management, dependency locking via `npm ci`, and automatic server startup through [`pinokio/start.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/pinokio/start.js). This path eliminates manual terminal commands but remains optional.

### API Keys for Enhanced Features

Several **API keys** unlock premium functionality but are not prerequisites to start the app:

- **Cesium ion token**: Unlocks photorealistic 3D tiles and terrain (free personal tier available)
- **Google Maps key**: Enables direct routing and place search
- **OpenAI key**: Powers voice control and AI HUD summarization

These credentials are **upgrades, not prerequisites**. You can launch the simulator without them and add keys later via the *POWER UP* panel.

### Environment File Configuration

If you add API keys, the application reads credentials from a hidden `.env` file (or Pinokio’s `pinokio/ENVIRONMENT` for Pinokio users). The [`README.md`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/README.md) notes that either file is made owner-only before secrets are written. You can reference `.env.example` for the required variable names.

## Installation Methods

### Method 1: One-Click Launch with Pinokio

This path requires no manual Node.js configuration:

1. Install or upgrade Pinokio to version **8.2 or later**
2. Open the application page at `https://pinokio.co/apps/github-com-bilawalsidhu-gods-eye-view`
3. Click **Install**, then **Start**

Pinokio automatically installs the correct Node version, executes `npm ci`, and launches the local server.

### Method 2: Manual Local Setup

For developers preferring terminal control, run these commands from the repository root:

```bash

# Clone the repository

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

# Install exact dependencies

npm ci

# Verify Node version compatibility (runs scripts/setup-doctor.mjs)

npm run doctor

# Start the development server (configured in vite.config.js)

npm run dev

```

The application serves on `http://localhost:4173` by default as configured in [`vite.config.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/vite.config.js).

## Verifying Your Environment

Before launching, run the setup doctor to validate your environment:

```bash
npm run doctor

```

This executes `scripts/setup-doctor.mjs`, which calls `classifyNodeVersion()` to check your Node.js version against the supported range. The script will error if you run an unsupported version (below 24.14) or warn if you use an untested version.

## Configuring Optional Upgrades

To add API keys after installation:

1. Launch the simulator
2. Open the **POWER UP** panel (bottom-right corner)
3. Paste your Cesium ion, Google Maps, or OpenAI credentials
4. Click **SAVE KEYS**

The application will restart with enhanced features enabled. Alternatively, manually create a `.env` file in the project root following the template in `.env.example`.

## Summary

- **Node.js 24.14.0+ or 26.x** is the only hard requirement, enforced by [`package.json`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/package.json) engines and `scripts/setup-doctor.mjs`
- **npm** is required for dependency installation via `npm ci`
- **Pinokio 8.2+** offers optional one-click automation but is not mandatory
- **API keys** (Cesium ion, Google Maps, OpenAI) are optional upgrades configurable via the POWER UP panel or `.env` file
- The simulator runs on **Windows, macOS, and Linux** and serves on `localhost:4173` by default

## Frequently Asked Questions

### Is Node.js 26.x officially supported?

Yes. According to [`package.json`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/package.json) and the [`README.md`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/README.md), Node.js 26.x is officially supported alongside the 24.x LTS line. The `classifyNodeVersion()` function in `scripts/setup-doctor.mjs` explicitly handles version 26 without warnings, though versions below 24.14 will trigger errors.

### Can I run God’s Eye View without installing Pinokio?

Absolutely. Pinokio is an optional convenience layer. You can run the simulator entirely via terminal commands (`npm ci` followed by `npm run dev`) as long as you meet the Node.js and npm prerequisites. The manual path gives you full control over the [`vite.config.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/vite.config.js) development server.

### Are API keys required to start the simulator?

No. The [`README.md`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/README.md) explicitly states that keys are "upgrades, not prerequisites." You can launch the application and explore the base 3D environment without Cesium ion, Google Maps, or OpenAI credentials. Add these later through the POWER UP panel when you need photorealistic tiles, routing, or voice control.

### Which platforms can run God’s Eye View?

The project officially supports **Windows**, **macOS**, and **Linux**. This cross-platform compatibility is documented in the quick-start section of [`README.md`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/README.md), and the Node.js-based architecture ensures consistent behavior across operating systems provided you use the specified Node version.