reimap

Watch your machine reach across the internet — in real time.

Windows · macOS · Linux · Android · local-first · no telemetry · extensible via 21 hooks

reimap is a local-first network observability tool. It watches the sockets your computer opens, enriches every remote endpoint with geolocation data, and paints them onto a live, animated world map. Everything runs on your own device: there is no telemetry, no account, and nothing about your traffic ever leaves your machine.

Where a plain connection list tells you that your machine is talking to 140.82.113.25, reimap shows you who, where, and how often — with animated great-circle arcs radiating from your device — and lets you extend every part of that pipeline through a first-class hook system.

Built by Batuhan Ayrıbaş — a Rootcastle project. Licensed under the MIT License.

• Why reimap
• Features
• Screenshots
• How it works
• Installation
• Quick start
• Platforms
• The interface
• Keyboard shortcuts
• GeoIP setup
• The hook system
• Writing a plugin
• Standards & compliance
• Configuration
• Command-line usage
• Development
• Privacy
• Credits & license

Modern applications open dozens of connections you never see. reimap makes that invisible activity legible:

• See the world behind your apps. Every established connection becomes a point on a map, hoverable for the owning process, protocol and status.
• Notice what's new. A rolling history highlights endpoints and countries your machine has never contacted before.
• Stay private by design. GeoIP resolution happens locally against a database you own. reimap never calls home.
• Extend everything. reimap ships an event/filter hook system so you can log, alert, enrich, redact, or export at any stage without patching the core.

Insights	Plugins & Hooks (live inspector)

Daily report	History

Aurora theme	Terminal theme

Android — standalone offline demo (no server, no network):

reimap runs a background scan loop. Each cycle follows a simple pipeline, and every arrow in it is a hook you can tap:

 scan sockets ──▶ FILTER_CONNECTION ──▶ GeoIP lookup ──▶ update store ──▶ insights ──▶ render map
      │                  │                    │               │              │            │
 SCAN_STARTED    (drop / rewrite)      GEOIP_RESOLVED   CONNECTION_NEW  INSIGHTS_    FILTER_MAP_FIGURE
 SCAN_COMPLETED                        GEOIP_UNRESOLVED CONNECTION_CLOSED  UPDATED    UI_MARKER_STYLED

The background thread and the web UI communicate only through thread-safe stores, so a slow render never stalls a scan and a misbehaving plugin never crashes the loop.

reimap targets Python 3.10+.

# from a clone
git clone https://github.com/rootcastleco/reimap.git
cd reimap
pip install -e .

# or with development tooling (tests + linter)
pip install -e ".[dev]"

reimap

reimap starts a scan loop, opens http://127.0.0.1:8050/ in your browser, and begins plotting connections. Without a GeoIP database installed, connections still appear in the Unmapped and Open ports panels; install a database (see below) to place them on the map.

reimap --theme aurora --port 9000 --no-browser

No GeoIP database yet? See it populated instantly with the built-in demo:

reimap --demo          # seeds a curated worldwide dataset, no GeoIP needed

reimap runs everywhere, with official builds produced by CI.

Architecture note. On Android the privileged socket scanning runs on the desktop/server engine (Python); the phone renders — either the bundled offline demo, or a live desktop instance you point it at. This keeps the APK tiny and permission-light.

• Top status bar — live counters: total / mapped / remote / LAN / listening / scans.
• Left menu rail — one button per panel; the active panel is highlighted.
• Right drawer — hosts the active panel and refreshes on its own interval.
• Footer — links to batuhanayribas.com and rootcastle.com.

Panels: Insights, Unmapped, LAN / Local, Open ports, Daily report, History, Plugins & Hooks, GeoIP, Settings, About.

Shortcuts are handled entirely in the browser, so they never round-trip to the server.

reimap never bundles GeoIP data (to stay licence-clean and telemetry-free). Two ways to install it:

1. From the UI. Create a free MaxMind account, generate a licence key, paste it into Settings → MaxMind licence key, and press Update GeoIP. reimap downloads and extracts GeoLite2-City for you.
2. Manually. Drop a GeoLite2-City.mmdb file into reimap's cache directory (shown in the GeoIP panel).

The hook system is what sets reimap apart. There are two flavours:

• Event hooks — fire-and-observe. Subscribers receive a context mapping and their return value is ignored. Example: connection.new, scan.completed.
• Filter hooks — each subscriber receives the running value and returns a (possibly modified) replacement; returning None drops it. Example: filter.connection (drop/rewrite a connection before it is mapped).

Callbacks carry a numeric priority (lower runs first), exceptions are isolated and logged, and the registry is fully introspectable — the Plugins & Hooks panel lists every hook and every active subscriber live.

List every available hook from the CLI:

reimap --list-hooks

See HOOKS.md for the complete reference of all 21 hooks and their context payloads.

A plugin is any Python module exposing register(hooks, runtime). Drop it into <config>/plugins/ (the path is shown in the GeoIP panel) and enable it in the config. Here is a complete plugin that beeps in the log for every connection to a new country:

# ~/.config/reimap/plugins/country_watch.py
from reimap.hooks import HookName

def register(hooks, runtime):
    seen = set()

    @hooks.on(HookName.GEOIP_RESOLVED, name="country_watch", priority=80)
    def _on_resolved(ctx):
        country = ctx["location"].country
        if country and country not in seen:
            seen.add(country)
            print(f"[country_watch] first contact with {country}")

reimap ships five built-in plugins you can copy as starting points:

Enable plugins via the enabled_plugins list in the config file.

reimap is engineered to the discipline of a controlled software project, not just "an app that works." Two industry standards are applied — and documented — in full:

• MIL-STD-498 (Software Development and Documentation). A tailored documentation set lives in docs/mil-std-498/: a Requirements Specification (SRS) with numbered requirements, a Design Description (SDD), a Test Description (STD), a Development Plan (SDP), a Version Description (SVD), and a bidirectional Requirements Traceability Matrix (RTM) linking every requirement → design element → verifying test.
• NASA/JPL "Power of 10" rules for safety-critical code, adapted to Python (docs/mil-std-498/coding-standard.md): bounded loops, boundary assertions, checked return values, minimal-scope state, and a project-specific fail-soft rule — no plugin or hook can ever crash a scan cycle or the server.

Both are enforced continuously: ruff static analysis and the full pytest suite run in CI on Python 3.10, 3.11 and 3.12.

Configuration lives in a JSON file under your platform config directory (reimap / rootcastle). It is created with sensible defaults on first run. Notable keys:

reimap [--host HOST] [--port PORT] [--theme THEME] [--interval SECONDS]
       [--no-browser] [--list-hooks] [--debug] [--version]

pip install -e ".[dev]"
pytest            # run the test suite
ruff check .      # lint

The codebase is organised by responsibility — see ARCHITECTURE.md for the module map and design notes.

reimap is local-first and telemetry-free. See PRIVACY.md for the details of what is (and is not) stored on your machine.

reimap is designed and built by Batuhan Ayrıbaş under the Rootcastle umbrella.

Released under the MIT License. This project is an independent, original implementation inspired by the concept of live socket-to-map visualisation; it shares no source code with any other project.

GeoLite2 data, if you install it, is © MaxMind and subject to MaxMind's own licensing terms.