tailpath

README

Tailpath

Tailpath is a passive, real-time topology and traffic-path viewer for Tailscale networks. It shows which nodes are communicating, how much traffic is flowing, and whether each active path is direct, DERP-relayed, peer-relayed, or unknown.

Tailpath is under active development. The first supported vertical slice is tracked in the roadmap.

中文说明

Principles

• Observe runtime state already maintained by Tailscale.
• Never continuously probe peers to discover paths.
• Model traffic relationships, not ACL reachability.
• Preserve observation provenance and represent missing evidence as unknown.
• Keep topology and traffic data inside the self-hosted deployment.

Planned deployment

The central server runs as a dedicated tsnet node by default. Collectors sample their local tailscaled status every two seconds and only submit traffic samples when non-control peer counters change. The server-owned idle heartbeat defaults to one minute and controls the related freshness windows.

The release artifact is one tailpath binary and one OCI image with server, collector, and healthcheck subcommands. Linux server and collector support is the v0.2 target. The macOS collector is alpha pending real arm64-node validation; the Windows collector is an unverified preview. Server deployment is supported through Linux Compose only.

See deployment for the native collector installers and their platform-specific background-service behavior.

Development

Open the repository in its dev container, then run:

make bootstrap
make check

See development, architecture, and contributing before making changes.

License

Apache-2.0. See LICENSE.