Velocity

A self-hosted live map of aircraft, ships and satellites that records what it sees, so you can rewind to any past moment. No API keys, no account.

git clone https://github.com/AndrewCTF/velocity.git && cd velocity
docker compose up          # then open http://localhost:8080

Why it exists

Free trackers only let you look back a little: Flightradar24 gives 7 days of replay on the free tier, MarineTraffic 24 hours, and ADS-B Exchange dropped its free API. Velocity pulls the same public feeds and writes every position to your own disk, so the history is yours.

Free tiers as of July 2026; each cell is checkable on the vendor's pricing page.

What it does

• Records history. Every position goes into SQLite by default, or Postgres/TimescaleDB if you set HISTORY_PG_DSN. The default keeps a rolling window; set ARCHIVE_MODE=1 to keep everything. A scrubber at the bottom rewinds the map to any moment you recorded.
• Says where each contact came from. Every aircraft and ship shows which feeds reported it, how many agreed, and how old the position is, so a stale fix doesn't look live. /api/status/provenance gives the same per feed.
• Puts more on the same map. GPS jamming, ships with AIS switched off, flight restrictions, military bases, naval warnings, earthquakes, internet outages and conflict events.
• Keeps evidence. Captures get a SHA-256 hash and an append-only custody log, and a case exports to an HTML or PPTX report that cites its sources.
• Talks to AI agents. It runs as an MCP server, so an agent can ask about live traffic instead of guessing. Anything automated is labelled as such.

Quick start · The apps · Take the tour · Query it from an AI agent

Limits

• It's built for one person, not a team.
• Coverage is whatever the public feeds see. It's good over Europe and North America and thin elsewhere; ship data is densest around Northern Europe. The map tells you where coverage is thin.
• Some live state (current incidents, area selections, briefs) clears on restart. History, saved objects, cases and the evidence log stay on disk. See Scope and limits.
• The 3D satellite view needs a lot of GPU memory.

Use at your own risk. No warranty; the authors take no responsibility for how you use this tool or the data it pulls. Velocity pulls from third-party sources that have not authorised it: their terms apply to you, the requests come from your IP, and rate limits, bans and legal exposure are yours. Feeds can be incomplete, delayed or spoofed, and AI summaries can be wrong. Don't use it for navigation, safety-of-life, or anything where being wrong hurts someone. Read DISCLAIMER.md before you run it. Security self-assessments: ISO/IEC 27001:2022 controls, OWASP ASVS 5.0 L2.

Prerequisites

Honestly, not much. There are two ways to run it, pick whichever you're set up for:

• The easy way, with Docker. If you have Docker (24 or newer, with the compose plugin that ships with Docker Desktop), that's the whole list. One command and you're up.
• Running the pieces yourself. If you'd rather not use Docker, you'll need Node 20+, pnpm 9 (corepack enable picks the right version for you), Python 3.12 for the backend, and uv to pull its dependencies. A plain venv works too if you don't have uv.

Either way, you need a browser that can do WebGL2, so any recent Chrome, Edge or Firefox. The globe leans on your GPU, so on a laptop with switchable graphics do yourself a favour and push it onto the discrete card before you judge the frame rate.

And no keys. The core feeds (planes, ships, quakes, satellites, the basemap) all run without a single API key. Keys only ever add reach; see What it pulls in for what each one buys you.

Quick start

Docker is the short road. It brings up the API, the web app and nginx together:

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

Now open http://localhost:8080. It comes up live, planes moving, ships, quakes, the lot, with nothing to configure in between — and position history is already recording to a Docker volume, so it's still there the next time you run docker compose up (set ARCHIVE_MODE=1 in .env for an open-ended archive instead of the default rolling window; see Scope and limits). The first time in, a short tour points out where things live; you can pull it back up whenever from ⚙ Settings.

That dock along the bottom is the archive. Pick a window (1h, 6h, 24h, 3d, 7d), click anywhere on the density strip, and the globe rewinds to that moment; the header swaps from Live to Replay, and one button puts you back. Playback runs at 1x through 3600x. The dated day-picker and the recording since … · GB · fixes ownership chip live in the 2D console at /2d, which reads the same /api/history/coverage archive.

The Play button drives the clock through half-hour tar1090 replay chunks with a 24-entry cache, decoding readsb's 16-byte heatmap entries in a Web Worker and appending each contact's samples to its SampledPositionProperty. Aircraft reach back to 2024 through the public readsb heatmap archives the backend proxies and caches (GET /api/history/upstream/chunk|tracks|coverage); one decoded adsb.lol chunk (2024-06-01 12:00 UTC) held 180 slices of 10 s and 3,953 aircraft tracks over Europe. Vessels have no public equivalent, so they replay only as far back as your own archive goes.

Local (open) mode. The compute-heavy endpoints — the LLM-backed Reports tabs, recon, and OSINT enrichment — fail closed on a keyless box so a public deployment can't be made to spend GPU/credits by an anonymous caller. The dev docker compose up sets ALLOW_UNAUTHENTICATED=1 for you (the stack is loopback-only), so those features work out of the box and the UI shows an open-mode banner. Configure API_KEY or Supabase in .env and real auth takes over (the flag becomes irrelevant). For an internet-facing box use docker-compose.prod.yml, which leaves the flag unset. The globe, replay, evidence capture, and all keyless feeds never needed the flag.

Open it on your phone

The stack listens on 127.0.0.1 only, on purpose: the dev stack runs in open mode, so anything that can reach it can use it. To reach your own instance from your phone, put it on your tailnet instead of your LAN:

tailscale serve --bg 8080   # https://<this-machine>.<your-tailnet>.ts.net

Then add that origin to .env and restart, or the API refuses the new Host header (the DNS-rebinding guard in app/origin_guard.py):

CORS_ORIGINS=http://localhost:8080,https://<this-machine>.<your-tailnet>.ts.net

Only devices signed in to your tailnet can open it. Don't use tailscale funnel, which publishes it to the whole internet. For anything wider than your own devices, run docker-compose.prod.yml with Supabase sign-in configured (docs/security/auth-and-sessions.md); it fails closed without a credential.

make install                                      # pnpm install + api venv
cd apps/api && .venv/bin/uvicorn app.main:app     # backend on :8000
pnpm dev                                          # vite on :5173, proxies /api to localhost:8000

Set API_PROXY_TARGET if the backend isn't on http://127.0.0.1:8000; the dev server proxies /api, /tiles and /ws there, so the browser stays same-origin. (VITE_API_URL is different: it makes the browser call the API directly, cross-origin, and is only for builds with no proxy in front.) API_KEY is for servers, the CLI and the MCP server. Never build it into a hosted web bundle, because anyone who loads the page can read it. Browsers sign in with Supabase instead (docs/security/auth-and-sessions.md).

The apps

Velocity isn't one mega-das