bitmagnet

bitmagnet is a self‑hosted BitTorrent indexer that leverages the Distributed Hash Table (DHT) to discover and catalog torrent metadata without relying on external trackers or third‑party indexers. By continuously crawling the DHT network, it retrieves info hashes, fetches their corresponding metadata, and enriches each entry with content classification (movies, TV shows, etc.). The result is a searchable index that can be queried through a web UI and a GraphQL API, making it an attractive backend for media‑center stacks such as Servarr (Sonarr/Radarr) and custom automation pipelines.

Key Features

• DHT‑based crawling – Scans the entire DHT for new torrents, ensuring a near‑real‑time feed of content.
• Metadata enrichment – Pulls .torrent files, extracts file lists, and classifies media using fuzzy matching against public datasets.
• GraphQL API – Provides fine‑grained queries for torrents, search results, and classification data.
• Servarr integration – Exposes endpoints that can be consumed by Sonarr, Radarr, Lidarr, and others to auto‑add discovered media.
• Web UI – A lightweight SPA that visualizes the index, supports advanced search, and displays classification scores.

Technical Stack

• Language: Go (Golang) – chosen for its concurrency model, static binaries, and efficient networking.
• Frameworks: Custom lightweight HTTP router; GraphQL server built with graphql-go.
• Database: PostgreSQL (primary store for torrent metadata and classification tables). Optional SQLite support for lightweight deployments.
• DHT Implementation: Uses a community DHT library (bittorrent-go) with extensions for peer‑metadata requests.
• Containerization: Official Docker images are provided; the application exposes a single port for API/UI and can be orchestrated via Kubernetes or Docker Compose.

Core Capabilities

• Real‑time indexing – The crawler runs as a background goroutine, pushing new torrents into the PostgreSQL queue.
• Metadata extraction – Parses .torrent files, extracts tracker lists, piece hashes, and file trees.
• Content classification – Employs a rule‑based engine that matches filenames against known media patterns; returns confidence scores.
• Search API – GraphQL queries support full‑text search, filtering by type (movie/TV), release year, and metadata score.
• Webhook hooks – Exposes POST endpoints for external services to react when new torrents are indexed.

Deployment & Infrastructure

bitmagnet is designed for self‑hosting environments ranging from a single Raspberry Pi to a multi‑node Kubernetes cluster. It requires:

• CPU: 2 cores for the crawler, 1 core for API handling.
• Memory: 4 GiB baseline; scaling with the size of the index (≈10 MiB per 100k torrents).
• Storage: SSD preferred for the PostgreSQL data directory; a separate volume can hold raw .torrent files if desired.
• Networking: Open UDP port 6881 for DHT communication; HTTP/HTTPS ports (default 8080) for API/UI. The Docker image supports environment variables to toggle DHT crawling, set PostgreSQL credentials, and enable TLS.

Integration & Extensibility

Developers can extend bitmagnet through:

• Plugin hooks – The crawler exposes a Go interface that allows custom metadata enrichers to be injected at runtime.
• GraphQL schema extensions – By adding resolver functions, new fields (e.g., subtitle availability) can be exposed without altering the core.
• Webhooks – External services (e.g., media servers, CI pipelines) can subscribe to newTorrent events and trigger downstream actions.
• CLI tools – The binary includes subcommands for manual indexing, database migration, and health checks.

Developer Experience

The project follows idiomatic Go conventions: clear package boundaries, comprehensive unit tests, and a well‑structured README. Documentation is available both in the repository and on the official website, with example GraphQL queries and API usage guides. The community is active on GitHub Discussions and an OpenCollective page, providing quick support for deployment questions. Licensing is permissive (MIT), encouraging commercial or internal use without attribution requirements.

Use Cases

1. Media Center Automation – Integrate with Sonarr/Radarr to automatically discover new releases and trigger downloaders.
2. Research & Analytics – Build a public torrent index for academic studies on peer distribution patterns.
3. Private Torrent Networks – Deploy an internal crawler that indexes only trusted peers, exposing a controlled search API.
4. Continuous Integration – Use the GraphQL endpoint to verify that newly published torrent files contain expected metadata before release.

Advantages

• No external dependencies – Unlike public indexers, bitmagnet relies solely on the DHT, eliminating tracker outages and API rate limits.
• Performance – Go’s lightweight goroutines enable thousands of concurrent DHT lookups with minimal latency.
• Extensibility – The plugin system and open GraphQL schema allow developers to add bespoke enrichment logic or custom search operators.
• Licensing & Control – MIT license and self‑hosting give full control over data retention policies, GDPR compliance, and custom feature development.
• Community‑driven roadmap – Early adopters can influence the direction of the upcoming 1.0 release, ensuring that features align with real