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

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

cp .env.example .env

A minimal configuration with two commonly used keys:

# .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:

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)

2. Paste credentials — Each key has a password-masked input field (lines 14-25 of 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:

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:

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 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.

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