# How to Configure gods-eye-view Settings: A Complete Guide to API Keys, Environment Variables, and the POWER UP Panel

> Learn how to configure gods-eye-view settings with API keys and environment variables. Our guide covers the POWER UP panel for easy setup and restarts. Start visualizing your data today!

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

---

**Configure gods-eye-view by creating a `.env` file from the provided template, filling in provider API keys, and running `npm run dev`—or use the in-app POWER UP panel to paste keys and restart automatically.**

Gods-eye-view is a browser-based spy-satellite simulator that unlocks advanced capabilities—Google Photorealistic 3D tiles, OpenAI voice control, live AIS ship tracking, and more—through **provider API keys**. This guide explains how to configure gods-eye-view settings using the `.env` file, the POWER UP in-app panel, or macOS Keychain integration, with specific references to the source code implementation.

## Configuration Methods Overview

You have three ways to configure gods-eye-view settings:

| Method | Location | Best For |
|--------|----------|----------|
| **`.env` file** | Repository root (`/.env`) | Pre-launch setup, version control of template |
| **POWER UP panel** | In-app UI ([`src/keySetup.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/keySetup.js)) | On-the-fly key entry without file editing |
| **Environment variables / macOS Keychain** | Shell or Keychain | Secure credential storage, Pinokio launcher |

All methods converge on the same configuration state—the POWER UP panel writes back to `.env`, and the server reads from whichever source is available.

## Understanding Key Tiers

Gods-eye-view organizes provider keys into three tiers, displayed in the POWER UP UI ([`src/keySetup.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/keySetup.js), lines 58-79):

- **🟢 Keyless** — Runs without any keys using Esri World Imagery basemap and OpenStreetMap fallback. Includes most live feeds: OpenSky, USGS earthquakes, CelesTrak satellites.

- **🟡 Free key** — Unlocks Cesium Ion 3D terrain, AISStream ship data, NASA FIRMS wildfires, TomTom traffic flow, and extended OpenSky credits.

- **🔴 Metered** — Enables premium features: Google Maps 3D Tiles and Places search, OpenAI Realtime voice synthesis. These incur per-use costs.

## Method 1: Configure via `.env` File

The most direct approach is editing the environment file directly. Copy the template and fill in your keys:

```bash
cp .env.example .env

```

A minimal configuration with two commonly used keys:

```ini

# .env — core provider keys

GOOGLE_MAPS_API_KEY=YOUR_GOOGLE_KEY
CESIUM_ION_TOKEN=YOUR_CESIUM_TOKEN
OPENAI_API_KEY=YOUR_OPENAI_KEY
AISSTREAM_API_KEY=YOUR_AISSTREAM_KEY
TOMTOM_API_KEY=YOUR_TOMTOM_KEY

```

**Key exposure rules** (enforced by `src/keySetupCore.mjs`):

- **Client-exposed**: `GOOGLE_MAPS_API_KEY`, `CESIUM_ION_TOKEN` — injected into the browser bundle via Vite's `define` mechanism
- **Server-only**: `OPENAI_API_KEY`, `AISSTREAM_API_KEY`, etc. — proxied through the Node.js backend, never visible in DevTools

Start the dev server after saving:

```bash
npm ci && npm run dev

```

The server automatically loads values from `.env` at startup.

## Method 2: Use the In-App POWER UP Panel

For interactive configuration without leaving the browser, use the built-in setup UI:

1. **Trigger the panel** — When required keys are missing, a **POWER UP** chip appears in the bottom-right corner (rendered by [`src/keySetup.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/keySetup.js))

2. **Paste credentials** — Each key has a password-masked input field (lines 14-25 of [`src/keySetup.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/keySetup.js))

3. **Save and restart** — Clicking save POSTs to `/api/setup/keys`, which:
   - Writes keys to `.env` with owner-only permissions
   - Restarts the dev server automatically (lines 64-71)
   - Reloads the page with new capabilities active

After successful configuration, the chip displays **POWERED UP** (line 20). Keys injected via shell environment or Keychain show a "configured externally" badge (lines 88-96).

