v0.1.0

whyreach tells you why one Docker container can't connect to another container or to the host. It shows the proof and the fix, and it changes nothing. Run it yourself as a CLI, or let your AI coding agent use it through MCP.

What's in it

• 14 diagnosis rules for common Docker networking pitfalls: localhost used inside a container, a service listening only on 127.0.0.1, containers on different networks, the wrong port, a published port used between containers, a service that isn't ready yet, host.docker.internal on Linux, a DNS server that doesn't answer, and more. Each has a rule page.
• Evidence from the container's side: Docker's metadata, the listening sockets inside each container, DNS as the container sees it, and a TCP connect from the source. Every finding cites its evidence and comes with a fix. When something can't be checked, whyreach says so instead of guessing.
• Read-only: it never changes your containers, networks, firewall or DNS. Optional probe containers run only if you allow them.
• An MCP server with 4 tools (diagnose_connection, inspect_environment, run_probe, save_report) for Claude Code and other MCP clients. Looking up outside names and connecting to private addresses outside Docker need your approval.
• Shareable reports: whyreach diagnose --report saves a bundle, and reports saved through MCP are always redacted.
• One static binary, with no telemetry and no update checks.

Install

Linux (amd64 or arm64) with Docker Engine. Download the archive for your machine and checksums.txt below, then follow the README's install steps. Container image: ghcr.io/sandstrompl/whyreach:0.1.0.

Each archive and the image have a signed build-provenance attestation:
gh attestation verify whyreach_0.1.0_linux_amd64.tar.gz --repo SandstromPL/whyreach

Platforms

Linux with Docker Engine only. Docker Desktop, macOS and Windows come later.

Benchmark

On 21 lab scenarios with Claude Haiku, an agent with only whyreach's tools and an agent with only a shell each found the right cause in 20, and each missed a different one. whyreach's agent needed a median of 2 tool calls instead of 6, about a third of the tokens and less than half the time. It tried no risky commands, while the shell agent tried 18 (all docker exec, all blocked). Updated after a re-run: in the first run, the agents could see each scenario's name in their folder names. Full results