Installation

Installation Overview

World Monitor can be deployed in three ways:

Hosted Web App

Use the production deployment at worldmonitor.app — no setup required

Desktop Application

Native app for macOS, Windows, and Linux with local API sidecar

Self-Hosted

Deploy your own instance on Vercel, Railway, or custom infrastructure

Desktop Installation

The desktop app provides the best experience with OS integration, local AI, and offline capabilities.

System Requirements

macOS
Windows
Linux

macOS 11.0 (Big Sur) or later
Apple Silicon (M1/M2/M3) or Intel x64
200 MB disk space
4 GB RAM minimum (8 GB recommended for local AI)

Download and Install

Download Installer

Download the installer for your platform:

macOS
Windows
Linux

Apple Silicon (M1/M2/M3)

curl -L "https://worldmonitor.app/api/download?platform=macos-arm64" -o WorldMonitor.dmg

Intel

curl -L "https://worldmonitor.app/api/download?platform=macos-x64" -o WorldMonitor.dmg

Or visit GitHub Releases and download:

World.Monitor_<version>_aarch64.dmg (Apple Silicon)
World.Monitor_<version>_x64.dmg (Intel)

.exe installer (recommended)

Invoke-WebRequest "https://worldmonitor.app/api/download?platform=windows-exe" -OutFile WorldMonitor-Setup.exe

.msi installer

Invoke-WebRequest "https://worldmonitor.app/api/download?platform=windows-msi" -OutFile WorldMonitor-Setup.msi

Or download from GitHub Releases:

World.Monitor_<version>_x64-setup.exe
World.Monitor_<version>_x64_en-US.msi

AppImage (universal)

curl -L "https://worldmonitor.app/api/download?platform=linux-appimage" -o WorldMonitor.AppImage
chmod +x WorldMonitor.AppImage

Or download from GitHub Releases:

world-monitor_<version>_amd64.AppImage

Install Application

macOS
Windows
Linux

Open the downloaded .dmg file
Drag World Monitor to the Applications folder
Eject the DMG
Open Applications and launch World Monitor

On first launch, macOS may show a security warning:“World Monitor cannot be opened because it is from an unidentified developer.”Solution: Go to System Settings → Privacy & Security and click Open Anyway

Using .exe installer:

Double-click WorldMonitor-Setup.exe
Follow the installation wizard
Choose installation directory (default: C:\Program Files\World Monitor)
Launch from Start Menu or Desktop shortcut

Using .msi installer:

Double-click the .msi file
Follow the MSI installation wizard
Launch from Start Menu

Windows Defender may show a SmartScreen warning:“Windows protected your PC”Solution: Click More info → Run anyway

AppImage (no installation required):

chmod +x WorldMonitor.AppImage
./WorldMonitor.AppImage

Optional: Integrate with desktop environment

# Move to /opt
sudo mv WorldMonitor.AppImage /opt/worldmonitor.appimage

# Create desktop entry
cat > ~/.local/share/applications/worldmonitor.desktop <<EOF
[Desktop Entry]
Name=World Monitor
Exec=/opt/worldmonitor.appimage
Icon=worldmonitor
Type=Application
Categories=Network;News;
EOF

First Launch

On first launch, World Monitor:

