# jpillora/cloud-torrent: a self-hosted remote torrent client in a single Go binary

> Cloud Torrent runs a web UI on your own server, downloads torrents to local disk, and serves the resulting files over HTTP. It is a small, single-binary tool for people who want a remote download box rather than a desktop client.

**jpillora/cloud-torrent** — ☁️ Cloud Torrent: a self-hosted remote torrent client

- Repository: https://github.com/jpillora/cloud-torrent
- Stars: 6,247 · Forks: 1,813
- Language: Go
- License: AGPL-3.0
- Published: 2026-09-28 · Updated: 2026-09-28 · Language: en
- Canonical page: https://hysenlabs.com/projects/jpillora-cloud-torrent

## The problem Cloud Torrent solves, and who it is for

A desktop torrent client ties downloads to the machine you sit at. If you want files to arrive on a server with a fast connection and stay there, you either leave a laptop running or you hand the job to a third-party service. Cloud Torrent takes the first option and removes the GUI: the README describes it as a self-hosted remote torrent client written in Go, where you start torrents remotely and they are downloaded as sets of files on the local disk of the server, which are then retrievable or streamable via HTTP.

The audience is narrow and specific. It suits someone with a VPS or a home server who wants a browser tab as the control surface, and who is comfortable running a long-lived process that writes to disk. The README's own VPS walkthrough targets Digital Ocean and Vultr droplets, and the Docker example uses a server-side directory mounted at /downloads. This is not a client for someone who wants a polished desktop experience with per-file prioritisation, or for someone who wants to hand a magnet link to a hosted service and forget it. The value here is that the download happens on hardware you control, and the output is reachable over HTTP without a second step.

## What the repository layout says about the architecture

The top-level entries are main.go, engine/, server/, static/, go.mod, and go.sum. That split is the clearest statement of the design: a single entry point, an engine package, a server package, and a static front end. The front end is not a separate build pipeline in the repository listing, so the web UI is shipped alongside the Go binary rather than compiled from a JavaScript project at install time.

The dependency list fills in the mechanism. github.com/anacrolix/torrent v1.59.1 is the BitTorrent implementation, so Cloud Torrent is a front end and process manager around an existing Go torrent library rather than a from-scratch protocol implementation. github.com/jpillora/velox v0.4.2 is the real-time update layer behind the "Real-time updates" feature: the browser is not polling a JSON endpoint on a timer, it holds a live connection. github.com/jpillora/scraper v0.3.0 backs the embedded torrent search. github.com/jpillora/cookieauth v1.1.1, together with the --auth flag, is how the optional basic auth is enforced. github.com/shirou/gopsutil/v3 v3.24.5 supplies host statistics, which is why the UI can show machine-level numbers alongside torrent state. github.com/jpillora/archive and github.com/NYTimes/gziphandler handle packaging and compression of what the content server returns.

The data flow follows from that. You submit a magnet link or a torrent file through the browser. The engine hands it to anacrolix/torrent, which writes pieces to disk under the configured download directory. The server package reads those files back and serves them over HTTP, and velox pushes progress updates to the open page. Nothing is uploaded to a third party, and there is no account layer in between.

## Installing Cloud Torrent and starting a first download

The README gives three install paths: a release binary, Docker, and a build from source. The binary path uses a shell installer hosted on the author's domain. The README shows it as a one-liner that pipes into bash, which means you are executing a remote script rather than downloading a verified artifact by hand. If that matters to you, take the release asset instead.

```bash
curl https://i.jpillora.com/cloud-torrent! | bash
```

Docker is the shorter route and the one the README uses for its VPS walkthrough. The published image is jpillora/cloud-torrent, and the example maps port 3000 and mounts a host directory at /downloads so the downloaded files outlive the container.

```bash
docker run -d -p 3000:3000 -v /path/to/my/downloads:/downloads jpillora/cloud-torrent
```

After that, the UI is at http://localhost:3000/ by default. The README's VPS example uses a different port and adds a restart policy, which is the more realistic production shape:

```bash
docker run --name ct -d -p 63000:63000 \
  --restart always \
  -v /root/downloads:/downloads \
  jpillora/cloud-torrent --port 63000
```

The --port flag is the listening port, defaulting to 3000, and the README notes it can also be set through the PORT environment variable. Once the page loads, you paste a magnet link or upload a torrent file, and the download appears in the list with live progress. When it finishes, the files are on the host disk at the mounted path and are also reachable through the built-in content server, which the README describes as a fast content server built on Go's net/http ServeContent. That streaming path is the reason to run this rather than a plain BitTorrent daemon: you can start watching a file over HTTP while the rest of it is still arriving.

From source, Go is required, and the README gives a single go get command:

```bash
go get -v github.com/jpillora/cloud-torrent
```

The full flag set is short. The README lists --title, --port, --host, --auth, --config-path, --key-path, --cert-path, --log, and --open. The --auth flag takes a value in the form 'user:password', and the README notes it can be supplied through the AUTH environment variable instead, which is the better choice on a container platform where command lines end up in process listings.

## Where Cloud Torrent is the wrong tool

The most important limitation is stated by the project itself. The README's Future features section says the next set of core features requires large structural changes and therefore requires a complete rewrite for best results, and that this rewrite is in progress in the 0.9 branch though it will take quite some time. That is an unusual thing for a README to admit, and it should shape your expectations. The remote backends, file transforms, automatic updates, and RSS features listed there are not in the current release; they are a description of a different program that does not exist yet. If your requirement is RSS-driven automatic episode downloads, Cloud Torrent does not do it today.

