NetWatch: a Rust TUI that turns packet capture into a diagnosis

The problem NetWatch solves, and who it is for

Most terminal network tools answer one question. ss lists sockets, tcpdump prints packets, traceroute maps hops, and each needs its own flags and its own mental model. The README positions NetWatch against that split: one binary, no config, and a single screen that shows interfaces, connections, throughput and a diagnosis together. The stated goal is that `sudo netwatch` gives you live capture with L7 decode, process attribution where the platform allows it, and a diagnostic engine that opens an issue when a learned baseline breaks and closes it when the fix holds.

The audience is narrow and specific. Someone debugging from an SSH session into a Raspberry Pi, a developer who wants to see which process is saturating a link, or a person doing triage on a machine they can reach but cannot instrument with a full agent. The Lite view is sized at 80x24 for exactly that case, and the documentation names an SSH session to a Pi or a tmux split as the use case. If your work happens in a browser-based observability stack, this is not aimed at you.

How the capture, attribution and diagnosis pipeline fits together

The repository layout shows a Rust binary built on ratatui and crossterm for the terminal, tokio for the runtime, and libpcap through the pcap crate for capture. Decoding is split across small libraries: tls-parser for ClientHello and SNI extraction, httparse for HTTP request lines, and rustls with webpki-roots for probes that time a TLS handshake themselves. QUIC Initial decryption appears in the dependency comments as a later phase.

The tabs reveal the data flow. Packets are captured and decoded in tab 4, connections are rolled up per process in tab 2, and the Diagnose tab consumes those objects to produce an issue, a cause, a fix and a verified close, with `report.md` generated from the same objects. Ten tabs cover dashboard, connections, interfaces, packets, stats, topology, timeline, processes, diagnose and egress. The README describes 30 rules behind the diagnosis and a ranked list of causes.

Two design choices stand out. First, the diagnostic engine is stateful: it learns a baseline and then decides when that baseline has broken, which means the first minutes of a session are not representative. Second, the egress tab promotes observed destinations into a policy and alerts on drift, which is a different job from passive capture. Both are documented in the repository's docs directory rather than in the README body, so the README alone will not tell you how a rule fires.

Installing NetWatch and running a first capture

The README lists package-manager installs for macOS and Linux via Homebrew, Windows via Scoop, prebuilt binaries via cargo binstall, Arch via paru, Nix via nix-shell, and conda-forge. Pick whichever matches your machine; the binary is the same.

brew install netwatch                 # macOS / Linux
scoop install netwatch                # Windows (needs Npcap)
cargo binstall netwatch-tui           # prebuilt binary, anywhere with Rust
paru -S netwatch-tui                  # Arch (AUR)
nix-shell -p netwatch                 # NixOS / Nix
conda install -c conda-forge netwatch # conda / mamba (Linux, macOS)

Debian and Ubuntu users add an apt repository instead, which is the path the README documents for those distributions.

curl -fsSL https://matthart1983.github.io/netwatch/apt/netwatch.gpg \
  | sudo tee /usr/share/keyrings/netwatch.gpg >/dev/null
echo "deb [signed-by=/usr/share/keyrings/netwatch.gpg] \
https://matthart1983.github.io/netwatch/apt stable main" \
  | sudo tee /etc/apt/sources.list.d/netwatch.list
sudo apt update && sudo apt install netwatch

Fedora uses a copr repository, and there is a container image for hosts where you would rather not install anything.

docker run --rm -it --net=host --pid=host --cap-add=NET_RAW ghcr.io/matthart1983/netwatch

Once installed, the README gives four ways to start. Plain `netwatch` shows interfaces, connections and config without privileges. `sudo netwatch` enables capture where elevated access is required. `--lite` fits one 80x24 screen, and `--view dense` needs 130x44 or larger.

netwatch              # interfaces, connections, config. No privileges.
sudo netwatch         # enables capture where elevated access is required
netwatch --lite       # one 80x24 screen
netwatch --view dense # four boxes, 130x44 or larger

