How to Boot the Gods Eye View Application: Pinokio and Terminal Setup

You can boot Gods Eye View either via the Pinokio desktop launcher for automated dependency management, or by cloning the repository and running npm run dev after verifying Node.js 24.x or 26.x is installed.

Gods Eye View is an open-source geospatial visualization platform maintained by bilawalsidhu. Booting the application initializes a Vite-powered development server that serves the Cesium-based 3D globe interface at http://localhost:4173. Whether you choose the automated Pinokio installer or the manual terminal workflow, the application initializes the same core architecture defined in src/main.js and vite.config.js.

Prerequisites for Booting Gods Eye View

Before starting the application, ensure your environment meets the following requirements:

• Node.js 24.x or 26.x — The npm run doctor script explicitly warns against version 25.x.
• Git — Required only for the terminal boot method to clone https://github.com/bilawalsidhu/gods-eye-view.git.
• Pinokio 8.2+ — Required only for the automated boot method (available on Windows, macOS, and Linux).

Method 1: One-Click Boot with Pinokio

Pinokio provides a containerized boot process that handles dependency installation and server initialization automatically.

Installation Steps

1. Install Pinokio 8.2 or later from the official distribution.
2. Open the Gods Eye View Pinokio page: github-com-bilawalsidhu-gods-eye-view.
3. Click Install, wait for dependency resolution to complete, then click Start.
4. Pinokio automatically opens your default browser to the local server URL.

How Pinokio Handles the Boot Process

Pinokio performs the equivalent of npm ci behind the scenes, installing exact dependency versions locked in package-lock.json. It detects a free local port, injects environment variables via a temporary ENVIRONMENT file, and executes the Vite development server. This method respects the same environment-variable precedence as a local clone, reading optional API keys from Pinokio’s secure storage or the macOS Keychain via the logic defined in src/keySetup.js.

Method 2: Manual Terminal Boot

For developers who prefer direct control over the environment, the terminal boot method provides full transparency into the initialization sequence.

Step-by-Step Commands

Execute the following commands in your terminal:

git clone https://github.com/bilawalsidhu/gods-eye-view.git
cd gods-eye-view
npm ci
npm run doctor
npm run dev

npm ci installs exact versions from the lock file, ensuring reproducible builds. npm run doctor validates Node.js version compatibility and checks for optional provider keys in .env or the system keychain. npm run dev starts the Vite server defined in vite.config.js, binding to localhost:4173 by default.

Port and Host Configuration

By default, the server binds to localhost only. To expose the application on your local network, use the helper script scripts/dev-fresh.sh or set the environment variable HOST=0.0.0.0 before running the dev command:

HOST=0.0.0.0 npm run dev

Boot Architecture and File Responsibilities

Understanding the boot sequence requires familiarity with these key source files:

• vite.config.js — Configures the Vite development server, ES module resolution, and hot-reload behavior.
• src/main.js — Entry point that initializes the Cesium globe, registers live-data layers (flights, ships, satellites), and mounts the React/Vue UI components.
• src/ui.js — Manages the HUD and panel rendering, including the POWER UP interface for key entry.
• src/keySetup.js — Implements lazy-loading logic for API keys from .env, Pinokio’s ENVIRONMENT file, or macOS Keychain.
• scripts/dev-fresh.sh — Clears the Vite cache and pulls keys from macOS Keychain before starting the server.
• .env.example — Template defining optional provider keys for Cesium ion, Google Maps, OpenAI, and other services.

During boot, the Vite server imports src/main.js, which creates the 3D visualization context. The POWER UP panel (handled by src/keySetup.js) defers API initialization until the user explicitly provides keys, allowing the application to boot without external service dependencies.

Summary

• Pinokio provides automated booting with one click, handling npm ci and environment injection internally.
• Terminal boot requires Node.js 24.x or 26.x and executes npm ci, npm run doctor, and npm run dev sequentially.
• Both methods serve the application at http://localhost:4173 by default, with optional LAN exposure via HOST=0.0.0.0.
• No API keys are required for initial boot; the POWER UP panel manages provider credentials post-launch.

Frequently Asked Questions

What Node.js version is required to boot Gods Eye View?

The application requires Node.js version 24.x or 26.x. Version 25.x is explicitly unsupported, and the npm run doctor script will generate compatibility warnings if detected.

Can I run Gods Eye View without API keys?

Yes. The application boots successfully without any API keys using demo datasets. Optional keys for Cesium ion, Google Maps, OpenAI, and other providers can be added later through the POWER UP panel or by populating a .env file based on .env.example.

How do I change the default port when booting manually?

The Vite dev server defaults to port 4173 as configured in vite.config.js. You can specify an alternative port by passing the --port flag to the dev command: npm run dev -- --port 3000.

Why does Pinokio use a different boot method than the terminal?

Pinokio abstracts the terminal commands (npm ci, npm run dev) into a containerized workflow while respecting the same environment-variable precedence. It creates a temporary ENVIRONMENT file equivalent to .env, ensuring behavioral parity with manual boot methods while providing automated dependency isolation.

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