PigeonWT 🕊️

Decentralized WebTorrent tracker server using PigeonHub - enabling peer-to-peer file sharing across a mesh network with namespace support.

Features

• 🌐 Decentralized: Built on PigeonHub's mesh networking - no central point of failure
• 📦 Namespace Support: Create isolated tracker networks for different use cases
• 🔗 Cross-Server Connectivity: Peers on different servers can discover and connect to each other
• ⚡ WebRTC: Built on WebTorrent for fast, efficient peer-to-peer transfers
• 🖥️ Web Interface: Simple demo page to test the tracker functionality
• 📊 Stats API: RESTful API for monitoring tracker statistics

Quick Start

Installation

npm install

Running the Server

# Start with default settings (port 8080)
npm start

# Start with custom port
PORT=3000 npm start

# Start with custom bootstrap hubs
BOOTSTRAP_HUBS=wss://hub1.example.com,wss://hub2.example.com npm start

Environment Variables

• PORT - PigeonHub server port (default: 8080)
• HOST - Bind address (default: 0.0.0.0)
• TRACKER_PORT - BitTorrent tracker port (default: 8000)
• BOOTSTRAP_HUBS - Comma-separated list of bootstrap hub URLs

Usage

Web Interface

After starting the server, open your browser to:

• Demo page: http://localhost:8001
• Tracker stats: http://localhost:8000/stats

Tracker URLs

Use these URLs in your WebTorrent client:

• WebSocket: ws://localhost:8000
• HTTP: http://localhost:8000/announce

API Endpoints

• GET /api/namespaces - List all active namespaces
• GET /api/stats/:namespace - Get statistics for a specific namespace

How It Works

PigeonWT combines two powerful technologies:

1. PigeonHub: Provides the mesh networking layer, allowing multiple tracker servers to discover and communicate with each other
2. bittorrent-tracker: Provides the WebTorrent tracker functionality for peer discovery and coordination

When you start multiple PigeonWT servers:

• They automatically discover each other through PigeonHub's mesh network
• Peers can connect to any server and discover peers connected to other servers
• Each namespace is isolated, allowing multiple independent torrent networks

Example: Running Multiple Servers

# Server 1
PORT=8080 TRACKER_PORT=8000 npm start

# Server 2 (in another terminal)
PORT=8081 TRACKER_PORT=8002 npm start

# Server 3 (in another terminal)  
PORT=8082 TRACKER_PORT=8004 npm start

Peers connected to any of these servers will be able to discover and connect to each other!

Development

# Install dependencies
npm install

# Start in development mode
npm run dev

Security

For security considerations and known issues, see SECURITY.md.

Architecture

[PigeonWT Server 1]  ←→  [PigeonWT Server 2]  ←→  [PigeonWT Server 3]
       ↕                        ↕                        ↕
   [Tracker A]              [Tracker B]              [Tracker C]
       ↕                        ↕                        ↕
   [Peer 1,2]               [Peer 3,4]               [Peer 5,6]

Each server runs:

• PigeonHub server for mesh networking
• BitTorrent tracker for peer coordination
• Web server for the demo interface

License

ISC