Flood: a self-hosted web UI for rTorrent, qBittorrent and Transmission

What Flood adds on top of a torrent client you already run

Flood is not a torrent client. It is a monitoring and administration service that sits beside one. The README describes it as "a Node.js service that communicates with your favorite torrent client and serves a decent web UI for administration", and the package description adds multi-user and multi-client support. That framing matters, because it tells you where the value is: the client keeps downloading, and Flood gives you a browser tab, accounts, and an HTTP API in front of it.

The supported clients are rTorrent, qBittorrent v4.1 and later, and Transmission, each with a linked test setup file in the repository. Deluge v2 and later is listed as experimental, which is a real distinction rather than a formality. If Deluge is your client, you are on the part of the matrix the maintainers have not committed to testing.

The audience is narrow and specific. You run a seedbox or a home server, you already have a client configured, and you want remote administration without exposing the client's own interface. Flood's builtin user management is enabled by default, and the README says you are prompted to configure the connection to the torrent client when you first load the web interface. That first-run flow is aimed at someone who wants the UI to be the only thing reachable from outside.

How the Node.js backend talks to rTorrent, qBittorrent and Transmission

The repository is a pnpm workspace with three top-level source directories: client, server and shared. The client directory holds the React frontend, built with Vite and styled through Panda CSS. The server directory holds the Node.js service. The shared directory holds code both sides use, and it is where the configuration schema lives: the README points readers to shared/schema/Config.ts for the full set of options.

That split explains the data flow. The server process opens a connection to the torrent client using whatever protocol that client exposes, normalises what comes back into a shape the frontend understands, and the browser talks only to Flood. The client never speaks to your torrent client directly. This is why the configuration interface is a command line one rather than a web form: connection details, the listening port and the allowed paths are process-level concerns, set before the service starts.

Flood also exposes its own HTTP API. The README states that an OpenAPI specification is available at /api/openapi.json and interactive Swagger UI documentation at /api/docs/. The wiki links to lists of unofficial client API libraries and unofficial API integrations, so the API is treated as a supported surface rather than an accident of the frontend. If you want to script against your torrent client without learning three different protocols, that is the practical argument for putting Flood in the middle.

The server also performs file operations itself. The troubleshooting section is explicit that Flood uses only the path provided by the torrent client, and that the same path must resolve to the same file for both processes. A file at "/path/to/a/file" for the client has to be "/path/to/a/file" for Flood. A bind mount that presents the same data at a different mount point breaks file operations even though the torrents themselves keep running.

Installing Flood with npm and completing the first client connection

The README gives two installation routes. The first is npm, globally or through npx. The second is a single-executable build downloaded from Releases, which bundles Node.js and supports Linux, macOS and Windows. Docker is a third option, covered below.

Before any of that, Node.js has to be present. Flood tracks Current and supports Active LTS as well. The README lists NodeSource for Debian, Ubuntu and Enterprise Linux distributions, winget or Chocolatey on Windows, and brew on macOS.

The global install is a single command. The sudo prefix is the README's own parenthetical, which tells you it may or may not be needed depending on how your Node.js installation is set up.

(sudo) npm install --global flood

After that, running the service is just the binary name. If you would rather not install globally, npx runs it without a permanent install.

flood

Running it with no arguments starts the service and, per the README, prompts you to configure the torrent client connection when you load the web interface, because builtin user management is on by default. To see what else the process accepts before you start it, ask for help. The README names --help, and points to shared/schema/Config.ts for the full configuration surface.

flood --help

One argument you may need before first run is the base URI. If you proxy Flood under a subpath, the README says to set baseURI to that subpath. Serving Flood from https://foo.bar/apps/flood means baseURI is /apps/flood. Serving it from the root of a host means you do not set it at all.

The Docker route is a single command for a help listing, which is how the README introduces the image. Note the port and volume flags in the README's own example: the container exposes 3000, and folder mapping is expressed as -v /data:/data. The README also notes that arguments such as --port and --allowedpath can be passed as environment variables instead, in the form -e FLOOD_OPTION_port=3000.

docker run -it jesec/flood --help

