SKOPIA Field Manual ↩ skopia.watch
[ FIELD MANUAL ]

Run it. Read it. Own it.

Skopia is self-hosted by design — there is no shared instance. This manual takes you from a fresh clone to a running watchtower, and explains what every part of the console does.

01 Overview

Skopia is a real-time, sovereign open-source intelligence dashboard — the open-source Palantir you host and own. It aggregates live flight, maritime, CCTV, seismic, wildfire, cyber and conflict data onto a GPU-accelerated 3D globe, and adds a browser-based recon toolkit and a self-hosted AI investigation agent.

The core idea: the value is the code you run. There is no public instance to sign up for — you deploy your own, and nothing leaves your perimeter unless you explicitly opt in.

Stack Next.js 16 (App Router) · TypeScript 5 · MapLibre GL (WebGL) · Docker standalone. Around 60 API routes across three families: cartographic feeds, osint/* recon, and ai/* analysis.

02 Quick start

For local development. Every core feed is keyless, so you can run it with zero configuration.

# clone and run
git clone https://github.com/NOLAM-CH/skopia.git
cd skopia
npm install
cp .env.example .env.local   # optional — all core feeds are keyless
npm run dev

Open http://localhost:3000. The globe loads immediately and feeds begin populating.

03 Self-hosting

The production target is Docker or a long-running Node server. The image is a multi-stage node:22-alpine standalone build that runs non-root.

git clone https://github.com/NOLAM-CH/skopia.git
cd skopia
cp .env.example .env         # optional
docker compose up -d --build

Set OSIRIS_PORT in .env to change the published host port (the container always listens on 3000 internally).

Deployment target Some routes run well past 30 seconds (e.g. dark-vessel detection fans out over several SAR zones). A serverless host with short function timeouts (default Vercel) is not supported without reworking those routes. Use Docker or a persistent Node process.

04 Configuration

Skopia works with zero API keys — every core feed uses public, keyless sources. Copy .env.example and set only what you need. .env* files are gitignored — never commit secrets.

VariablePurpose
SEARXNG_URLSelf-hosted SearXNG instance for the investigation RAG (default http://localhost:8888)
AGENT_ENDPOINTSLocal LLM endpoint chain host|model,host|model (default: local Ollama)
AI_BASE_URL / AI_MODELOptional opt-in cloud / OpenAI-compatible provider for the analyst routes
DOH_RESOLVERDNS-over-HTTPS resolver for recon (default Quad9 — non-GAFAM)
SCANNER_URL / SCANNER_KEYActive-scan backend (RECON returns 503 without it)
GFW_API_TOKENGlobal Fishing Watch SAR (free, non-commercial) — powers the dark-vessel layer
AIS_API_KEYaisstream.io — live maritime AIS

05 Reading the globe

The main view is a WebGL 3D globe. The left rail groups the layers (Aviation, Maritime, Surveil, Hazard, Threat, Network, Display); toggle a group to show or hide its markers. The legend, bottom-right, decodes colours and icons for whatever is active.

  • The bottom command bar holds the three main actions: Locate (jump to any place), Threat Digest and Sovereign Investigation.
  • The top status strip shows Zulu time, connection state, live feed count and space-weather (Kp index).
  • A day/night terminator tracks real solar position across the sphere.

06 Intelligence layers

Each layer reads public sources server-side (the server's IP is exposed, never the visitor's), except embedded video which the browser loads from the provider.

Aviation
OpenSky / ADS-B
Commercial, private, military and jet traffic, live.
Maritime
aisstream · GFW · OpenSanctions
Ports, chokepoints, live AIS, SAR dark-vessels, OFAC-SDN match.
CCTV
TfL · WSDOT · Caltrans · NYC DOT
Public traffic and city cameras.
Seismic
USGS · ETH Zürich (SED)
Real-time M2.5+ quakes, and blast signatures.
Fires / Hazards
NASA FIRMS · GDACS · EONET
Active hotspots and multi-hazard alerts.
Space
NOAA SWPC · Celestrak
Solar weather and satellite tracks.
Cyber
NVD · abuse.ch
CVE threats and the recon toolkit.
Conflict
ADS-B derivation · SAR
Active zones, GPS-jamming, masked areas.
Sanctions
OpenSanctions (OFAC SDN)
Person / org / vessel SDN search, BTC/ETH tracing.
News / Telegram
broadcasters · t.me/s/<channel>
Curated live streams and public-channel OSINT.

07 Recon toolkit

A browser-based reconnaissance panel for infrastructure investigation. It is passive by default — only the active scan and WHOIS touch a third-party target.

  • DNS-over-HTTPS lookup via a non-GAFAM resolver, plus reverse DNS.
  • WHOIS with an automatic OFAC-SDN cross-check on the result.
  • SSL/TLS inspection, subdomain & tech fingerprinting, IP intelligence.
  • CVE lookup against the NVD.
  • Active scan — rate-limited and SSRF-guarded, returns 503 unless a scanner backend is configured.

08 Threat Digest

One click turns every live incident — conflict, cyber, disaster, malware — into a ranked, sourced situational brief written by your own AI. Bottom-line-up-front, with jump-to-map on any item.

It ranks events by severity and recency, then runs a single synthesis pass through your local LLM. If the model is offline or the feeds are unreachable it says so and refuses — it never invents a summary.

09 Sovereign Investigation

A retrieval-augmented (RAG) investigation agent. It expands your question, retrieves real sources from a self-hosted SearXNG plus curated OSINT feeds, and synthesises a briefing on your local model.

  • Every fact carries a [n] citation to a real retrieved source.
  • Findings are corroborated and labelled indicative — never a single source stated as fact.
  • The briefing is written in English; retrieval still searches in local languages for better source recall.

10 Sovereignty model

Three principles are wired into the defaults, not bolted on:

  • Sovereign by default. The AI runs on a local LLM and a self-hosted SearXNG; no cloud is contacted unless you set the opt-in variables. Fonts are self-hosted, DNS defaults to a non-GAFAM resolver, and there is zero analytics or telemetry.
  • Passive by default. Only the active-scan route and osint/whois emit traffic to a third-party target. Everything else reads public sources server-side. Nothing acts autonomously.
  • Augment the investigator. Output is sourced, corroborated and labelled indicative — the tool sharpens your judgement, it does not replace it.

11 Responsible use

Skopia is an OSINT and reconnaissance tool for defensive, educational and authorized use only. Do not scan or probe infrastructure you do not own or are not authorized to monitor. Review each data source's terms before any commercial deployment — some (e.g. Global Fishing Watch, ip-api.com) carry non-commercial clauses.

License Skopia's additions are AGPL-3.0-or-later. It is a fork of the MIT-licensed simplifaisoul/osiris; that notice is preserved. See the repository for full attribution.