Skyintel

🚀 VoyageIntel

Unified real-time air, sea, and space tracking with AI-powered queries and an immersive 3D globe.

📌 Evolution: VoyageIntel extends SkyIntel (flight + satellite tracking) with full maritime intelligence — real-time AIS vessel tracking, port monitoring, and sea weather. The original air + space version remains available on the railway branch.

Features

• 🌍 3D Globe — CesiumJS-powered immersive dark globe with real-time flight, vessel, and satellite rendering
• ✈️ Flight Tracking — Live commercial, private, and military aircraft via ADSB.lol global feed
• 🚢 Vessel Tracking — Real-time AIS vessel monitoring worldwide via aisstream.io WebSocket — cargo, tanker, passenger, military, fishing, recreational
• ⚔️ Military Monitoring — Unfiltered military aircraft feed + naval vessel detection — unlike commercial trackers that hide these (FOR EDUCATIONAL PURPOSES ONLY, these are public data)
• 🛰 Satellite Tracking — 6 categories (Space Stations, Military, Weather, Nav, Science, Starlink) via Celestrak + SGP4
• 🚀 ISS Tracking — Real-time position, crew info, pass predictions, and one-click Track ISS
• ⚓ Port Database — ~400 ports worldwide from the World Port Index with spatial queries
• 🌤 Weather — Aviation weather via Open-Meteo + marine weather (waves, swell, sea temp) via Marine API
• 🌍 Geocoding — Google Maps geocoding with SQLite cache for AI-powered location resolution
• 🤖 MCP Server — 25+ tools via FastMCP, streamable HTTP + stdio for Claude Desktop / VS Code / Cursor
• 💬 BYOK AI Chat — Bring your own API key (Claude, OpenAI, Gemini) — keys stored in browser only
• ⚡ SSE Streaming — Server-Sent Events for real-time chat responses with incremental token rendering
• 🛡️ Guardrails — Layered chat safety via system prompt hardening + optional LLM Guard scanners
• 📊 Playground Dashboard — /playground — single pane of glass for system health, guardrail monitoring, and LangFuse analytics
• 🖥 CLI — Full command suite including voyageintel ask, voyageintel vessels, voyageintel ports
• 📈 LangFuse Observability — Optional LLM tracing, token tracking, and latency monitoring with dashboard integration

Quick Start

Install

# Recommended for MCP client integration (Claude Desktop, VS Code, etc.)
pipx install voyageintel

# Or install in a virtual environment
pip install voyageintel

⚠️ pipx vs pip: pipx install puts the voyageintel command on your global PATH — required for MCP clients like Claude Desktop that spawn the process directly. pip install inside a virtual environment only makes the command available when the venv is activated. If you use pip, MCP clients will need the full path to the binary (e.g. /path/to/venv/bin/voyageintel).

To upgrade an existing installation:

pipx upgrade voyageintel
# or
pip install --upgrade voyageintel

Verify

voyageintel --version      # Check installed version
voyageintel --help         # View all commands
voyageintel status         # Check configuration and system status

Run

voyageintel serve

Open http://localhost:9097 for the 3D globe and http://localhost:9097/playground for the observability dashboard.

Configuration

VoyageIntel works out of the box with zero configuration for flight and satellite tracking. API keys enable additional domains:

Create a .env file if needed:

# Server
VI_HOST=0.0.0.0
VI_PORT=9097

# AIS Data (required for maritime vessel tracking)
VI_AISSTREAM_API_KEY=your_key

# AIS Performance
VI_AIS_BATCH_FLUSH_INTERVAL=1.0
VI_AIS_RECONNECT_DELAY=5
VI_VESSEL_PRUNE_HOURS=6

# Cesium Ion (optional — enables terrain layer)
VI_CESIUM_ION_TOKEN=your_token

# Google Maps (optional — enables geocoding)
VI_GOOGLE_MAPS_API_KEY=your_key