Starts the Node.js sidecar on a random port (e.g., http://127.0.0.1:54321)
Generates a unique session token for localhost security
Loads the dashboard with cloud fallback enabled

The sidecar logs are written to:

macOS/Linux: ~/Library/Logs/WorldMonitor/sidecar.log
Windows: %APPDATA%\WorldMonitor\logs\sidecar.log

The app works immediately without configuration. API keys are optional for enhanced features.

Download Variants

Desktop installers are available for all four variants:

World Monitor
Tech Monitor
Finance Monitor

Default geopolitical variant:

# macOS ARM64
curl -L "https://worldmonitor.app/api/download?platform=macos-arm64&variant=full" -o WorldMonitor.dmg

# Windows
curl -L "https://worldmonitor.app/api/download?platform=windows-exe&variant=full" -o WorldMonitor.exe

Tech industry variant:

# macOS ARM64
curl -L "https://worldmonitor.app/api/download?platform=macos-arm64&variant=tech" -o TechMonitor.dmg

# Windows
curl -L "https://worldmonitor.app/api/download?platform=windows-exe&variant=tech" -o TechMonitor.exe

Finance and markets variant:

# macOS ARM64
curl -L "https://worldmonitor.app/api/download?platform=macos-arm64&variant=finance" -o FinanceMonitor.dmg

# Windows
curl -L "https://worldmonitor.app/api/download?platform=windows-exe&variant=finance" -o FinanceMonitor.exe

Web App Installation (PWA)

Install World Monitor as a Progressive Web App for an app-like experience.

Install on Desktop

Chrome/Edge
Safari (macOS)
Firefox

Visit worldmonitor.app
Click the install icon in the address bar (puzzle piece or plus sign)
Click Install in the prompt
Launch from Chrome Apps or Start Menu

Manual installation:

Click ⋮ (three dots) → Install World Monitor
Confirm installation

Install on Mobile

iOS (Safari)
Android (Chrome)

Visit worldmonitor.app in Safari
Tap the Share button (square with arrow)
Scroll down and tap Add to Home Screen
Tap Add
Launch from Home Screen

PWA Features

The PWA provides:

Full-screen standalone mode (no browser UI)
Offline map support (500 tiles cached, 30-day TTL)
Faster startup with aggressive asset caching
Auto-updating service worker (checks every 60 minutes)
Offline fallback page with retry button

The PWA does not support:

Local AI models (Ollama/LM Studio)
OS keychain integration
Local API sidecar

For these features, use the native desktop app.

Self-Hosted Deployment

Deploy your own instance of World Monitor for full control.

Prerequisites

node --version  # v18.0.0 or later
npm --version   # v9.0.0 or later

git clone https://github.com/koala73/worldmonitor.git
cd worldmonitor
npm install

Local Development

Install Dependencies

npm install

Configure Environment

Copy the example environment file:

cp .env.example .env.local

Edit .env.local and add optional API keys:

# AI Summarization
GROQ_API_KEY=your_groq_key_here
OPENROUTER_API_KEY=your_openrouter_key_here

# Caching (Redis)
UPSTASH_REDIS_REST_URL=your_redis_url
UPSTASH_REDIS_REST_TOKEN=your_redis_token

# Conflict Data
ACLED_ACCESS_TOKEN=your_acled_token

# Satellite Fires
NASA_FIRMS_API_KEY=your_firms_key

See Environment Variables for full list.

Start Development Server

Default variant (World Monitor):

npm run dev

Tech variant:

npm run dev:tech

Finance variant:

npm run dev:finance

Open http://localhost:3000 in your browser.

Production Build

Build Static Assets

# Default variant
npm run build

# Tech variant
npm run build:tech

# Finance variant
npm run build:finance

Output: dist/ directory with static HTML, CSS, JS, and assets.

Preview Build

npm run preview

Open http://localhost:4173 to test the production build.

Deploy to Vercel

Install Vercel CLI

npm install -g vercel

Deploy

vercel

Follow the prompts:

Link to existing project or create new
Select deployment region
Configure environment variables

Configure Environment Variables

Add secrets via Vercel dashboard or CLI:

vercel env add GROQ_API_KEY
vercel env add UPSTASH_REDIS_REST_URL
vercel env add UPSTASH_REDIS_REST_TOKEN

See Vercel Deployment for detailed configuration.

Deploy Railway Relay (Optional)

For AIS vessel tracking, OpenSky aircraft data, and Telegram OSINT:

Create Railway Project

Sign up at railway.app
Create new project
Deploy from GitHub repository

Configure Environment Variables

Add to Railway dashboard:

AISSTREAM_API_KEY=your_ais_key
OPENSKY_CLIENT_ID=your_opensky_id
OPENSKY_CLIENT_SECRET=your_opensky_secret
TELEGRAM_API_ID=your_telegram_id
TELEGRAM_API_HASH=your_telegram_hash
TELEGRAM_SESSION=your_session_string
RELAY_SHARED_SECRET=random_secret_here

Update Vercel Environment

Add relay connection in Vercel:

WS_RELAY_URL=https://your-railway-app.railway.app
RELAY_SHARED_SECRET=same_secret_as_railway

Desktop App Development

Build the desktop app from source:

Prerequisites

macOS
Windows
Linux

# Install Xcode Command Line Tools
xcode-select --install

# Install Rust
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

# Install Node.js
brew install node

# Install Rust
winget install Rustlang.Rust.GNU

# Install Node.js
winget install OpenJS.NodeJS

# Install Visual Studio Build Tools
winget install Microsoft.VisualStudio.2022.BuildTools

# Install Rust
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

# Install Node.js
curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
sudo apt-get install -y nodejs

# Install dependencies
sudo apt-get install -y libwebkit2gtk-4.0-dev build-essential curl wget file libssl-dev libgtk-3-dev libayatana-appindicator3-dev librsvg2-dev

Build Commands

# Run in dev mode with DevTools
npm run desktop:dev

# Build for production
npm run desktop:build:full

# Output:
# src-tauri/target/release/bundle/

npm run desktop:build:tech

npm run desktop:build:finance

Package Desktop App

# Build and package for macOS
npm run desktop:package:macos:full

# With code signing
npm run desktop:package:macos:full:sign

# Build and package for Windows
npm run desktop:package:windows:full

# With code signing
npm run desktop:package:windows:full:sign

Verification

Test Installation

Desktop App

Verify the desktop app is working:

Launch app — Should open without errors
Check sidecar — Look for “Sidecar running on port…” in logs
Test API — News feeds and map layers should load
Open Settings — Press Cmd+, (macOS) or Ctrl+, (Windows/Linux)
Check DevTools — Press Cmd+Alt+I (macOS) or Ctrl+Alt+I (Windows/Linux)

If the sidecar fails to start, check logs:

# macOS/Linux
tail -f ~/Library/Logs/WorldMonitor/sidecar.log

# Windows
type %APPDATA%\WorldMonitor\logs\sidecar.log

Web Deployment

Verify your web deployment:

Visit URL — Dashboard should load
Check console — No errors in browser DevTools (F12)
Test API endpoints — /api/earthquake/fdsnws/event/1/query?format=geojson&limit=100
Load news feeds — News panels should populate
Test AI brief — Click “World Brief” badge

Common issues:

CORS errors — Check Vercel environment variables
API timeouts — Increase serverless function timeout
Missing secrets — Add environment variables in Vercel dashboard

Next Steps

Configure API Keys

Enable enhanced features with optional API keys

Local LLM Setup

Run AI models locally with Ollama or LM Studio

Interactive Globe

Learn about 40+ data layers and map controls

Desktop App Features

Explore OS integration and local API sidecar

Get Started

Core Features

Data & Intelligence

Variants

Configuration

Development

Deployment

Installation Overview

Hosted Web App

Desktop Application

Self-Hosted

Desktop Installation

System Requirements

Download and Install

Download Variants

Web App Installation (PWA)

Install on Desktop

Install on Mobile

PWA Features

Self-Hosted Deployment

Prerequisites

Local Development

Production Build

Deploy to Vercel

Deploy Railway Relay (Optional)

Desktop App Development

Prerequisites

Build Commands

Package Desktop App

Verification

Test Installation

Next Steps

Configure API Keys

Local LLM Setup

Interactive Globe

Desktop App Features

​Installation Overview

Hosted Web App

Desktop Application

Self-Hosted

​Desktop Installation

​System Requirements

​Download and Install

​Download Variants

​Web App Installation (PWA)

​Install on Desktop

​Install on Mobile

​PWA Features

​Self-Hosted Deployment

​Prerequisites

​Local Development

​Production Build

​Deploy to Vercel

​Deploy Railway Relay (Optional)

​Desktop App Development

​Prerequisites

​Build Commands

​Package Desktop App

​Verification

​Test Installation

​Next Steps

Configure API Keys

Local LLM Setup

Interactive Globe

Desktop App Features

Installation Overview

Desktop Installation

System Requirements

Download and Install

Download Variants

Web App Installation (PWA)

Install on Desktop

Install on Mobile

PWA Features

Self-Hosted Deployment

Prerequisites

Local Development

Production Build

Deploy to Vercel

Deploy Railway Relay (Optional)

Desktop App Development

Prerequisites

Build Commands

Package Desktop App

Verification

Test Installation

Next Steps