TSFlow - Tailscale Network Flow Visualizer

A real-time network traffic visualization dashboard for Tailscale networks. Monitor device connectivity, analyze bandwidth usage, and explore network flows with an interactive graph interface.

Installation

Homebrew (macOS/Linux)

brew install rajsinghtech/tap/tsflow

Docker

docker pull ghcr.io/rajsinghtech/tsflow:latest

Binary Download

Download from GitHub Releases.

Quick Start

Note: TSFlow requires Tailscale Network Flow Logs (Premium/Enterprise plans). Enable it in your Tailscale admin console.

Run with Homebrew

export TAILSCALE_OAUTH_CLIENT_ID=your-client-id
export TAILSCALE_OAUTH_CLIENT_SECRET=your-client-secret
tsflow

Open http://localhost:8080

Run with Docker

docker run -d \
  --name tsflow \
  -p 8080:8080 \
  -v tsflow_data:/app/data \
  -e TAILSCALE_OAUTH_CLIENT_ID=your-client-id \
  -e TAILSCALE_OAUTH_CLIENT_SECRET=your-client-secret \
  ghcr.io/rajsinghtech/tsflow:latest

Configuration

Authentication

TSFlow supports OAuth (recommended) or API key authentication.

OAuth Setup:

1. Go to OAuth clients in Tailscale Admin
2. Create a new OAuth client with all:read scope
3. Set TAILSCALE_OAUTH_CLIENT_ID and TAILSCALE_OAUTH_CLIENT_SECRET

API Key Setup:

1. Go to API keys in Tailscale Admin
2. Create a new API key
3. Set TAILSCALE_API_KEY

Environment Variables

Tailscale Authentication

Variable	Description	Default
TAILSCALE_OAUTH_CLIENT_ID	OAuth client ID	-
TAILSCALE_OAUTH_CLIENT_SECRET	OAuth client secret	-
TAILSCALE_OAUTH_SCOPES	OAuth scopes (comma-separated)	all:read
TAILSCALE_API_KEY	API key (alternative to OAuth)	-
TAILSCALE_TAILNET	Tailnet name (- for auto-detect)	-
TAILSCALE_API_URL	API endpoint	https://api.tailscale.com

Server Settings

Variable	Description	Default
PORT	Server port	8080
ENVIRONMENT	development or production	development

tsnet Serve Mode

TSFlow can embed a Tailscale node and serve itself directly on your tailnet, eliminating the need for a separate Tailscale sidecar container.

Variable	Description	Default
TSFLOW_SERVE	Enable tsnet serve mode	false
TSFLOW_HOSTNAME	MagicDNS hostname on the tailnet	tsflow
TSFLOW_TAGS	Comma-separated ACL tags (e.g. tag:tsflow)	-
TSFLOW_FUNNEL	Expose via Tailscale Funnel	false
TSFLOW_STATE_DIR	tsnet state persistence directory	./data/tsnet-state

Requirements:

• OAuth credentials (API keys are not supported in tsnet mode)
• ACL tags must be allowed for the OAuth client to register nodes
• For Funnel, the ACL must grant funnel access to the tag

Example:

docker run -d \
  --name tsflow \
  -v tsflow_data:/app/data \
  -e TAILSCALE_OAUTH_CLIENT_ID=your-client-id \
  -e TAILSCALE_OAUTH_CLIENT_SECRET=your-client-secret \
  -e TSFLOW_SERVE=true \
  -e TSFLOW_HOSTNAME=tsflow \
  -e TSFLOW_TAGS=tag:tsflow \
  ghcr.io/rajsinghtech/tsflow:latest

TSFlow will be accessible at https://tsflow.<your-tailnet>.ts.net with automatic HTTPS certificates.

Data Storage & Polling

Variable	Description	Default
TSFLOW_DB_PATH	SQLite database path	./data/tsflow.db
TSFLOW_POLL_INTERVAL	How often to poll Tailscale API for new logs	5m
TSFLOW_INITIAL_BACKFILL	How far back to fetch logs on startup	6h
TSFLOW_RETENTION	How long to keep flow logs	168h (7 days)

Data Storage

TSFlow stores flow logs in SQLite with:

• 7-day retention for raw flow logs (configurable via TSFLOW_RETENTION)

Mount a volume to persist data: -v tsflow_data:/app/data

Development

Setup

git clone https://github.com/rajsinghtech/tsflow.git
cd tsflow

# Install dependencies
cd frontend && npm install && cd ..
cd backend && go mod download && cd ..

Development Mode

Run backend and frontend separately for hot reload:

# Terminal 1: Backend (no embedded frontend)
make dev-backend

# Terminal 2: Frontend with Vite dev server
make dev-frontend

Frontend runs on http://localhost:5173 and proxies /api to backend on :8080.

Production Build

make build
./backend/tsflow

This builds the SvelteKit frontend and embeds it in the Go binary.

Deployment

Docker Compose

services:
  tsflow:
    image: ghcr.io/rajsinghtech/tsflow:latest
    ports:
      - "8080:8080"
    environment:
      - TAILSCALE_OAUTH_CLIENT_ID=${TAILSCALE_OAUTH_CLIENT_ID}
      - TAILSCALE_OAUTH_CLIENT_SECRET=${TAILSCALE_OAUTH_CLIENT_SECRET}
    volumes:
      - tsflow_data:/app/data
    restart: unless-stopped

volumes:
  tsflow_data:

Kubernetes

cd k8s
# Edit kustomization.yaml with your credentials
kubectl apply -k .

Star History

License

MIT

---

Built with ❤️ for the Tailscale community