Inside the TUI, keys `1` through `9` and `0` switch tabs, `V` cycles the three views without a restart, and `?` shows every keybinding. On Linux you can avoid sudo by granting capabilities once, which the README documents with the exact set and points to the reference for when the grant has to be repeated.

sudo setcap 'cap_net_raw,cap_bpf,cap_perfmon+eip' "$(which netwatch)"

Where NetWatch stops: privileges, platforms and blind spots

Elevated access is the first constraint. The README is honest that capture needs it, and the setcap workaround trades a password prompt for a capability grant that has to be reapplied after certain upgrades, which the reference documents rather than the README. On Windows the dependency is Npcap, which is a separate install and a separate licence to review before you ship this to a fleet.

The second constraint is the capability matrix. The repository carries a CAPABILITIES.md that the README links under the heading of platform differences, diagnostic limits and verification scope. That file exists because the same feature set is not available everywhere. The README does not enumerate which tabs degrade on which platform, so you have to read the matrix before assuming the Diagnose tab behaves identically on macOS and Linux.

The third constraint is scope. This is a TUI. The README points to a Prometheus export and a doctor command, but it does not describe a headless daemon or a long-running agent, so a machine you cannot attach a terminal to is a poor fit. The AI commentary in Diagnose is off by default, which is the right default for a tool that reads your traffic, but it also means the feature is not part of the out-of-the-box experience. And the diagnostic engine depends on a learned baseline, so a machine that reboots often, or a network that changes shape every hour, gives it little to learn from.

How NetWatch differs from tcpdump plus Wireshark

The obvious alternative is the pair most engineers already have: tcpdump for capture and Wireshark for dissection. The difference is not decoding quality. Wireshark dissects more protocols than NetWatch will, and the README does not claim otherwise. The difference is where the interpretation happens.

With tcpdump and Wireshark, you capture to a file, move the file, open it, find the stream, and reason about it yourself. NetWatch keeps the capture live, attributes sockets to processes where the platform permits, and hands the result to a rule engine that names an issue and a cause. That is a different trade: less protocol depth, more immediate context. The egress tab goes further in a direction Wireshark does not attempt, by promoting observed destinations into a policy and alerting on drift.

If your problem is a malformed packet or an obscure protocol, reach for Wireshark. If your problem is which process is retransmitting to which host and why the baseline moved, NetWatch is built for that question.

Maintenance, packaging and what the MIT licence leaves you

The last push to the repository was on 2026-09-23, and the most recent release listed is v0.32.3 from 2026-09-20. The version in Cargo.toml matches the release. That is a fast release cadence, and it has a cost: the README links a changelog and a packaging document precisely because the install channel determines what updates you. Homebrew, Scoop, AUR, Nix, conda-forge and the apt repository are all maintained separately, and nothing in the README promises they move in lockstep. If you pin a version, check which channel carries it before you plan an upgrade.

The licence is MIT, stated in both the README badge and Cargo.toml. That is permissive and places few obligations on redistribution beyond preserving the notice, but it also means no warranty and no support commitment. The repository carries a NOTICE file and a SECURITY.md, which is where you would look before deploying this in an environment with compliance requirements. None of this is legal advice; read the LICENSE file yourself.

The maintenance question is not whether the project is alive, since the push date answers that. It is whether the parts you depend on are stable. Deep packet inspection, QUIC decryption and the egress linter are all areas the documentation describes as evolving, and the examples directory contains live capture tests for TLS 1.2, TLS decryption and QUIC, which suggests those paths are exercised but also that they are the ones most likely to change.

Editorial conclusion

Adopt NetWatch if you debug networks from a terminal and want capture, socket attribution and a baseline engine in one binary, and if you accept that deep inspection needs elevated privileges. Do not adopt it if you need a long-term metrics store or a headless agent, since the README describes a TUI and a Prometheus export rather than a daemon. Verify three things first: that your platform appears in the capability matrix, that the doctor command reports capture as available, and that your distribution's update path actually carries the version you installed. The MIT licence lets you fork, but the diagnosis logic, the rules and the platform gaps are the parts you would inherit.

Frequently asked questions

Official sources

1. License: MIT
2. matthart1983/netwatch on GitHub
3. Project website
4. README
5. Releases