self-hosted 6 min read

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.

By
Share: X in
Dark abstract illustration of a decentralized network of glowing nodes feeding into a database cylinder

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.

EndpointPurpose
/webuiMain web interface
/graphqlGraphQL API with a GraphiQL browser
/torznab/*Torznab API for Servarr-style clients
/importAdd existing torrents to the library
/metricsPrometheus metrics
/debug/pprof/*Go profiling endpoints
/statusHealth 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" 1928 finds the 1928 short
  • The . operator means “followed by”, so apple . orange returns records with apple before orange
  • The | operator is OR, so apple | orange returns 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