planesnitch

planesnitch snitches on every interesting aircraft that flies near your locations: military jets, government spooks, emergency squawks, sketchy low-flyers, or whatever you tell it to watch for. It polls free public ADS-B APIs (or your own receiver), matches what it sees against your watchlists, and rats the aircraft out to Telegram or a webhook.

No SDR. No antenna. No hardware. One Docker container and one config file, for as many locations as you want.

public ADS-B APIs, or your own ultrafeeder
  │  one request per location group, merged by ICAO hex
  ▼
aircraft in range
  │  matched against watchlists and alert rules from config.yaml
  │  one cooldown per rule and aircraft
  ▼
Telegram (text, or photo with caption)  and/or  webhook (JSON array per poll)

Quick start

Grab the example config and fill in your location and Telegram bot:

curl -sL \
  https://raw.githubusercontent.com/psyb0t/docker-planesnitch/main/config.yaml.example \
  -o config.yaml

Run it:

docker run -d --name planesnitch \
  -v ./config.yaml:/app/config.yaml:ro \
  psyb0t/planesnitch

The example config also watches the military, government and police lists from plane-alert-db. Those need CSV files mounted at /csv; Getting started has the full walkthrough.

Where to go next

You want to	Read
Go from nothing to your first alert	Getting started
Know every config key and its default	Configuration
Pick what to watch for	Watchlists
Set up Telegram or a webhook, or parse the payload	Notifications
Understand polling, sources, rate limits and cooldowns	How it works
Run it for real: volumes, health check, image tags	Deployment
Know what leaves your machine	Security
Fix something	Troubleshooting
Drive it from an AI agent	Agent integrations
Hack on the code	Development