Network Doctor

!Network Doctor diagnosing an office printer hostname that will not resolve: the DNS row fails, every check that depended on it is skipped, and the verdict names the missing DNS record as the fix

Instead of handing you a wall of ping, dig, and curl output, Network Doctor answers the useful question: **is the problem on my network, along the path, or at the service?**

Why Network Doctor

• Isolates the failing layer. Independent probes distinguish local-link,

• Explains what to do next. Results include evidence and targeted fix hints,

• Needs no root access. Even the path-MTU check and LAN map use unprivileged

• Works interactively or in automation. Use the TUI for live investigation,

• Runs everywhere. The same diagnosis engine supports Linux, macOS, and

Quick start

netdoc                  # local interface, egress, proxy, public DNS, Wi-Fi
netdoc github.com       # DNS, TCP, TLS, HTTP diagnosis of one target
netdoc github.com:22    # the port selects the protocol rows (SSH banner)
netdoc --watch host     # catch intermittent failures
netdoc --json host      # structured report for scripts or bug reports

A finished run leads with the answer in plain language: whether Network Doctor found a problem, which part of the connection it is in, what that means, and what to try first. Under it, marked Technical:, come the diagnosis itself, the fix, the tool worth reaching for next, and the one line of evidence the verdict rests on, above the checks that produced them. Select any other row for its own evidence and fix, press D for a check's complete details, e for the causal explanation, w to save a report you can send to someone who can help, and ? for every shortcut. When the evidence does not establish a cause, the answer says so rather than guessing, and a clean run means no obvious problem was found, not that every application will work.

The recording above is one worked example: an office printer hostname that no longer resolves. The DNS row fails, every check that depended on it is skipped rather than guessed at, and the verdict names the missing DNS record instead of blaming the printer.

Install

Runs on Linux, macOS, and Windows. Project = network-doctor; installed binary = netdoc.

Windows

Scoop, from own bucket:

scoop bucket add heymaikol https://github.com/heymaikol/scoop-bucket
scoop install network-doctor

A release reaches the bucket as soon as it publishes, so scoop update network-doctor picks it up like any other app.

macOS and Linux (Homebrew)

brew install network-doctor

The Homebrew Core formula, bottled for both platforms, so brew upgrade picks up releases like any other formula. It installs netdoc alone; for netdoc-sim too, take a Linux package.

Linux

Every Linux package installs two commands at the same version: netdoc, and netdoc-sim, the simulator behind Challenge Mode.

Fedora

Fedora stable uses the prebuilt release RPM, downloaded from the latest release. It is prebuilt, so the Go-version limitation that prevents COPR source builds on Fedora 43, 44, and 45 does not apply:

sudo dnf install ./network-doctor_X.Y.Z_linux_ARCH.rpm    # ARCH is amd64 or arm64

Fedora Rawhide uses the COPR repository, which builds from source and publishes for Rawhide on x86_64 and aarch64 alone:

sudo dnf copr enable heymaikol/network-doctor
sudo dnf install network-doctor

Other distributions

Take a prebuilt .deb, .rpm, or .apk from the latest release, for amd64 and arm64:

sudo apt install ./network-doctor_X.Y.Z_linux_amd64.deb    # Debian, Ubuntu, Mint
sudo dnf install ./network-doctor_X.Y.Z_linux_amd64.rpm    # RHEL, Rocky, Alma
sudo apk add --allow-untrusted ./network-doctor_X.Y.Z_linux_amd64.apk    # Alpine

Downloaded packages are standalone, so dnf/apt will not pull the next version for you; the COPR repository upgrades normally. Upgrade paths, trust roots, and the netdoc-sim Linux-only rule are in docs/installation.md.

Everywhere else

Grab a prebuilt binary from the latest release (Windows ships as a .zip, the rest as bare binaries), or install with Go 1.27+:

go install github.com/heymaikol/network-doctor/cmd/netdoc@latest

Check what you are running with netdoc --version. Releases carry a signed attestation binding each artifact to the workflow run that built it; verifying one is in docs/installation.md, along with building from a clone.

What it checks

