Velocity

[!WARNING]
Superseded by v1.0.1 — do not run this tag.
It records an archive whose write-ahead log grows without bound (49.6 GB against
15.2 GB of data on the box it was found on). Left recording, it fills the disk.
Fixed in v1.0.1; nothing to migrate.

Velocity is a self-hosted situation console. It pulls live aircraft, ships,
satellites, earthquakes, GPS jamming, dark vessels, restricted airspace, naval
warnings, outages and conflict events onto one 3D globe, correlates them on the
server, and keeps the position history on your own disk for as long as you give
it room.

This is the first tagged release. The project has been running daily against
live feeds since June; v1.0.0 marks the point where a stranger can clone it,
run one command, and get the same picture without asking anyone for a key.

Why this exists

Commercial trackers gate the part that matters. Flightradar24 gates replay at 7
days on the free tier, MarineTraffic cut its free history window to 24 hours,
and ADS-B Exchange killed its free API tier outright. A self-hosted tool does
not have that problem: turn on the archive profile and Velocity records position
history to your disk until the disk budget you set runs out. Nobody can
retroactively shorten your window.

What's in the box

• Live fusion globe — a snapshot measured at 12,647 aircraft (0.5 s old) and
  57,420 vessels while writing this, the vessels MMSI-deduped across four
  keyless sources. About 32,000 of those vessels are moored or parked and
  long-retained, so the moving picture is nearer 25,000. Satellites are
  propagated client-side with real SGP4, not faked motion. Category icons and
  per-entity dossiers, not dots.
• Replay you own — a disk-backed SQLite archive with a timeline scrubber.
  48-hour rolling window by default, or an open-ended disk-budgeted archive.
• An investigation layer — a local ontology (objects, assertions with
  provenance, situations, case files), an evidence locker that hashes at
  capture, and case-to-report export.
• A watch officer — an autonomous pass over the live picture that promotes
  correlated events into incidents with cited reasoning.
• Workflows and Foundry — bring your own datasets, transforms and builds;
  wire live feeds through Python and SQL blocks into alerts.
• Keyless alerting — geofence and watch-list rules firing to Discord or a
  generic webhook, server-side, with no browser open.
• An MCP server — query the live console from an AI agent.

Keyless by default

ADS-B grid, Baltic AIS, MyShipTracking, ShipXplorer, USGS earthquakes, the
Carto basemap and CelesTrak all work with no API key. FIRMS degrades gracefully
without one. Keys are optional everywhere they appear.

Quick start

git clone https://github.com/AndrewCTF/velocity.git
cd velocity
cp .env.example .env       # optional, leave it empty and it still works
docker compose up          # api + web + nginx on :8080

Scope and limits

Read these before you get excited. It is a single-analyst tool, not a team
platform. Live derived state (the current incident list, AOI selections,
watch-officer briefs) lives in memory and clears on restart; what you
deliberately keep is durable — the position archive, the local ontology, and
the evidence locker. There is no facial recognition and there never will be.
AI-drafted prose is labeled as such wherever it reaches a document.

1,719 backend tests pass at this tag, most of them pinning hard-won invariants
about upstream feed behaviour that each regressed at least once.

AGPL-3.0.