The second limitation is access control. The README documents --auth as optional basic auth in the form 'user:password'. There is no mention of multiple users, per-torrent permissions, or an audit trail. Anyone who reaches the port with valid credentials sees the same view and can add or remove the same torrents. The README does not document rate limiting or lockout on failed attempts. Treat the port as you would an unauthenticated admin panel, and put it behind a reverse proxy or a private network rather than exposing it directly.

The third is that this is a disk-writing service with no quota mechanism described. Torrents are written as sets of files on the local disk of the server, and nothing in the README describes a size cap, a retention policy, or automatic cleanup. On a small VPS with a fixed volume, that is a real failure mode: the download succeeds and then the disk fills. The README is silent on what happens when the target filesystem runs out of space.

Finally, if you want a command-line client you can script, this is not it. Cloud Torrent is a server with a browser UI. The --open flag launches your default browser, which tells you where the project expects interaction to happen.

## How it compares to Transmission and to hosted download services

Transmission is the closest like-for-like alternative, and the difference is architectural rather than a matter of feature counts. Transmission is a daemon with a native desktop GUI and a separate web interface, and it has a long-standing remote-control protocol that third-party clients speak. Cloud Torrent collapses that into one Go binary with the UI embedded, which is why the README can list "Single binary" and "Cross platform" as features. The trade-off runs the other way too: Transmission's separation means you can drive it from a script or a phone app without touching the daemon, while Cloud Torrent's control surface is the page it serves.

The other comparison is against hosted download services, the ones that fetch a torrent for you and hand back a link. Those remove the server entirely, which is genuinely less work. The difference is that the file passes through someone else's machine, and the README's framing of Cloud Torrent as self-hosted is a direct answer to that: the files are downloaded on the local disk of the server you run, and they are retrievable from that same server. If your reason for wanting a remote client is that you do not trust the intermediary, Cloud Torrent is the version of the idea that keeps you in the loop. If your reason is simply that you do not want to run a server, it is the wrong answer, because running a server is the whole product.

## Maintenance, releases, and the AGPL-3.0 licence

The repository is not archived, and the last push was on 2026-09-26, two days before this article. That is current. The release history is sparser than the commit activity: v0.9.4 was tagged on 2024-11-30, following v0.9.1 and v0.9.0 on 2024-04-19. So the repository is receiving commits while tagged releases are infrequent. If you install from a release binary or the published Docker image, you are on a build that is close to two years old by tag date, even though the branch has moved since. If you build from source, you get the current state of master, which the README warns is mid-rewrite.

The upgrade story is thin. The README lists automatic updates only under Future features, meaning the binary does not upgrade itself today. There is a wiki page linked for auto-running on boot, which implies the expected model is a long-lived process started by your init system, and upgrading means replacing the binary or pulling a newer image. The --config-path flag defaults to cloud-torrent.json, so check what that file holds before you replace a binary, since the README does not document a migration path between versions.

The licence is AGPL-3.0. The practical consequence, stated plainly and not as legal advice: if you modify Cloud Torrent and let other people interact with it over a network, the AGPL's network clause is the part that differs from the GPL, and it is the part worth reading before you build a modified version into something you host for others. Running an unmodified copy on your own server is the ordinary case and is what the README's install instructions describe. Note also that the program depends on github.com/anacrolix/torrent, which carries its own licence terms that you should check separately if you plan to redistribute.

## Conclusion

Adopt jpillora/cloud-torrent if you want a remote download box you control, with no desktop app and no third-party download service in the path. Skip it if you need a headless CLI, per-user accounts, or a client that is still under active feature development; the README itself says the core feature set requires a rewrite. Before deploying, verify what the web UI exposes, since the README documents --auth for basic auth but does not describe role separation or per-torrent permissions.

## FAQ

### What is jpillora/cloud-torrent?

It is a self-hosted remote torrent client written in Go. You start torrents through a web interface, they download to the local disk of the server, and the resulting files are retrievable or streamable over HTTP.

### How do I install jpillora/cloud-torrent with Docker?

The README gives the image jpillora/cloud-torrent and an example that maps port 3000 and mounts a host directory at /downloads. The VPS walkthrough uses a different port with --restart always and the same volume mount.

### Does jpillora/cloud-torrent support authentication?

Yes, optionally. The --auth flag takes a value in the form 'user:password', and the README notes it can also be supplied through the AUTH environment variable. The README does not describe multiple users or per-torrent permissions.

### Is jpillora/cloud-torrent still being developed?

The repository is not archived and the last push was on 2026-09-26. Tagged releases are less frequent: v0.9.4 dates from 2024-11-30. The README states that a rewrite in the 0.9 branch is in progress and will take quite some time.

## Sources

- [Issues](https://github.com/jpillora/cloud-torrent/issues)
- [jpillora/cloud-torrent on GitHub](https://github.com/jpillora/cloud-torrent)
- [License: AGPL-3.0](https://github.com/jpillora/cloud-torrent/blob/master/LICENSE)
- [README](https://github.com/jpillora/cloud-torrent/blob/master/README.md)
- [Releases](https://github.com/jpillora/cloud-torrent/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/jpillora-cloud-torrent