Probes form a dependency graph with independent branches, so an unrelated failure never hides a working one: direct egress, QUIC, proxy egress, public and encrypted DNS, and the selected target path each run on their own, and the unprivileged path-MTU check hangs off the connect.

| Branch | Rows | |---|---| | Local | Interface, Wi-Fi network | | Egress | Internet (TCP egress), QUIC / UDP 443, Internet (env proxy) | | Naming | DNS, DNS (public), DNS (encrypted DoH/DoT) | | Target path | TCP, Path MTU, TLS, HTTP, HTTPS, SSH/SMTP banner |

Each row lands in one of five states, ✓ Pass, ! Warn, ✗ Fail, ⊘ Skip, and – N/A; Warn never counts as a failure. The full probe table with exact pass conditions, JSON causes, and the unprivileged path-MTU method is in docs/reference.md.

Capabilities

Each one gets a sentence here and a complete contract in the reference.

• Service profiles. --profile github composes ordinary runs into one

• Watch Mode. --watch re-runs continuously and keeps a bounded incident

• Drill-down tools. When a row is not proof enough, run the real tools as

• Structured output and exit codes. --json prints one document with stable

• Diagnostic snapshots. --save writes a finished run to a portable .ndoc

• Remote and two-machine diagnosis. --via server host runs the checks on

• Narrowing a run. --list-checks prints the stable probe IDs that --check

Challenge Mode

Challenge Mode drops you into a deliberately broken network without telling you what is wrong, then lets Network Doctor take a shot at the same problem, with both graded against the simulator's independently observed ground truth. There is a daily challenge, and everybody who plays that day gets the same network:

netdoc-sim challenge -daily          # today's, the same one for everybody
netdoc-sim challenge -id V4-8F42C1   # replay the one a friend sent you

Everything is local and reproducible: no account, no server, no leaderboard, and a challenge id is the whole puzzle. The simulator builds its networks out of Linux namespaces, so macOS and Windows run one container image instead:

docker run --rm -it --cap-add SYS_ADMIN ghcr.io/heymaikol/netdoc-sim:latest challenge -daily

The walkthrough is in the wiki's Challenge Mode; the scoring contract is in docs/simulation-challenge.md and the simulator in docs/simulation.md.

Documentation

The wiki is the user-facing hub for how to use netdoc and what a diagnosis means; docs/reference.md is the full technical reference for exact CLI semantics, keybindings, exit codes, and schemas. Both are published at networkdoctor.dev:

• Getting Started: install, first run, and what the screen is showing you.
• Understanding Your Diagnosis: turning a verdict into a next action, including telling "my network" and "their service" apart.
• How Network Doctor Works: why the probe branches are independent, and how path MTU is measured without root.
• Troubleshooting and FAQ: the rows that behave surprisingly, and the questions that come up most.
• Reference, installation details, and the simulator guide: the same docs/ files that live beside the code.

Contributing

Network Doctor actively welcomes external contributors, and many contributions need no networking expertise. Useful work includes Go and Bubble Tea / TUI development, Bash, Zsh, and Fish completions, CI / packaging / release tooling, documentation, Linux / macOS / Windows testing, and real-network field testing.

• Good first issues
• Help wanted issues

Built with Bubble Tea, Bubbles, and Lip Gloss.

Support

Personal Network Diagnosis. Still stuck after running Network Doctor? I offer a paid personal diagnosis for one networking problem. Send a description, relevant context, and a sanitized report created locally with netdoc --support support.ndoc example.com. I investigate the evidence and send a written diagnosis of the likely cause, concrete steps to try next, and one follow-up reply. The introductory price is **$25 USD as a one-time payment, limited to the first 5 cases**. This is diagnostic assistance, not a guarantee of repair. Network Doctor does not upload the file.

GitHub Sponsors. Network Doctor is free software maintained independently. If it saves you time, you can sponsor its development. Your support helps fund the time spent on cross-platform testing, packaging, releases, and ongoing maintenance. Sponsorship is optional and does not affect access to the software or how issues are prioritized.

License

Network Doctor is licensed under the Apache License, Version 2.0. Package metadata declares this as Apache-2.0.

Star History