# TapMap: Real-Time Local Network Activity Map

> TapMap turns local socket activity into an interactive map, application details, and a rolling 30-day history. It suits people who want to see which programs contact remote services without treating the dashboard as a firewall or security suite.

**olalie/tapmap** — Watch your computer connect across the internet in real time. Discover the world behind your apps.

- Repository: https://github.com/olalie/tapmap
- Website: https://olalie.github.io/tapmap/
- Stars: 1,599 · Forks: 89
- Language: Python
- License: MIT
- Published: 2026-10-16 · Updated: 2026-10-16 · Language: en
- Canonical page: https://hysenlabs.com/projects/olalie-tapmap

## TapMap's local socket-to-map pipeline

TapMap addresses a specific visibility gap: a computer opens network connections throughout the day, but the applications, providers, countries, and ports behind those connections are usually hidden. The project is intended for users who want to inspect that activity while keeping the collection process on their own machine. It can expose services contacted by the computer, approximate geographic locations, associated application information, established LAN and LOCAL services, listening TCP ports, and bound UDP ports.

The documented pipeline is compact:

```text
socket scan → IP extraction → GeoIP lookup → map rendering
```

On Windows and Linux, TapMap uses `psutil` to read active network connections. macOS uses `lsof`. TapMap then extracts IP information, performs a GeoIP lookup, and passes the result to a map built with Dash and Plotly. Operating system metadata and verification mechanisms provide application identity and verification status. Technical details available from the `NETWORK` menu can include executable paths, processes, PIDs, signatures, and other local fields.

This is observation rather than interception. The README explicitly calls TapMap an awareness tool, not a firewall or a full security suite. The repository also contains `PRIVACY.md`, `SECURITY.md`, and tests, but the README does not describe the legal or operational boundaries of every local data field. Users handling sensitive systems should read those files before deployment.

The map covers connections observed since TapMap started or its cache was last cleared. This differs from the historical reports, which use a rolling 30-day collection window.

## Installing TapMap on Windows, macOS, and Linux

Desktop packages are available for all three platforms listed in the README. Windows and Linux use downloadable release artifacts, while macOS also has a Homebrew cask. These are desktop installations, so they include the system tray and autostart features. A fresh installation enables `Run TapMap automatically` by default, meaning TapMap starts at login in the background without opening a browser.

On macOS, the documented Homebrew command is:

```bash
brew install --cask tapmap
```

After installation, launch TapMap from Applications. The macOS system tray is called the menu bar. The README warns that Windows SmartScreen can appear when the downloaded installer is opened for the first time; it does not document a signing workaround or a flag for suppressing that warning.

For Windows, download the installer from the Releases page and run it. For Linux, download and install the `.deb` package from the same page. These instructions do not include a universal `tapmap` invocation because the README presents them as desktop package workflows. The packaged application starts a local web server and normally opens the browser automatically.

The source package declares Python `>=3.13` and exposes a `tapmap` script, but the README does not provide a complete source installation and launch procedure. It would be reasonable to inspect `pyproject.toml` and `README.md` in the repository before attempting an unsupported setup path, but no additional install command should be inferred from those declarations.

## Running TapMap with Docker on Linux

The container workflow is limited to a Linux host. TapMap needs host network and PID context to observe the machine's socket and process activity. It also mounts a persistent data directory so local history is not confined to an ephemeral container layer.

Run the published image with the documented settings:

```bash
docker run --rm \
  --network host \
  --pid host \
  -v ~/tapmap-data:/data \
  -e TAPMAP_IN_DOCKER=1 \
  olalie/tapmap:latest
```

The `TAPMAP_IN_DOCKER=1` variable enables the documented Docker mode. The host network and PID settings are operational requirements, not optional conveniences. The mount at `/data` matches the image's `TAPMAP_DATA_DIR=/data` default. The `Dockerfile` sets `TAPMAP_HOST=0.0.0.0` and exposes port `8050`, while `TAPMAP_PORT` remains `8050` unless configured.

Unlike desktop installations, the Docker form does not provide the system tray or autostart. The repository also includes `compose-linux.yml` and a dedicated Docker documentation page, but the README does not show the contents or commands from that page. As a result, no Compose command is included here.

Binding to `0.0.0.0` deserves attention even though TapMap states that collection is local. The provided command does not publish a host port with `-p`; direct browser access may therefore depend on the documented Docker networking behavior. The README says TapMap's normal interface is `http://127.0.0.1:8050/`, but it does not give a separate container exposure example.

## Reading TapMap's map and Technical details

TapMap opens its local Dash server at `http://127.0.0.1:8050/`. Closing the browser does not stop the collector. The desktop version continues in the background and can be reopened or quit through the system tray icon, or the macOS menu bar icon.

The map's primary interaction is marker inspection. Hovering reveals applications using the selected network operator, while clicking opens detailed application information. Technical details are optional and hidden until `Technical details` is enabled in the `NETWORK` menu. At that higher detail level, the interface can show executable paths, processes, PIDs, signatures, and additional fields derived from operating system metadata.

The map also separates categories that are easy to overlook in a list. It includes unmapped public services without available geolocation, established LAN and LOCAL services, local TCP listeners, and UDP-bound sockets. Multiple overlapping connections can expose nearby locations rather than placing every result at an indistinguishable point.

