Baltic Sea shadow fleet monitoring via live AIS data. Watches 1200+ vessels from the Ukrainian GUR War&Sanctions catalogue against the AISStream WebSocket feed, plots positions on a self-updating map, flags proximity to undersea cables, and detects Russia↔West transshipment patterns.

Free, open source, runs locally. No cloud, no subscription beyond a free AISStream API key.

Part of the Former Lab sovereign intelligence toolchain.

Shadow Fleet Tracker Light is built and maintained by the Former Lab team — sovereign computing, building open, privacy-first tools on old hardware with no VC backing.

If this tool is useful to you, consider supporting on Patreon. A free tier is available, with a 7-day trial on paid tiers. Always support Ukraine!

patreon.com/FormerLab

Supporters get early access to new tools, development updates, and behind-the-scenes posts on how projects like this are built.

git clone https://github.com/FormerLab/shadow-fleet-tracker-light.git
cd shadow-fleet-tracker-light
pip install -r requirements.txt
export AISSTREAM_API_KEY=your_key_here   # free at aisstream.io
python shadow_tracker.py &
uvicorn webserver:app --host 0.0.0.0 --port 8000

Open http://localhost:8000 — the map is at /map.

Windows users: see the Setup section for PowerShell/cmd environment variable syntax.

Linux / macOS users can use start.sh. Windows users can use start.bat or start.ps1 — both open tracker and dashboard in separate windows and launch the browser automatically.

• Connects to the AISStream WebSocket and subscribes to a Baltic Sea bounding box
• Filters the stream against a watchlist of 1200+ vessel MMSIs sourced from the Ukrainian GUR catalogue (Vessels1.db)
• Plots live positions and route trails on a Folium/Leaflet map, refreshed every 3 minutes
• Alerts when a vessel comes within 10 km of a cable segment (from filtered_cables.kml)
• Detects loitering — vessels slow or stationary for 20+ minutes in a fixed area
• Detects transshipment patterns — vessels calling at Russian ports then Western hubs (or vice versa) within 21 days
• Logs all position data to SQLite for offline analysis
• Warm-restarts from the position log — the map is populated immediately on startup with last known positions, no blank-canvas wait
• Serves a FastAPI dashboard for log inspection, vessel analysis, GPX export, transshipment review, and interactive route replay

Dark CartoDB basemap with cable routes overlaid in green. Vessel markers update every 3 minutes with a live countdown to the next refresh — the page auto-reloads. Popups show MMSI, IMO, flag, speed, heading, destination, and deep links to MarineTraffic, VesselFinder, and War&Sanctions. OpenSanctions sanctions status shown if an API key is configured.

Known vessel names from Vessels1.db are shown immediately on first appearance without waiting for an AIS static message.

On startup the map is pre-populated from the last 24 hours of the position log. Vessels not yet seen in the current session are shown as grey markers with a "last seen Xh ago" label — they transition to live colour as new pings arrive.

shadow_tracker.py          Main process — WS consumer, map renderer, DB writes
loitering_module.py        Loitering detection and map annotation
transshipment_module.py    Port call detection and Russia↔West transshipment flagging
webserver.py               FastAPI dashboard
gur_scrape.py              One-shot scraper — builds IMO→GUR-ID mapping + full vessel catalogue
check.py                   Preflight checks — Python version, deps, API key, network
start.sh                   Launcher for Linux / macOS
start.bat                  Launcher for Windows (Command Prompt)
start.ps1                  Launcher for Windows (PowerShell)
requirements.txt           Dependencies

Vessels1.db                Watchlist — 1200+ vessels (MMSI + IMO + name where known)
vessel_data_log.db         Position log — runtime, append-only
vessel_static.db           AIS static data cache (name, destination, flag history)
transshipment.db           Port call log and transshipment events
loitering_events.db        Loitering events
filtered_cables.kml        Baltic Sea undersea cable geometry
cables.kml                 Full cable dataset (pre-filter source)
gur_mapping.json           IMO→GUR-ID mapping (produced by gur_scrape.py, optional)
gur_vessels_full.json      Full GUR catalogue — GUR-ID→{imo, mmsi, name, flag} (produced by gur_scrape.py)

Vessels1.db is the canonical list of tracked vessels. 1200+ entries sourced from the Ukrainian GUR War&Sanctions catalogue, covering tankers and cargo vessels identified as part of the Russian shadow fleet or implicated in Baltic hybrid activity.