# LLM — for CLI 'ask' command (optional, web chat uses browser localStorage)
VI_LLM_PROVIDER=anthropic          # anthropic / openai / google
VI_LLM_API_KEY=sk-ant-...
VI_LLM_MODEL=claude-sonnet-4-20250514

# LangFuse (optional — LLM observability + playground analytics)
VI_LANGFUSE_PUBLIC_KEY=pk-lf-...
VI_LANGFUSE_SECRET_KEY=sk-lf-...
VI_LANGFUSE_HOST=https://cloud.langfuse.com
VI_LANGFUSE_OTEL_HOST=https://cloud.langfuse.com

# Playground (opt-in observability dashboard)
VI_PLAYGROUND_ENABLED=true         # default: true

# Poll intervals
VI_FLIGHT_POLL_INTERVAL=60
VI_SATELLITE_POLL_INTERVAL=3600

Graceful Degradation

VoyageIntel starts with whatever API keys are available. Missing keys disable the corresponding domain — no crashes, no error screens.

Deployment Branches

VoyageIntel uses voyageintel as the default branch. The railway branch contains the original SkyIntel (flights + satellites only).

ADSB.lol Coverage

ADSB.lol is a crowdsourced network of volunteer ADS-B feeders. Coverage is excellent in North America, Europe, and parts of Asia, but sparse in regions with fewer feeders (e.g. central China, much of Africa, central Russia). This is a data availability limitation of the volunteer feeder network, not something that can be resolved in code.

AIS Coverage Limitation

VoyageIntel currently uses terrestrial AIS only, received via aisstream.io's shore-based receiver network. Effective range is approximately 50–70 nautical miles from shore. Mid-ocean vessels are not visible unless they pass within range of a coastal receiver.

Satellite AIS providers (Spire, exactEarth, ORBCOMM) offer global ocean coverage but are not currently integrated. This is a known limitation — satellite AIS integration is a candidate for future development.

Architecture Overview

