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:

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

API Key Setup:

Go to API keys in Tailscale Admin
Create a new API key
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

Tsflow

Install / Use

README