ShadowBroker: a self-hosted OSINT dashboard for aircraft, satellites and seismic data

The aggregation problem ShadowBroker targets

Aircraft positions, ship movements, orbital elements, earthquake readings and radio nodes are all published somewhere. They are not published in the same place. An analyst tracking a single flight, the vessel it meets and the satellite passing overhead currently keeps three browser tabs, two API keys and a spreadsheet. ShadowBroker's stated purpose is to collapse that into one screen. The README describes it as a platform that aggregates real-time, multi-domain OSINT telemetry from 60+ live intelligence feeds into a single map interface, and explicitly frames the project as a visualization layer rather than a new collection capability: it does not introduce new surveillance capabilities, it aggregates and visualizes existing public datasets. The intended audience is named in the same document: analysts, researchers, radio operators. That is a fairly narrow group. Someone who wants to watch one airport's departures will find the layer toggles and the recon sidebar heavier than the task requires.

How the frontend, backend and agent channel fit together

The stack is Next.js and MapLibre GL on the front, FastAPI and Python behind it. The repository layout confirms this split: backend/, frontend/, plus helm/, docs/ and a set of Compose files for different deployment shapes (docker-compose.yml, docker-compose.build.yml, docker-compose.e2e.yml, docker-compose.gitlab.yml, docker-compose.override.yml, docker-compose.participant.yml, docker-compose.relay.yml). The important architectural detail is where outbound requests originate. The README states that sensitive recon and Shodan queries never hit third-party APIs from the browser; they are proxied through the backend with SSRF guards and local-operator auth. The browser calls your own /api/osint/* and /api/tools/shodan/* routes, and the backend makes the outbound call after validation. Recon access uses the same trust model as layer toggles and admin routes. The agent path reuses those backends rather than exposing a separate API: the README describes an HMAC-signed agentic command channel supporting OpenClaw and other agents, with compact cross-layer search through search_telemetry and search_news, and osint_lookup for IP, DNS, WHOIS, sanctions and CVE queries. An agent on that channel can also place pins and control the map. That is a wide grant. Anyone wiring an agent in should treat the HMAC key as equivalent to operator access.

Installing ShadowBroker with Docker Compose and running a first query

The project ships prebuilt images. The header comment in docker-compose.yml names ghcr.io/bigbodycobain/shadowbroker-backend:latest and ghcr.io/bigbodycobain/shadowbroker-frontend:latest as the default registry, with GitLab mirror equivalents documented in the same comment. Configuration starts from the example environment file, which the .env.example header describes as the file to copy to .env before filling in keys.

cp .env.example .env

The Makefile provides wrapper targets. The default target prints help, and the two start targets differ only in bind address: up-local sets BIND=127.0.0.1, while up-lan detects the LAN IP and sets BIND=0.0.0.0 with CORS_ORIGINS pointing at that address on port 3000.

make up-local

The backend container publishes port 8000 by default, bound to ${BIND:-127.0.0.1}, so a local run is not reachable from other hosts unless you deliberately choose the LAN target. Logs and status come from the same Makefile.

make logs
make status

For aircraft telemetry the environment file is blunt about the prerequisite: OpenSky OAuth2 credentials are required for airplane telemetry, and without them the flights layer falls back to ADS-B-only with major gaps in Africa, Asia and Latin America. Fill in OPENSKY_CLIENT_ID and OPENSKY_CLIENT_SECRET before expecting a populated map. Other layers degrade to empty rather than to a partial view. The fishing_activity layer stays empty without GFW_API_TOKEN, and the Windy CCTV layer needs WINDY_API_KEY. Once the containers are up, the first real use is toggling a layer you hold a key for and right-clicking a point, which the README says returns a country dossier, head-of-state lookup and the latest Sentinel-2 image at 10m resolution.

Where the layer model breaks down

Empty layers are the obvious failure mode, and the project handles them by silence. A missing key produces no error banner in the map; the layer simply has nothing to draw, which is easy to misread as a quiet world rather than a misconfigured deployment. The GFW tuning variables in docker-compose.yml hint at the second problem: GFW_EVENTS_PAGE_SIZE defaults to 500, GFW_EVENTS_MAX_PAGES to 10, GFW_EVENTS_LOOKBACK_DAYS to 7 and GFW_EVENTS_TIMEOUT_S to 90. The .env.example comment explains why those caps exist, noting that GFW can return 40k+ global events and the defaults cap the fetch for map paint. Capping is the right call for a browser map, but it means the layer is a sample, not a census. Third, the README states plainly that live OSINT features necessarily make outbound requests to the public data providers you enable or query. Self-hosting removes accounts and product telemetry, not network exposure. Finally, the InfoNet messaging feature carries its own warning: privacy is not guaranteed yet, it is an experimental testnet. If you need a dependable transport, this is not it.

ShadowBroker against running the upstream feeds directly

The realistic alternative is not another dashboard. It is assembling the sources yourself: an ADS-B client against OpenSky, an AIS feed for vessels, Celestrak or similar for orbital data, and USGS for seismic events, each with its own viewer. That approach gives you exact control over polling rates, retention and schema, and it never puts an agent between you and the raw data. It also costs weeks of glue code and leaves you with four interfaces. ShadowBroker's difference is the shared coordinate space and the cross-layer search that only exists because the layers sit in one backend. A second alternative is a hosted OSINT map service. That removes the Docker and key-management burden, but it moves the outbound requests, the retention and the operator keys to someone else's infrastructure, which is the opposite of the design the README argues for. The trade is legible: self-hosting buys you control over where queries originate, and charges you the Compose stack, the provider registrations and the empty-layer debugging.

Licence, upgrade cadence and the cost of staying current

The licence is AGPL-3.0. For anyone running ShadowBroker as an internal dashboard that is unremarkable. For anyone who modifies it and exposes the modified version to users over a network, the AGPL's source-availability condition is the part to read carefully, and that is a question for your own counsel rather than something this article can settle. On maintenance, the last push to main was on 2026-09-10, and the most recent tagged release is v0.9.84 on 2026-08-05, preceded by v0.9.83 on 2026-06-15 and v0.9.82 on 2026-06-09. The version in pyproject.toml is 0.9.84, matching the tag. The upgrade cost is not in pulling a new image; it is in the environment surface. The Compose environment block lists provider keys and tuning values (AIS_API_KEY, OPENSKY_CLIENT_ID, GFW_EVENTS_* , WINDY_API_KEY, ADMIN_KEY, FINNHUB_API_KEY, AIRFRAMES_API_KEY, LTA_ACCOUNT_KEY, and LiveUAMap variables including SHADOWBROKER_ENABLE_LIVEUAMAP_SCRAPER). Every upstream provider that changes its authentication or rate limits lands on you, not on the project. Budget for that, not for the docker pull.

Editorial conclusion

Adopt ShadowBroker if you already hold OpenSky and AIS credentials and want aircraft, maritime and satellite layers on one self-hosted map with a server-side recon panel. Skip it if you need a zero-configuration viewer, or if you are not prepared to run a Docker Compose stack and register for the upstream data providers. Before committing, verify two things: that the flights layer behaves acceptably without OPENSKY_CLIENT_ID, since the environment file states it falls back to ADS-B-only with gaps over Africa, Asia and Latin America, and that the InfoNet testnet's own warning about privacy applies to whatever you intend to send through it.

Frequently asked questions

Official sources

1. BigBodyCobain/Shadowbroker on GitHub
2. Issues
3. License: AGPL-3.0
4. README
5. Releases