graph TB
    subgraph External["☁️ External Data Sources"]
        ADSB[ADSB.lol<br/>Flights · Military · Search]
        AIS[aisstream.io<br/>WebSocket · AIS Vessels]
        CT[Celestrak<br/>TLE Satellite Data]
        HEX[hexdb.io<br/>Aircraft Meta · Routes]
        WPI[World Port Index<br/>Static Dataset]
        OM[Open-Meteo<br/>Land + Marine Weather]
        ON[Open Notify<br/>ISS Crew]
        GM[Google Maps<br/>Geocoding API]
        LF[LangFuse Cloud<br/>OTEL Traces · Analytics]
    end

    subgraph Backend["⚙️ Backend · Python · Starlette"]
        direction TB
        subgraph Pollers["Background Pollers + Streams"]
            FP[Flight Poller<br/>60s · ADSB.lol HTTP]
            WS[AIS WebSocket Client<br/>Persistent · aisstream.io<br/>Batched writes 1-2s]
            SP[Satellite Poller<br/>1hr · Celestrak TLEs]
        end
        subgraph Processing["Data Processing"]
            FC[Flight Classifier]
            VC[Vessel Classifier + AIS Parser]
            PROP[SGP4 Propagator · Skyfield]
            GEO[Geocoder + Resolver<br/>Google Maps · Cached]
        end
        SVC[Unified Service Layer<br/>service.py]
        API[REST API<br/>/api/*]
        MCP[MCP Server<br/>FastMCP · /mcp · 25+ tools]
        GW[LLM Gateway<br/>LiteLLM · BYOK · SSE]
        GR[Guardrails<br/>LLM Guard · Optional]
        PG[Playground API<br/>/api/playground/*]
    end

    subgraph Storage["💾 SQLite · WAL Mode"]
        DB[(flights · vessels · satellites<br/>ports · aircraft_meta · geocode_cache<br/>R*Tree indexes)]
    end

    subgraph Frontend["🌍 Unified Web UI · Vanilla JS"]
        GLOBE[CesiumJS Globe<br/>Flights + Vessels + Satellites]
        DETAIL[Detail Panels<br/>Aircraft · Vessel · Satellite]
        CHAT[Chat Panel<br/>Cross-domain · BYOK · SSE]
        DASH[Playground Dashboard<br/>Air + Sea + Space Metrics]
    end

    subgraph Clients["🔌 External Clients"]
        CLI[CLI<br/>voyageintel ask/flights/vessels/iss]
        CD[Claude Desktop<br/>stdio]
        CC[Claude Code<br/>Streamable HTTP]
        VS[VS Code / Cursor<br/>Streamable HTTP]
    end

    ADSB -->|Poll 60s + on-demand| FP
    AIS -->|WebSocket stream| WS
    CT -->|TLE hourly| SP
    HEX -->|Cached lookups| SVC
    WPI -->|Static load| DB
    OM --> SVC
    ON --> SVC
    GM -->|Cached lookups| GEO

    FP --> FC --> DB
    WS --> VC --> DB
    SP --> PROP --> DB

    DB --> API
    DB --> SVC
    ADSB -->|On-demand queries| SVC
    SVC --> MCP
    SVC --> GW
    SVC --> CLI
    SVC --> PG
    GW --> GR
    GW -->|OTEL| LF
    LF -->|REST reads| PG

    API --> GLOBE
    API --> DETAIL
    GW --> CHAT
    PG --> DASH

    MCP --> CD
    MCP --> CC
    MCP --> VS

VoyageIntel is a Python/Starlette backend with a vanilla JS + CesiumJS frontend and no build step. Three background data ingestion processes run concurrently: an HTTP flight poller (ADSB.lol, 60s interval), a persistent WebSocket connection (aisstream.io, real-time AIS stream with batched writes), and an HTTP satellite poller (Celestrak, 1hr interval). All data flows into a single SQLite database with WAL mode — flights are appended and pruned, vessels are upserted by MMSI, and satellite TLEs are refreshed hourly. R*Tree spatial indexes accelerate radius queries for vessels and ports. A unified service layer (service.py) provides cross-domain query logic consumed by four surfaces: the REST API (globe rendering), the MCP server (25+ tools for Claude Desktop / VS Code / Cursor), the LLM gateway (BYOK AI chat with SSE streaming), and the CLI. The LLM gateway (gateway.py) implements a provider-agnostic tool-calling loop via LiteLLM, supporting Claude, OpenAI, and Gemini through a single BYOK interface — with SSE streaming for real-time token delivery. The /playground dashboard provides unified observability across all domains — flight counts, vessel counts by type, satellite cache stats, WebSocket health, polling status, guardrail monitoring, and LangFuse analytics. All flight classification (military, private, commercial) is performed through pattern-based heuristics in the classifier module, vessel classification maps AIS type codes to categories with MMSI-based flag state detection, and satellite positions are computed locally via SGP4 propagation using Skyfield.

Vessel Icon Types

Vessels are rendered on the CesiumJS globe using a BillboardCollection with 9 distinct icon silhouettes, colour-coded by AIS ship type:

ℹ️ AIS ship type codes follow the ITU-R M.1371 standard. Classification logic is in src/voyageintel/vessels/classifier.py. Military vessels are additionally detected by MMSI Maritime Identification Digits for flag state and name pattern matching (USS, HMS, HMAS, etc.).

MCP Client Setup

VoyageIntel exposes 25+ MCP tools via two transports:

ℹ️ The MCP server is currently available for local use only — it is not remotely hosted. You must run voyageintel serve locally, or deploy your own instance.

Claude Desktop ✅ Tested

Claude Desktop uses stdio transport — it spawns voyageintel as a child process.

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

If installed via pipx (recommended):

{
  "mcpServers": {
    "voyageintel": {
      "command": "voyageintel",
      "args": ["serve", "--stdio"]
    }
  }
}

If installed via pip in a virtual environment:

{
  "mcpServers": {
    "voyageintel": {
      "command": "/full/path/to/.venv/bin/voyageintel",
      "args": ["serve", "--stdio"]
    }
  }
}

Find your full path with which voyageintel (macOS/Linux) or where voyageintel (Windows).

After saving, restart Claude Desktop completely (quit and reopen). Look for the 🔌 tools icon — voyageintel should appear with 25+ tools.

Troubleshooting:

• Check logs: cat ~/Library/Logs/Claude/mcp-server-voyageintel.log
• "No such file or directory" → use full path or install via pipx
• "Could not attach" → ensure no other voyageintel serve is running on the same port

Claude Code ✅ Tested

Claude Code uses streamable HTTP transport — it connects to a running VoyageIntel server.

First, start the server:

voyageintel serve

Then register the MCP server:

claude mcp add voyageintel --transport http http://localhost:9097/mcp

Verify:

claude mcp list

Try asking: "What military vessels and aircraft are near the Strait of Hormuz?"

VS Code + GitHub Copilot ✅ Tested

VS Code uses streamable HTTP transport via .vscode/mcp.json.

First, start the server:

voyageintel serve

Then create .vscode/mcp.json in your workspace:

{
  "servers": {
    "voyageintel": {
      "url": "http://localhost:9097/mcp"
    }
  }
}

Verify via Command Palette (Cmd+Shift+P): MCP: List Servers — voyageintel should appear. Use Agent mode in Copilot Chat to access MCP tools.

Try asking: "What cargo vessels are near Singapore right now?"

Cursor ✅ Compatible

Cursor uses the same streamable HTTP transport as VS Code.

Start the server:

voyageintel serve

Add to .cursor/mcp.json:

{
  "servers": {
    "voyageintel": {
      "url": "http://localhost:9097/mcp"
    }
  }
}

Google Maps MCP Companion (Optional)

For directions, places, distance matrix, and elevation — connect Google's official MCP server alongside VoyageIntel:

Claude Desktop:

{
  "mcpServers": {
    "voyageintel": {
      "command": "voyageintel",
      "args": ["serve", "--stdio"]
    },
    "google-maps": {
      "command": "npx",
      "args": ["-y", "@googlemaps/maps-mcp-server"],
      "env": {
        "GOOGLE_MAPS_API_KEY": "your-key"
      }
    }
  }
}

VS Code:

{
  "servers": {
    "voyageintel": {
      "url": "http://localhost:9097/mcp"
    },
    "google-maps": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@googlemaps/maps-mcp-server"],
      "env": {
        "GOOGLE_MAPS_API_KEY": "your-key"
      }
    }
  }
}

Self-Hosted Remote Deployment

If you deploy your own VoyageIntel instance on a cloud platform (e.g. Railway, Render, Fly.io), remote MCP clients can connect to it directly:

VS Code / Cursor:

{
  "servers": {
    "voyageintel": {
      "url": "https://your-deployment-url.example.com/mcp"
    }
  }
}

Claude Code:

claude mcp add voyageintel --transport http https://your-deployment-url.example.com/mcp

Gemini CLI 🔜 Pending

Configuration pending — will be added once Gemini CLI MCP support is verified.

OpenAI Codex 🔜 Pending

Configuration pending — will be added once Codex MCP support is verified.

CLI Helper

Generate MCP config snippets directly:

voyageintel mcp-config              # Claude Desktop (stdio)
voyageintel mcp-config --stdio      # Claude Desktop (stdio, explicit)
voyageintel mcp-config --vscode     # VS Code / Cursor (HTTP)

Available MCP Tools

Air Domain (12 tools)

Sea Domain (10 tools)

Cross-Domain (4 tools)

Architectural Decisions

Guardrails Strategy

VoyageIntel uses a layered defense approach for chat safety:

The heavy PromptInjection scanner (~738MB) and NoRefusal scanner (~827MB) were excluded in favour of system prompt hardening — a deliberate cost/security tradeoff for cloud deployments where memory is billed per GB/hour.

Classification

Aircraft — Detected via ICAO hex ranges, callsign prefixes, squawk codes, and the ADSB.lol /v2/mil feed. Private jets detected via known ICAO type codes. See src/voyageintel/flights/classifier.py.

Vessels — Classified by AIS ship type codes (0–99) mapped to categories (cargo, tanker, passenger, military, fishing, recreational, special, high_speed). Military vessels additionally detected by name patterns (USS, HMS, HMAS, etc.). Flag state derived from MMSI Maritime Identification Digits. See src/voyageintel/vessels/classifier.py.

Data Sources

ℹ️ Dual data architecture: The globe reads from SQLite (polled data), while chat/MCP queries APIs live. This separation isolates polling from on-demand queries — avoids API rate limit contention and ensures globe rendering never competes with user queries.

Playground Dashboard

The /playground route provides an AI engineering observability surface — a single pane of glass for system health, guardrail monitoring, and LangFuse analytics.

System Metrics

• Flights tracked — total with commercial/military/private breakdown (from live poll data)
• Vessels tracked — total with type breakdown (cargo/tanker/passenger/military/fishing/etc.)
• AIS WebSocket — connection status, messages/sec, flush throughput
• Satellites cached — count and categories
• Polling & uptime — poll cycle count, uptime, poll intervals
• Database — SQLite file size, retention policy, path
• Data source health — live status for ADSB.lol, aisstream.io, Celestrak, hexdb.io, Open-Meteo
• LLM configuration — provider, model, API key status, LangFuse status

Guardrails Monitor

• Scan counts — input and output scans performed
• Block rate — blocked count and percentage
• Scanner status — loaded / lazy / unavailable for each scanner
• Recent blocked queries — last 20 blocked inputs (anonymised)
• Gracefully degrades to "available on railway-guardrails branch" when LLM Guard is not installed

LangFuse Analytics

• Chat sessions — total trace count from LangFuse
• Tool call frequency — heatmap of MCP tool usage (in-memory tracking for accuracy)
• Open LangFuse Dashboard — one-click link to the full LangFuse UI
• Gracefully hidden when LangFuse keys are not configured

Auto-refreshes every 15 seconds. Dark theme, card-based grid, fully responsive.

Web UI Guide

• Globe — Rotate, zoom, and pan the 3D globe. Flights, vessels, and satellites render in real-time.
• Navbar dropdown menus — Flights ▾, Satellites ▾, and Vessels ▾ dropdown menus in the navigation bar. Each dropdown contains checkboxes to toggle individual sub-types (e.g. Commercial, Military, Private under Flights; Cargo, Tanker, Passenger, Naval, Fishing, Recreational under Vessels). Use Show All / Hide All buttons at the top of each dropdown for bulk toggling. Click outside the dropdown to close it.
• Click to inspect — Click any flight, vessel, or satellite for a detail panel. Vessel detail panels show identity (name, MMSI, IMO, flag state), motion (speed, heading, course), dimensions, voyage info (destination, ETA, draught), and sea weather at the vessel's position.
• Status bar — Unified domain breakdown across all tracking domains:

  ✈ 9,335 ⚔ 127 🔒 974 | 🚢 8,231 ⚓ 42 🎣 1,890 | 🛰 346 | 🛰 Track ISS
  

• Track ISS — Click the 🛰 Track ISS button in the status bar to rotate the globe to the ISS.
• Layers — Switch between Dark, Satellite, Streets, and Terrain (terrain requires free Cesium Ion token).
• Share — Snapshot your current view and share via URL or Web Share API.
• Chat — Click the 💬 floating button to open the AI chat. Set your API key in ⚙ Settings first. Responses stream in real-time via SSE.
• Playground — Navigate to /playground for system health, guardrail stats, and LangFuse analytics.

💡 Tip: Clear chat history regularly for best performance on complex queries.

CLI Reference

API Reference

Context Management & Rate Limits

VoyageIntel uses a tool-calling architecture where the LLM makes multiple API calls per query. We've implemented several strategies to manage token usage:

• Chat history windowing — Only the last 6 messages are sent to the LLM per request, reducing input tokens while preserving context.
• Result capping — Tool results default to 50 items with total_count always returned, preventing context window blowout.
• Retry with backoff — Rate limit errors trigger automatic retries (up to 3 attempts, 30s/60s waits).
• Dual system prompts — Web chat uses HTML formatting, CLI uses markdown, keeping responses lean per surface.
• SSE streaming — Final LLM response streamed token-by-token via Server-Sent Events for perceived responsiveness.

💡 Tip: Clear chat history before complex queries for best results. Users on free-tier LLM plans should consider lighter models (e.g. claude-haiku-4-20250514, gpt-4o-mini).

Roadmap

Relationship to SkyIntel

VoyageIntel is the evolution of SkyIntel (pip install skyintel, skyintel.dev) — an air + space tracking platform. VoyageIntel is the superset: everything SkyIntel does, plus maritime (AIS vessel tracking, ports, marine weather) and future sub-sea intelligence.

Both projects coexist independently and can run simultaneously.

Contributing

VoyageIntel is open source under the Apache 2.0 license. We welcome contributions:

• 🐛 Bug reports — Open an issue with reproduction steps
• 💡 Feature requests — Suggest ideas via GitHub Issues
• 🔧 Pull requests — Especially welcome in:
  • Maritime data enrichment (vessel photos, classification improvements)
  • Aircraft classifier improvements (see src/voyageintel/flights/classifier.py)
  • Vessel classifier improvements (see src/voyageintel/vessels/classifier.py)
  • Globe rendering performance
  • Additional data sources
  • Test coverage
  • Documentation

Development Setup

git clone https://github.com/0xchamin/skyintel.git
cd skyintel
git checkout voyageintel
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
cp .env.example .env  # Add your API keys
voyageintel serve

Support the Project

If you find VoyageIntel useful, consider supporting its development:

⭐ Star this repo if you find it useful — it helps others discover the project.

Enterprise

Need a managed deployment, custom integrations, SLA support, or additional data sources?

📧 Let's talk — reach out via GitHub Issues or Buy Me a Coffee to start a conversation.

Disclaimer

VoyageIntel is an educational project and technical demonstration showcasing real-time multi-domain data integration, Model Context Protocol (MCP) tool-calling patterns, and AI-powered geospatial intelligence.

All data is sourced from publicly available open APIs — no classified, proprietary, or restricted data is used. Flight positions come from ADSB.lol, vessel positions from aisstream.io, satellite TLEs from Celestrak, ISS data from Open Notify, and weather from Open-Meteo.

• Flight, vessel, and satellite data is provided as-is from third-party sources. Accuracy, completeness, and availability are not guaranteed.
• Military aircraft data is sourced from publicly available ADS-B signals. Not all military aircraft broadcast ADS-B.
• Military vessel detection is based on AIS type codes and name patterns. Many military vessels disable or limit AIS transmission.
• Aircraft classification (military/private/commercial) and vessel classification are based on known patterns and heuristics — for educational purposes only.
• ADSB.lol coverage depends on volunteer ADS-B feeder density — some regions have limited coverage.
• AIS coverage depends on aisstream.io's terrestrial receiver network (~50–70 nm from shore). Mid-ocean vessels are not visible. Satellite AIS is not currently integrated.
• LLM-generated reports and analyses are AI-assisted and should not be used as sole sources for operational, safety, or security decisions.
• BYOK API keys are stored in browser localStorage only — never persisted server-side.

This project is not affiliated with any government, military, or intelligence agency. Aircraft, vessel, and satellite positions shown are approximate and should not be used for navigation, safety-critical decisions, or operational purposes.

License

Apache 2.0 — see LICENSE for details.

Built with ❤️ by 0xchamin