Upgrading is deliberately dull on both routes. The README says to run the installation command again for npm, and docker pull jesec/flood for the image. There is no migration step documented, and Flood conforms to Semantic Versioning conventions, so a minor or patch bump should not require configuration changes.

The filesystem path constraint is the failure mode to plan for

The most common way a Flood deployment goes wrong is not a crash. It is a UI that lists torrents correctly and then fails on every file action, because Flood and the torrent client disagree about where the files live. The README's troubleshooting section treats this as the headline issue, and the wording is unambiguous: Flood cannot use /mnt/some/different/path/file when the client sees /path/to/a/file.

This bites hardest in container setups. The Dockerfile in the repository carries a warning that it is for development and debugging only, that it bundles rTorrent for easier debugging, and that the bundled rTorrent is not started unless you pass --rtorrent. It also warns that the build uses the contents of the current folder, which may contain secrets or uncommitted changes, and that the result should not be published unless composed in a clean environment. For production the comment points at a different image, rtorrent-flood. If you copy the development Dockerfile into a deployment, you inherit both problems: a build context that may leak, and a path layout you have to reconcile by hand.

A second limitation is client capability. The README notes that certain features, including sequential download and initial seeding, are not available in vanilla rTorrent. Flood can only surface what the client exposes, so a feature gap in the client becomes a feature gap in the interface.

A third is Deluge. Experimental support means the maintainers have not attached the same test setup they use for the other three clients. Treating it as equivalent to rTorrent or Transmission is a misreading of the support table.

Flood versus using qBittorrent's own web interface

qBittorrent ships a web UI of its own, and Transmission and rTorrent have third-party frontends. The honest comparison is not Flood against nothing; it is Flood against the interface your client already provides.

The difference is scope. A client's built-in interface manages that one client. Flood manages several clients behind one interface, with its own user management, and exposes a single OpenAPI-documented API at /api/openapi.json regardless of which client is underneath. If you run one client and one user, the built-in interface is fewer moving parts: no Node.js runtime, no extra process, no path-matching problem between two services, because there is only one process touching the files.

Flood earns its place when the client count or the user count grows. Multi-client support is in the package description, and the API documentation is a first-class part of the README rather than an afterthought. The wiki's lists of unofficial API libraries and integrations are the visible sign of that: people are building against Flood's HTTP surface rather than each client's.

There is a cost, and it is the path constraint again. Adding Flood means adding a second process that needs the same view of the filesystem as the client. With one client and its own UI, that constraint does not exist.

Licence and the ongoing cost of running Flood

Flood is GPL-3.0-only, stated both in the repository and in the license field of package.json. The practical consequence, without offering legal advice, is the usual one for GPL software: if you distribute a modified Flood, or a product built on it, the copyleft terms attach to that distribution. Running it on your own server for your own torrents is not distribution. Anyone planning to embed Flood in something they ship should read the licence text rather than rely on a summary.

The upgrade cost is low by design. npm users re-run the install command; Docker users pull the image again. Versioning follows Semantic Versioning, and the repository keeps a CHANGELOG.md at the top level. The last push to the default branch was on 2026-09-23, and the most recent release listed is v4.16.2 on 2026-09-19, so the project is being worked on rather than sitting still.

The operational cost is the part people underestimate. Flood needs read and write access to the torrent data, and it needs that access at the same paths the client uses. Every change to how your storage is mounted is a change you have to make in two places. The README's advice to check the wiki's Security sections before exposing the service is worth taking literally, because the builtin user management is what stands between the internet and your torrent client's API.

Editorial conclusion

Adopt Flood if you already run rTorrent, qBittorrent or Transmission on a machine you control and want a browser interface with its own user management, an OpenAPI spec at /api/openapi.json and a Swagger UI at /api/docs/. Do not adopt it if the torrent client and Flood would see different paths for the same files, or if you depend on Deluge, which the README marks experimental. Before committing, verify that Flood's process can read and write the exact paths the client reports, and decide whether GPL-3.0-only fits how you intend to distribute anything built on it.

Frequently asked questions

Official sources

1. jesec/flood on GitHub
2. License: GPL-3.0
3. Project website
4. README
5. Releases