DEV Community

Cover image for I built a BitTorrent client that lives at localhost
Apoorv Darshan
Apoorv Darshan

Posted on

I built a BitTorrent client that lives at localhost

#opensource #go #node #showdev

I wanted the convenience of a browser interface without routing torrent data through a hosted backend or depending entirely on browser-compatible peers.

So I built Hash Harbor: an open-source torrent streamer and downloader whose interface always lives at:

http://localhost:3210
Enter fullscreen mode Exit fullscreen mode

Start it with one command:

npx hash-harbor
Enter fullscreen mode Exit fullscreen mode

The launcher downloads the correct checksum-verified native binary, starts the local engine, and opens the interface in your browser.

Hash Harbor streaming Sintel

Sintel © Blender Foundation — CC BY 3.0.

Why use a native engine?

A browser-only torrent client is limited by browser networking APIs and generally relies on WebRTC-compatible peers or web seeds.

Hash Harbor runs a native Go engine behind its browser interface. This allows it to connect to ordinary BitTorrent peers, trackers, and DHT while keeping the control interface bound to 127.0.0.1.

The architecture is intentionally simple:

Browser interface
       ↓
localhost:3210
       ↓
Native Go torrent engine
       ↓
Trackers, DHT and BitTorrent peers
Enter fullscreen mode Exit fullscreen mode

There is no hosted torrent backend. The engine, settings, and downloaded files stay on your computer.

What it supports

Hash Harbor can:

  • Accept BitTorrent v1 magnet links and info hashes
  • Stream supported video and audio while downloading
  • Seek, pause, control volume, and use fullscreen playback
  • Preview images, text files, and PDFs
  • Download individual files instead of the complete torrent
  • Display peers, speed, progress, metadata, and file information
  • Convert formats such as MKV and AVI for browser playback when FFmpeg is installed
  • Run on macOS, Linux, and Windows across Intel and ARM systems

The localhost port is predictable and configurable. It does not silently move to a random address, so you can bookmark it like a normal local application.

On macOS, it can also run automatically after login:

npx hash-harbor install-service
Enter fullscreen mode Exit fullscreen mode

Other management commands include:

npx hash-harbor status
npx hash-harbor open
npx hash-harbor config --port 3210
npx hash-harbor stop-service
Enter fullscreen mode Exit fullscreen mode

Distribution without bundling every binary into npm

The npm package acts as a small launcher. A tagged release runs the tests and builds six native binaries:

  • macOS Intel and ARM
  • Linux Intel and ARM
  • Windows Intel and ARM

GitHub Actions generates SHA-256 checksums, publishes the binaries through GitHub Releases, and publishes the matching npm launcher version.

When a user runs Hash Harbor, the launcher selects the appropriate binary and verifies its checksum before executing it.

Local does not mean anonymous

Hash Harbor's interface is local, but BitTorrent traffic still travels between your computer and peers. Other peers can see your public IP address.

It is not a VPN or anonymity service. Use it only for files you have permission to download and share, such as open movies, Linux distributions, and other legally distributed content.

Try it 

npx hash-harbor
Enter fullscreen mode Exit fullscreen mode

Hash Harbor is MIT licensed. Contributions, feedback, and GitHub stars are welcome.

Top comments (0)