A modern, real-time web application for visualizing and analyzing network traffic flows within Tailscale networks.
Important: TSFlow requires the Tailscale Network Flow Logs feature. This is available on Premium and Enterprise plans and must be enabled in your Tailscale admin console. The application will not show any flow data otherwise.
The fastest way to get started using pre-built images:
Using OAuth (Recommended):
docker run -d \
--name tsflow \
-p 8080:8080 \
-e TAILSCALE_OAUTH_CLIENT_ID=your-client-id \
-e TAILSCALE_OAUTH_CLIENT_SECRET=your-client-secret \
-e TAILSCALE_TAILNET=your-organization \
-e ENVIRONMENT=production \
--restart unless-stopped \
ghcr.io/rajsinghtech/tsflow:latestUsing API Key:
docker run -d \
--name tsflow \
-p 8080:8080 \
-e TAILSCALE_API_KEY=your-api-key \
-e TAILSCALE_TAILNET=your-organization \
-e ENVIRONMENT=production \
--restart unless-stopped \
ghcr.io/rajsinghtech/tsflow:latestNavigate to http://localhost:8080 to access the dashboard.
Go to the Logs tab in your Tailscale Admin Console and ensure that Network Flow Logs are enabled. Note: This requires a Premium or Enterprise plan.
TSFlow supports two authentication methods with Tailscale. You only need to configure one method.
OAuth provides better security through automatic token refresh and fine-grained permissions.
- Go to the OAuth clients page in your Tailscale Admin Console
- Create a new OAuth client
- Copy the Client ID and Client Secret
- Set the following environment variables:
TAILSCALE_OAUTH_CLIENT_ID=your-client-idTAILSCALE_OAUTH_CLIENT_SECRET=your-client-secretTAILSCALE_OAUTH_SCOPES=all:read,devices:read,network-logs:read(optional, defaults toall:read)
- Go to the API keys page in your Tailscale Admin Console
- Create a new API key
- Copy the generated API key (starts with
tskey-api-) - Set
TAILSCALE_API_KEY=your-api-key
- Go to the Settings page in your Tailscale Admin Console
- Your organization name is displayed in the Organization section (used by the Tailscale API)
- Use this exact organization name for the
TAILSCALE_TAILNETvariable
For most users, the default API URL works fine. However, some users may need to use region-specific endpoints:
- Default:
https://api.tailscale.com - US-specific:
https://api.us.tailscale.com
Set TAILSCALE_API_URL=https://api.us.tailscale.com if you need the US-specific endpoint.
| Variable | Description | Required | Default |
|---|---|---|---|
TAILSCALE_TAILNET |
Your organization name | Yes | - |
TAILSCALE_API_URL |
Tailscale API endpoint URL | No | https://api.tailscale.com |
| OAuth Method | |||
TAILSCALE_OAUTH_CLIENT_ID |
OAuth client ID | Yes* | - |
TAILSCALE_OAUTH_CLIENT_SECRET |
OAuth client secret | Yes* | - |
TAILSCALE_OAUTH_SCOPES |
OAuth scopes (comma-separated) | No | all:read |
| API Key Method | |||
TAILSCALE_API_KEY |
Your Tailscale API key | Yes* | - |
| Other | |||
PORT |
Backend server port | No | 8080 |
*Either OAuth credentials OR API key must be provided
Create a docker-compose.yml file:
Using OAuth (Recommended):
services:
tsflow:
image: ghcr.io/rajsinghtech/tsflow:latest
container_name: tsflow
ports:
- "8080:8080"
environment:
- TAILSCALE_OAUTH_CLIENT_ID=your-client-id
- TAILSCALE_OAUTH_CLIENT_SECRET=your-client-secret
- TAILSCALE_TAILNET=your-organization
- PORT=8080
restart: unless-stoppedUsing API Key:
services:
tsflow:
image: ghcr.io/rajsinghtech/tsflow:latest
container_name: tsflow
ports:
- "8080:8080"
environment:
- TAILSCALE_API_KEY=your-api-key
- TAILSCALE_TAILNET=your-organization
- PORT=8080
restart: unless-stoppedCommands:
# Start the application
docker-compose up -d
# View logs
docker-compose logs -f tsflow
# Update to latest version
docker-compose pull && docker-compose up -d
# Stop the application
docker-compose downDeploy TSFlow on Kubernetes using the provided manifests:
git clone https://github.com/rajsinghtech/tsflow.git
cd tsflow/k8s
# Edit kustomization.yaml with your credentials
kubectl apply -k .-
Create the namespace:
kubectl create namespace tailscale
-
Create the secret with your credentials:
kubectl create secret generic tsflow \ --namespace=tailscale \ --from-literal=TAILSCALE_API_KEY="your-api-key" \ --from-literal=TAILSCALE_TAILNET="your-organization"
-
Deploy the application:
kubectl apply -f k8s/deployment.yaml kubectl apply -f k8s/service.yaml kubectl apply -f k8s/httproute.yaml # Optional: Gateway API -
Access the application:
kubectl port-forward -n tailscale svc/tsflow 8080:80
For developers who want to build and run TSFlow locally:
- Go 1.21+ for backend development
- Node.js 18+ and npm for frontend development
-
Clone the repository:
git clone https://github.com/rajsinghtech/tsflow.git cd tsflow -
Set environment variables:
export TAILSCALE_API_KEY=tskey-api-your-api-key-here export TAILSCALE_TAILNET=your-organization-name
-
Build and run the frontend:
cd frontend npm install npm run build cd ..
-
Run the backend:
cd backend go mod download go run main.go -
Development workflow:
# For frontend development with hot reload cd frontend npm run dev # Runs on port 5173 with proxy to backend # For backend development with auto-reload cd backend go install github.com/cosmtrek/air@latest air # Auto-reloads on Go file changes
Example API calls:
# Health check
curl http://localhost:8080/health
# Get devices
curl http://localhost:8080/api/devices
# Get network logs (last 10 minutes)
curl "http://localhost:8080/api/network-logs?start=2024-12-19T10:00:00Z&end=2024-12-19T10:10:00Z"Built with ❤️ for the Tailscale community