The list includes vessels recently seized or intercepted by Baltic authorities:

MMSIs are corrected against current AIS data — shadow fleet vessels reflag frequently. The update_vessels_2026_03.sql file documents all changes with sources.

The watchlist is intentionally open. Add vessels directly to Vessels1.db while the tracker is running — they will be picked up within 5 minutes without a restart.

Linux / macOS:

sqlite3 Vessels1.db "INSERT OR IGNORE INTO vessels (mmsi, imo, name) VALUES ('123456789', '9999999', 'VESSEL NAME');"

Windows (no sqlite3 CLI needed):

import sqlite3
conn = sqlite3.connect("Vessels1.db")
conn.execute("INSERT OR IGNORE INTO vessels (mmsi, imo, name) VALUES ('123456789', '9999999', 'VESSEL NAME')")
conn.commit()
conn.close()

Vessels1.db — watchlist

vessels(mmsi TEXT PK, imo TEXT, name TEXT, destination TEXT)

vessel_data_log.db — position log

vessel_data_log(timestamp, mmsi, name, imo, destination, speed, heading, latitude, longitude, cable_alert)

Append-only. Written on every map render cycle.

vessel_static.db — AIS static data cache

vessel_static(mmsi TEXT PK, name TEXT, imo TEXT, destination TEXT, flag TEXT)
flag_history(id, mmsi, flag, timestamp)

Populated from live ShipStaticData AIS messages. Takes priority over Vessels1.db names once received. flag_history records every flag change with a timestamp — reflagging events are logged and displayed on the per-vessel page.

loitering_events.db — loitering log (created at runtime)

loitering_events(id, mmsi, timestamp, latitude, longitude, near_cable)

transshipment.db — port call and transshipment log (created at runtime)

port_calls(id, mmsi, name, port, port_type, entry_ts, exit_ts, min_speed)
transshipment_events(id, mmsi, name, direction, from_port, from_exit_ts,
                     to_port, to_entry_ts, days_between, detected_ts)

• Python 3.11 or newer — python.org/downloads
• An AISStream API key — free at aisstream.io (register, then copy your key from the dashboard)
• The dependencies in requirements.txt

The easiest way to run the tracker. Each script installs dependencies, runs preflight checks, and launches both processes.

Linux / macOS:

chmod +x start.sh
export AISSTREAM_API_KEY=your_key_here
./start.sh

Windows (PowerShell):

$env:AISSTREAM_API_KEY = "your_key_here"
.\start.ps1

Windows (Command Prompt):

set AISSTREAM_API_KEY=your_key_here
start.bat

All three scripts run check.py first — a preflight that verifies Python version, dependencies, data files, API key, and network reachability, with clear error messages if anything is missing.

You can also run the preflight check on its own at any time:

1. Clone and install dependencies

git clone https://github.com/FormerLab/shadow-fleet-tracker-light.git
cd shadow-fleet-tracker-light
pip install -r requirements.txt

On Ubuntu 22.04+ and Debian 12+ you may get an "externally managed environment" error from pip. The start scripts handle this automatically by creating a virtual environment — just run start.sh and it takes care of it. If installing manually, create a venv first:

python3 -m venv .venv
source .venv/bin/activate   # Linux/macOS
.venv\Scripts\activate      # Windows
pip install -r requirements.txt

2. Set your AISStream API key

Linux / macOS:

export AISSTREAM_API_KEY=your_key_here
export OPENSANCTIONS_API_KEY=your_key_here  # optional

Windows (Command Prompt):

set AISSTREAM_API_KEY=your_key_here
set OPENSANCTIONS_API_KEY=your_key_here

Windows (PowerShell):

$env:AISSTREAM_API_KEY = "your_key_here"
$env:OPENSANCTIONS_API_KEY = "your_key_here"

3. Run the tracker and dashboard as two separate terminals

Terminal 1 — the AIS feed consumer:

Terminal 2 — the web dashboard:

uvicorn webserver:app --host 0.0.0.0 --port 8000

4. Open the dashboard

The live map is at http://localhost:8000/map and updates every 3 minutes. On first run the map renders immediately from any position history already in the database — no blank canvas wait.

python gur_scrape.py --start 1580

python gur_scrape.py --probe 1517