{"id":51735194,"url":"https://github.com/halaprix/peerpath","last_synced_at":"2026-07-18T06:13:41.643Z","repository":{"id":368416683,"uuid":"1284780607","full_name":"halaprix/peerpath","owner":"halaprix","description":"Read-only diagnostics for Dockerized WireGuard/wg-easy reachability failures.","archived":false,"fork":false,"pushed_at":"2026-06-30T13:56:11.000Z","size":28,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-30T14:15:40.928Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://github.com/halaprix/100-days-100-apps","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/halaprix.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-06-30T07:31:31.000Z","updated_at":"2026-06-30T13:56:15.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/halaprix/peerpath","commit_stats":null,"previous_names":["halaprix/peerpath"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/halaprix/peerpath","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/halaprix%2Fpeerpath","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/halaprix%2Fpeerpath/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/halaprix%2Fpeerpath/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/halaprix%2Fpeerpath/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/halaprix","download_url":"https://codeload.github.com/halaprix/peerpath/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/halaprix%2Fpeerpath/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35607342,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-18T02:00:07.223Z","response_time":61,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-07-18T06:13:40.919Z","updated_at":"2026-07-18T06:13:41.638Z","avatar_url":"https://github.com/halaprix.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# PeerPath\n\nA read-only CLI doctor for Dockerized WireGuard/wg-easy setups that explains why the host, container, and peers can or cannot reach each other, then prints the smallest safe routing/firewall fix.\n\n## Problem\n\nSelf-hosters adopt wg-easy because bare WireGuard is annoying to manage, but host-to-peer and reverse-proxy-to-peer routing still depends on Docker networking, WireGuard peer config, host routes, forwarding sysctls, nftables/iptables state, firewall policy, and wg-easy hooks.\n\nWhen that breaks, users often end up with trial-and-error commands from forum posts or AI chat. Those fixes may be ephemeral, reboot-sensitive, or unsafe.\n\n## Evidence\n\n| Source | Link | Signal |\n|---|---|---|\n| Reddit / r/selfhosted | https://www.reddit.com/r/selfhosted/comments/1ujajsu/how_to_setup_bridge_between_host_and_wgeasy/ | Fresh post: wg-easy container can reach peers, but the host cannot; the user describes AI/trial-and-error iptables fixes as hard to reproduce. |\n| wg-easy | https://github.com/wg-easy/wg-easy | Popular WireGuard + web UI project with Docker-first setup and iptables-sensitive firewall features. |\n| wg-easy docs | https://wg-easy.github.io/wg-easy/latest/examples/tutorials/basic-installation/ | Official basic install is Docker Compose-first. |\n| wg-easy Podman/nftables docs | https://wg-easy.github.io/wg-easy/latest/examples/tutorials/podman-nft/ | Official advanced setup needs capabilities, sysctls, kernel modules, nftables hooks, and restart behavior. |\n| Docker docs | https://docs.docker.com/engine/network/packet-filtering-firewalls/ | Docker creates firewall rules and can set forwarding behavior that surprises router/VPN hosts. |\n| WireGuard quick start | https://www.wireguard.com/quickstart/ | WireGuard exposes routing, peer, keepalive, and `wg show` primitives that can be inspected read-only. |\n\n## Competitor / Substitute Check\n\n| Type | Name / Substitute | Notes |\n|---|---|---|\n| Direct competitor | wg-easy docs and GitHub issues | Authoritative, but not a machine-specific reachability report. |\n| Direct competitor | Netmaker / Tailscale / NetBird-style mesh VPNs | Strong alternatives if the user switches stack; they do not diagnose an existing wg-easy Docker box. |\n| Direct competitor | Docker, WireGuard, nftables, and iptables docs | Correct but low-level and scattered. |\n| Indirect substitute | ChatGPT, forum posts, shell history, copied firewall snippets | Can get lucky; often produces brittle fixes and poor operator understanding. |\n| Status quo | Manual probing inside containers plus ad-hoc routes/firewall rules | Wastes hours and can create outages or accidental exposure. |\n\n## Wedge\n\nPeerPath is a diagnostic adapter, not a VPN platform. It correlates facts from the host, the wg-easy container, peer config, routes, forwarding, and firewall state into a single “why can/can’t this path connect?” report.\n\n## Target user\n\nHomelab/self-hosted operators running wg-easy in Docker or Podman who need reliable host-to-peer, peer-to-host, or reverse-proxy-to-peer connectivity.\n\n## MVP\n\n- `peerpath doctor` read-only report.\n- Fixture mode for demos and CI.\n- Parsers for `docker inspect`, `wg show`, `ip route`, forwarding sysctls, and nft/iptables summaries.\n- Safe connectivity probes for host/container/peer paths.\n- Ranked remediation snippets with risk labels.\n- Markdown/JSON export for support threads and GitHub issues.\n\n## Quickstart\n\n```bash\npython -m pip install -e .\npython -m peerpath fixture list --fixtures-dir tests/fixtures\npython -m peerpath doctor --fixture tests/fixtures/host-missing-route\npython -m peerpath doctor --fixture tests/fixtures/allowedips-mismatch --format json\n```\n\nExample report excerpt:\n\n```text\n### blocking: Host has no specific route to the WireGuard peer CIDR\n\n- ID: `host_missing_route_to_peer_cidr`\n- Confidence: high\n- Safe next check: Inspect the host route table for a specific route to the peer CIDR.\n```\n\nLive host/container collection is not enabled yet. v0.1 alpha only diagnoses synthetic fixtures checked into the repo.\n\n## Non-goals\n\n- No default mutation of firewall, routing, or VPN state.\n- Not a replacement for wg-easy, WireGuard, or mesh VPN platforms.\n- No storage of private VPN keys or secrets.\n- No enterprise VPN management in the first version.\n\n## Safety model\n\nPeerPath v0.1 is read-only. It reports evidence and risk-labeled next checks; it does not mutate routes, firewall rules, Docker networks, or WireGuard state.\n\nCommitted fixtures are synthetic. Local reports may include private route CIDRs because those addresses are diagnostic evidence; do not publish a report until you have reviewed it for hostnames, paths, comments, and secrets.\n\n## Status\n\nv0.1.0-alpha.1 — fixture-driven CLI doctor implemented. Live host/container collection is future work.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhalaprix%2Fpeerpath","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhalaprix%2Fpeerpath","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhalaprix%2Fpeerpath/lists"}