Find the layer where your connection breaks. Network Doctor is a cross-platform network troubleshooting TUI that turns interface, DNS, TCP, TLS, HTTP, proxy, and path-MTU checks into one plain-English diagnosis.
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?
- Isolates the failing layer. Independent probes distinguish local-link, DNS, egress, target, TLS, HTTP, proxy, and path-MTU failures, and say so when the evidence stops short of naming one.
- Explains what to do next. Results include evidence and targeted fix hints, with familiar drill-down tools one keypress away.
- Needs no root access. Even the path-MTU check and LAN map use unprivileged sockets and bounded probes.
- Works interactively or in automation. Use the TUI for live investigation,
--watchfor intermittent faults, or stable JSON and exit codes in scripts. - Runs everywhere. The same diagnosis engine supports Linux, macOS, and Windows, with native packages and prebuilt binaries.
If Network Doctor saves you time, you can support its development on GitHub Sponsors.
Runs on Linux, macOS, and Windows. Project = network-doctor; installed binary = netdoc.
Scoop, from own bucket:
scoop bucket add heymaikol https://github.com/heymaikol/scoop-bucket
scoop install network-doctorA release reaches the bucket as soon as it publishes, so scoop update network-doctor picks it up like any other app.
brew install network-doctorThe 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.
Every Linux package installs two commands at the same version: netdoc, and
netdoc-sim, the simulator behind Challenge Mode.
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 arm64Fedora 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-doctorTake 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 # AlpineDownloaded 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.
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@latestCheck 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.
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 reportsA finished run leads with the answer: the verdict, 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 e for the causal explanation, and ? for every shortcut.
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.
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.
Each one gets a sentence here and a complete contract in the reference.
- Service profiles.
--profile githubcomposes ordinary runs into one service-specific check with a single aggregate verdict, and every component keeps its full report. Built-ins:github,ssh,smtp,web. Plans and aggregate rules. - Watch Mode.
--watchre-runs continuously and keeps a bounded incident timeline around each intermittent failure, from the last working state to the recovery. Pressito inspect one,wto save it. Incident reconstruction. - Drill-down tools. When a row is not proof enough, run the real tools as
cancellable streaming jobs, several at once, sanitized before the output hits
your terminal: route, socket, ping, DNS, curl, traceroute, mtr, and nmap are
one keypress each,
vmaps the local private network, andSopens an SSH login. Per-OS commands. - Structured output and exit codes.
--jsonprints one document with stable field names:statusper row, and theverdicta script actually asks about (ok,degraded,dns,network,service,incomplete). Exit0passed,1failed or incomplete,2could not run. Fields, exit codes. - Diagnostic snapshots.
--savewrites a finished run to a portable.ndocfor the failure you cannot reproduce on demand,--supportwrites it pseudonymized for sharing, and--compare good.ndoc bad.ndocreports what changed between two saved runs without opening a socket. Format, support policy, comparison. - Remote and two-machine diagnosis.
--via server hostruns the checks on another machine through your ownsshclient, installing nothing on the far end.--two-sidedasks why one target behaves differently from two vantage points and places the failure on the side where it is specific.--peer-listenand--peer-connectcompare traffic observed at both ends of an authenticated, directly connected TLS 1.3 session, with no relay or account. Remote, two-sided, peer. - Narrowing a run.
--list-checksprints the stable probe IDs that--checkand--skipaccept,--no-reference-egressdrops every check that would contact netdoc's own reference services, and--ifacebinds probe traffic to one interface or address. Flag semantics.
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 youEverything 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 -dailyThe walkthrough is in the wiki's Challenge Mode; the scoring contract is in docs/simulation-challenge.md and the simulator in docs/simulation.md.
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
heymaikol.github.io/network-doctor:
- 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.
The site is built from docs/ and the wiki, so each page is still edited exactly where it lives; nothing is duplicated to publish it.
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.
Read CONTRIBUTING.md for setup, choosing a task, and opening a
pull request. An ordinary change runs ./scripts/check; the complete gate and
what each layer of evidence proves are in
docs/validation.md. Please report suspected
vulnerabilities privately as described in SECURITY.md.
Built with Bubble Tea, Bubbles, and Lip Gloss.
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.
Network Doctor is licensed under the Apache License, Version 2.0. Package metadata declares this as Apache-2.0.