bitmagnet: self-hosted torrent search with a DHT crawler
bitmagnet is a self-hosted BitTorrent indexer with a DHT crawler, Postgres full-text search, a GraphQL API, and Torznab support for the Servarr stack.
TL;DR: bitmagnet builds its own torrent index by crawling the BitTorrent DHT, then stores the metadata in Postgres so you can query it like any other database. It ships with a web UI, a GraphQL API, and a Torznab endpoint that plugs into Prowlarr, Sonarr, and Radarr without a third-party tracker in the middle.
What it is
Most torrent search is a website with a database behind it, and that database is the weak point. bitmagnet takes the opposite route: instead of asking a tracker what it already knows, it joins the distributed hash table that BitTorrent clients use to find peers, listens for the metadata flowing across it, and builds the index itself.
The distinction matters. A DHT crawler only ever sees torrent metadata: the info hash, the file list, the size of each file, and the trackers a client announced. It never touches the payload. The crawler follows the same idea as Magnetico, an earlier open-source project the bitmagnet author credits for the DHT implementation, but wired into a full application with search, a UI, and an API wrapped around it.
Under the hood it is a Go service backed by Postgres, which acts as both the primary data store and the message queue. The search engine is Postgres full-text search rather than a separate search cluster, and the web UI is TypeScript and Angular compiled into the Go binary, so one container serves everything.
What it exposes
Everything sits behind a single HTTP server on port 3333.
| Endpoint | Purpose |
|---|---|
/webui | Main web interface |
/graphql | GraphQL API with a GraphiQL browser |
/torznab/* | Torznab API for Servarr-style clients |
/import | Add existing torrents to the library |
/metrics | Prometheus metrics |
/debug/pprof/* | Go profiling endpoints |
/status | Health check |
Search syntax is Postgres full-text search with a few conveniences layered on top:
- Quoted phrases have to appear in that order, so
"steamboat willie" 1928finds the 1928 short - The
.operator means “followed by”, soapple . orangereturns records with apple before orange - The
|operator is OR, soapple | orangereturns either one
Getting it running
The supported path is Docker Compose, and bitmagnet wants a Postgres instance next to it. This is the minimal setup from the project’s own installation docs.
services:
bitmagnet:
image: ghcr.io/bitmagnet-io/bitmagnet:latest
container_name: bitmagnet
ports:
- "3333:3333"
- "3334:3334/tcp"
- "3334:3334/udp"
restart: unless-stopped
environment:
- POSTGRES_HOST=postgres
- POSTGRES_PASSWORD=postgres
volumes:
- ./config:/root/.config/bitmagnet
command:
- worker
- run
- --keys=http_server
- --keys=queue_server
- --keys=dht_crawler
depends_on:
postgres:
condition: service_healthy
postgres:
image: postgres:16-alpine
container_name: bitmagnet-postgres
volumes:
- ./data/postgres:/var/lib/postgresql/data
restart: unless-stopped
environment:
- POSTGRES_PASSWORD=postgres
- POSTGRES_DB=bitmagnet
- PGUSER=postgres
shm_size: 1g
Port 3333 carries the web UI and the API. Port 3334 over both TCP and UDP is what the DHT crawler uses to talk to peers. The shm_size line gives Postgres 1 GB of shared memory, and the example includes it deliberately, so keep it.
The command block is the part worth understanding. bitmagnet runs as a set of workers, and --keys decides which ones start: http_server serves the UI and API, queue_server runs the import and classifier pipeline, dht_crawler is the crawler itself. Drop that last key and you get a normal indexer over a library you populate yourself.
To see the effective configuration without starting the stack:
bitmagnet config show
Settings live in a config file mounted at /root/.config/bitmagnet, and the same values can come in as environment variables, which is why the compose file above passes Postgres credentials that way.
log:
json: true
tmdb:
api_key: my-api-key
http_server:
cors:
allowed_origins:
- https://example1.com
- https://example2.com
Two options are worth knowing before the first run. tmdb.enabled controls the The Movie Database integration used for classifying content, and dht_crawler.save_files_threshold (default 100) caps how many file entries the crawler stores for any single torrent, which stops multi-file releases from bloating the database.
Connecting the Servarr apps
This is what makes bitmagnet useful to a home media setup. bitmagnet speaks Torznab, so it registers as a “Generic Torznab” indexer in Prowlarr, and Prowlarr then fans it out to Sonarr, Radarr, and the rest of the stack.
If Prowlarr shares a Docker network with bitmagnet, the indexer URL is just the service name on port 3333:
http://bitmagnet:3333/torznab
Add it under Indexers, pick Generic Torznab, paste the URL, and hit Test. No API key and no tracker credentials. If the services live on different networks, point at the host address instead and make sure port 3333 is reachable.
What to watch for
The crawler needs time before it is useful. One early adopter reported under 100 kB/s of combined traffic and roughly 6 percent CPU for the crawler after the first 30 to 60 minutes, and noted that nodes which have only been up for a few days rarely exchange much with each other. An index that looks empty on day one may just be empty on day one.
There is no moderation layer. The index is built from whatever the DHT announces, so junk and mislabelled releases show up next to legitimate ones, and there is no gatekeeper to appeal to. The author said publicly that he wants bitmagnet to be a good citizen and that the app was very much a preview when it launched, but the underlying tradeoff of a decentralized index is that quality control ends up on whoever is searching. Torrents uploaded to private trackers set the private flag, which disables DHT announcements, so they do not appear here.
Operating it is a real systems job rather than a one-command install. It needs Postgres and a Go toolchain, the project depends on Postgres-specific features across both the search engine and the queue, and swapping the database out is explicitly not a priority for the maintainer. The repository is MIT licensed, the last push landed in August 2026, and it sits at roughly 4,400 stars.
Source and Accuracy Notes
- Project page: https://bitmagnet.io/ - verified via direct visit
- Source repository: github.com/bitmagnet-io/bitmagnet - MIT license, Go, verified via GitHub API
- Documentation: bitmagnet.io/setup/installation.html and bitmagnet.io/setup/configuration.html - compose file and config samples taken from the project’s own examples
- HN launch thread: https://news.ycombinator.com/item?id=37777347 - 497 points, October 2023
Related Posts
dev-tools
Bumblebee Go Package Inventory Guide
Review Bumblebee for Go package inventory workflows, including setup, dependency validation, CI adoption, supply-chain use, and report checks.
5/28/2026
dev-tools
AgentMesh – Define AI Agent Teams in YAML
Define multi-agent AI workflows in YAML and run them locally with one command. AgentMesh brings Docker Compose patterns to AI agent orchestration.
5/28/2026
dev-tools
Cicada – FOSS CI/CD That Replaces YAML With a Real Language
Cicada replaces GitHub Actions and GitLab CI YAML configs with a custom functional DSL, letting you write pipelines using variables, functions, and shell.
5/29/2026