## Method 3: macOS Keychain with Pinokio

When launching via Pinokio, store credentials in the macOS Keychain for enhanced security:

```bash
security add-generic-password -U -s "google-maps-api" -a "api-key" -w "YOUR_GOOGLE_KEY"
security add-generic-password -U -s "cesium-ion-token" -a "api-token" -w "YOUR_CESIUM_TOKEN"
security add-generic-password -U -s "openai-api" -a "api-key" -w "YOUR_OPENAI_KEY"

```

Pinokio reads these entries and writes them to `pinokio/ENVIRONMENT` before launch. The POWER UP panel remains available for viewing and modifying keys, with changes persisted back through the same Keychain integration.

## Advanced Configuration Options

Beyond provider keys, customize behavior with additional environment variables:

| Variable | Purpose | Default |
|----------|---------|---------|
| `GEV_RATELIMIT_GOOGLE_PER_MIN` | Per-IP rate limit for Google Places | `60` |
| `GEV_RATELIMIT_OPENAI_PER_MIN` | Per-IP rate limit for OpenAI endpoints | `30` |
| `CCTV_SOURCES_FILE` | Path to CCTV camera source pack | — |
| `CCTV_MAX_SOURCES` | Maximum cameras to load | `48` |
| `VITE_AIS_LIVE_MAX_ROWS` | Maximum ships rendered client-side | `12000` |

Variables prefixed with `VITE_` are exposed to the browser; others remain server-only.

## Network Configuration for LAN Sharing

To make your instance accessible on the local network:

```bash
HOST=0.0.0.0 npm run dev

```

**Security consideration**: This exposes your key-broker proxy to all LAN devices. Combine with:
- Stricter `GEV_RATELIMIT_*` values
- HTTP referrer restrictions on provider keys (Google Cloud Console, Cesium Ion dashboard)
- Network-level access controls

## Where Settings Are Applied in Code

- **Server bootstrap**: `src/keySetupCore.mjs` reads `.env` and environment variables, serves `/api/setup/status` and `/api/setup/keys` endpoints
- **Client injection**: [`src/keySetup.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/keySetup.js) line 81 uses Vite `define` to inject client-safe keys
- **Test harness**: `scripts/run-unit-tests.mjs` loads the same configuration for consistent test environments

## Summary

- **Copy `.env.example` to `.env`** as your starting point for gods-eye-view configuration
- **Prioritize server-only keys** for any credential that supports proxying—keep them out of the browser bundle
- **Use the POWER UP panel** when you need to add keys without file editing or when running under Pinokio
- **Set rate limits before enabling LAN access** to protect provider quotas from unintended usage
- **Verify key exposure** in DevTools Network tab—only `GOOGLE_MAPS_API_KEY` and `CESIUM_ION_TOKEN` should appear in client requests

## Frequently Asked Questions

### Can I run gods-eye-view without any API keys?

Yes. The app functions entirely in **keyless mode** with Esri World Imagery basemap and OpenStreetMap data. You lose Google 3D Tiles, voice control, and certain premium live feeds, but core satellite tracking and base layers remain fully operational.

### Why does the POWER UP panel restart the server when I save?

The restart ensures **configuration consistency** across the Node.js backend and Vite dev server. The server must reload `.env` to apply new proxy credentials, and the client bundle needs recompilation to receive updated `VITE_` prefixed values. This implementation in `src/keySetupCore.mjs` prevents state mismatches between server and browser.

### How do I protect my Google Maps API key from quota theft?

Restrict your key in the Google Cloud Console by:
- Setting **HTTP referrers** to your localhost or domain
- Enabling **API-specific restrictions** (Maps JavaScript API, Places API only)
- Monitoring usage dashboards for anomalous spikes

Despite being client-exposed, these measures limit abuse to your approved origins.

### What's the difference between `CESIUM_ION_TOKEN` and other API keys?

`CESIUM_ION_TOKEN` uses **JWT format** and is scoped to specific asset permissions (typically `assets:read`). Unlike provider API keys that authenticate billing accounts, Ion tokens authorize access to 3D tilesets and terrain data hosted on Cesium's platform.