For a first inspection, start TapMap, open the page manually if the browser does not appear, hover over a remote marker, and compare the listed applications with active desktop tasks. Then enable `Technical details` to inspect process and executable fields. This workflow shows why TapMap is more useful than a conventional ping test: it starts from live local sockets and associates them with applications and network operators.

The geolocation is approximate, as stated by the README. It should not be treated as evidence that a specific person or physical machine is at the marker. Likewise, a marker indicates observed network activity, not proof that the remote service is trustworthy.

## TapMap's 30-day history and Significant Connections

TapMap builds a rolling 30-day activity history locally. The `Insights` panel identifies new applications, providers identified by ASN, countries, and ports. It also marks frequent activity using a Top 5+ view, including ties. Selecting a country in Insights zooms the map to that country.

The `Daily Activity Report`, available through the menu or the `D` shortcut, adds application recurrence categories such as seen once, occasional, recurring, and stable. It also provides provider concentration analysis, country activity visualization, and generated activity logs with timelines. These reports depend on continuous collection. The README recommends running TapMap at startup to build a complete history, but it does not state the exact amount of history that can be expected before startup execution.

`Significant Connections`, opened from `INSIGHTS` or with `S`, records new applications, countries, network operators, remote ports, and failed application verification. The interface shows up to 500 recent events. Desktop notifications are enabled by default on Windows, Linux, and macOS and can be changed with `Notifications (N)`.

TapMap can also publish new Significant Connections to MQTT. The README documents only the configuration wizard command:

```bash
tapmap --configure-mqtt
```

The wizard is the documented entry point for broker setup. The README links to separate MQTT documentation but does not state whether event payloads contain stable identifiers, full application metadata, or only the event category. That payload detail must be checked before connecting TapMap to a broker used by other systems.

## TapMap's limits for security and container isolation

The clearest limitation is stated by the project itself: TapMap is not a firewall or a full security suite. It makes connections visible and records patterns, but the documented controls do not include blocking addresses, terminating sessions, or applying policy. Users who need to prevent access rather than observe it need a different control.

The application-to-network association can also be limited by operating system visibility. Windows and Linux use `psutil`; macOS uses `lsof`; Docker depends on host PID visibility. The README does not claim that every process will always be resolved, nor does it document how containers, privileged processes, short-lived sockets, VPNs, proxies, or encrypted tunnels affect attribution. Those are important boundaries for interpreting an empty map entry or an unexpected application name.

GeoIP introduces another limitation. The interface lists unmapped public services when geolocation is missing, so absence from the world map does not necessarily mean absence of traffic. Country markers are approximate, and provider information is not a substitute for DNS ownership, routing, or contractual analysis.

TapMap centers the workflow on application-aware connection metadata, geolocation, map exploration, and 30-day activity summaries. A firewall or network access-control tool takes the opposite approach: it enforces connection policy rather than merely displaying observed activity. The right choice depends on whether the requirement is evidence, mapping, or enforcement.

## TapMap releases, Python requirements, and MIT terms

The repository is not archived. Its last push was on 2026-09-22, and the release list includes `v1.14.2` from 2026-09-22, `v1.14.1` from 2026-09-17, and `v1.14.0` from 2026-09-16. This indicates recent repository and release activity, but it does not establish compatibility with every future operating system update.

Desktop users receive packaged installers or a `.deb` file rather than managing the pinned Python dependencies themselves. Docker builds from `python:3.13-slim`, installs the versions in `requirements.txt`, copies the project, and installs the package. The Python project requires Python `>=3.13`. Upgrade planning should therefore account for both the desktop release artifact and, for source or container work, the pinned dependency set and Python version.

The repository declares the `MIT` license and includes a `LICENSE` file. That designation matters when reviewing distribution, modification, or integration conditions, but this article does not provide legal advice. The actual `LICENSE` file should govern use of the code and bundled assets. The presence of `third_party/` also makes it sensible to inspect component licenses separately rather than assuming every included file is covered by the top-level declaration.

## Conclusion

TapMap is suitable for desktop users who want an explorable record of outbound connections, application identities, remote locations, and recurring network activity. It is not appropriate as the primary control for blocking traffic, investigating malware, or auditing every connection. Before adoption, verify that its local data handling, desktop notifications, autostart behavior, and platform-specific process visibility fit your expectations. On Linux, confirm first that the Docker host mode grants the process visibility TapMap requires.

## FAQ

### Does TapMap send telemetry or host network data in the cloud?

The README says TapMap runs locally and collects all data on the user's machine, with no telemetry. It binds its normal interface to `http://127.0.0.1:8050/`, although the Docker image also sets `TAPMAP_HOST=0.0.0.0`.

### How long does TapMap retain network activity history?

Insights and the Daily Activity Report use a rolling 30-day history. The map itself shows connections observed since TapMap started or its cache was last cleared.

### Can TapMap block connections or replace a firewall?

No. The README explicitly describes TapMap as an awareness tool rather than a firewall or a full security suite. It is intended to expose and explain network activity, not enforce access policy.

## Sources

- [License: MIT](https://github.com/olalie/tapmap/blob/main/LICENSE)
- [olalie/tapmap on GitHub](https://github.com/olalie/tapmap)
- [Project website](https://olalie.github.io/tapmap/)
- [README](https://github.com/olalie/tapmap/blob/main/README.md)
- [Releases](https://github.com/olalie/tapmap/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/olalie-tapmap