🇬🇧 English · 🇫🇷 Français

Applies to Hydranos 4.4.

This page is for anyone running Hydranos on a Windows PC. By the end you will have hydranos.exe running from a folder you chose, know where its files go, how to stop and update it without losing resume data, how to type the wiki's command examples in PowerShell, and which features behave differently on Windows. Terms such as store and resume state are defined on Concepts and Glossary.

Releases are on github.com/Kheopsian/Hydranos/releases. Windows has one build, 64-bit x86 (amd64):

• hydranos-v4.4.0-windows-amd64.zip
• hydranos-v4.4.0-windows-amd64.zip.sha256

Checking the download is optional but recommended. Open PowerShell in your Downloads folder (in Explorer: right-click an empty spot of the folder › Open in Terminal, or type cd $HOME\Downloads in PowerShell), then compare the hash with the first word of the .sha256 file (case does not matter):

(Get-FileHash .\hydranos-v4.4.0-windows-amd64.zip -Algorithm SHA256).Hash
Get-Content .\hydranos-v4.4.0-windows-amd64.zip.sha256

The zip holds one folder, hydranos-v4.4.0-windows-amd64\, with:

Since 4.4 the zip no longer holds hydranos-engine.exe. An install updated from 4.3 still has that file: nothing uses it and you can delete it. There is no --agent-only mode; running several machines is done with nodes (Nodes and Multiple Machines).

Copy the contents of that folder into a folder you can write to without administrator rights, for example C:\Hydranos or C:\Users\<you>\Hydranos. Not under C:\Program Files: Hydranos writes its config, log and state next to the config file, and Program Files is read-only for normal programs.

SmartScreen. The release executables are not code-signed (the release build does no signing). The first time you start hydranos.exe, Windows may show "Windows protected your PC": click More info › Run anyway. The same can happen after an update replaces the files. Your antivirus may also ask; that is expected for an unsigned program downloaded from GitHub.

hydranos.exe takes these command-line options: --config <path> (or --config=<path>), --console, --version (-V) and --help (-h), plus two commands, reset-password <password> [path\to\default.toml] and hash-password <password> (see Security and Access). An unknown argument does not stop the start: Hydranos prints hydranos: ignoring unknown argument "…"; starting anyway (see hydranos --help) and starts. That warning is only visible when Hydranos runs in a console (see First start).

Without --config, the config is default.toml beside hydranos.exe. Unzipped into C:\Hydranos and started by a double-click, every file lands in that folder:

What each file holds is on Architecture.

Coming from 4.3 started without --config. 4.3 used /config/default.toml, which Windows reads as \config\default.toml on the current drive (C:\config\ for a double-click from C:\Hydranos). When there is no default.toml beside hydranos.exe and that old file exists, 4.4 keeps using it (and everything beside it), so nothing seems to vanish. Its notice (hydranos: using /config/default.toml (the 4.3 location); move it beside hydranos.exe or pass --config, with forward slashes) is printed before any console is attached, so you will not see it in a console window. To move to the new place: quit Hydranos, move the contents of C:\config\ into C:\Hydranos\, then change data_dir in default.toml from "/config/data" (what 4.3 wrote) to "C:/Hydranos/data", and start again. Or leave it where it is and start with --config "C:\config\default.toml".

To keep the config somewhere else, pass --config. Create a shortcut: right-click hydranos.exe › Create shortcut (on Windows 11: Show more options first), open its Properties, and set Target to, for example:

"C:\Hydranos\hydranos.exe" --config "D:\HydranosData\default.toml"

Keep the quotes: they are required as soon as a folder name contains a space ("C:\Users\Jean Dupont\Hydranos\hydranos.exe" --config "C:\Users\Jean Dupont\Hydranos\default.toml"). Use that shortcut from now on. The log, data and the engine folders then follow the config file, not the .exe.

Two rules for this folder:

• Keep it on a local disk. Hydranos treats a UNC path (\\server\share) or a mapped network drive as a network filesystem. The store's journal mode is chosen accordingly, and a store moved onto a network drive after it was used locally can start Hydranos in rescue mode (see Operating Hydranos).
• Paths inside default.toml need forward slashes or single quotes. TOML treats \ inside double quotes as an escape, so data_dir = "C:\Hydranos\data" fails to parse and Hydranos exits. Write "C:/Hydranos/data" or 'C:\Hydranos\data'. This rule is for the TOML file only: in the web UI's fields (category Save Path, Set location…, watched folders) type normal Windows paths such as D:\Media\Movies. A workflow's move files to a folder action takes the same: a drive path (D:\archive) or a UNC path; \archive, without the drive, is refused (see Workflows).

Two ways, pick one:

• From the web UI (simplest): Config › Advanced settings (default.toml), change the value, click Save settings. Settings that need a restart are flagged when you save.
• By hand: quit Hydranos from the tray, open C:\Hydranos\default.toml in Notepad, edit, save, start Hydranos again. Hydranos reads the file only at start.

To restart, either use the web UI's restart (or tray › Quit Hydranos, wait until hydranos.exe is gone from Task Manager, and start it again). Since 4.4 the restart does the same clean stop as Quit (resume state saved), and on Windows the stopping process starts its successor itself, with the same command-line arguments, before it exits (restart: successor started in hydranos.log). The one exception is a service: see Start with Windows.

Double-click hydranos.exe (or run your shortcut). No console window opens: hydranos.exe is a Windows (GUI) program. A Hydranos icon appears in the notification area next to the clock (it may be in the hidden-icons arrow ^), and the web UI answers on http://127.0.0.1:8199.

To see the log live:

• Start it from PowerShell or cmd: it attaches to that window and prints its log there.
• Add --console to the shortcut's Target: it opens a console window of its own. Prefer tray › Quit to that window's X: closing the console does start the clean stop, but Windows ends the process a few seconds later, so the save may be cut short (see Stopping cleanly).

Output written before the console is attached never shows in a console window: --version, --help, hash-password and the 4.3-location message print nothing in the PowerShell or cmd window, even when started from there (read from the code, not tested on Windows). Redirected, they do write: .\hydranos.exe --version | Out-String, or > out.txt. That is how hydranos-update reads the installed version. reset-password still writes the new hash into default.toml; check with Notepad that [auth] has a new password_hash, then start Hydranos.

The log is also written to hydranos.log beside the config, unless the environment variable HYDRANOS_LOG_STDOUT is set (to any value, even 0). If Hydranos does not appear to start, read that file first.

Do this in order:

1. Create the admin account first. Open http://127.0.0.1:8199 on this PC and follow First run on Installation and First Run. Until the account exists, any caller on your local network (a loopback, private or link-local address) who can reach port 8199 can create it; a public address gets 403 (see Security and Access). Connections from this PC to 127.0.0.1 are not filtered by Windows Firewall (Windows behaviour, not tested by the maintainer), so you do not need to answer the firewall prompt to do this.
2. Then answer the Windows Firewall prompt. It appears in the first seconds, when Hydranos opens port 8199 on all interfaces, then the engines' ports. Tick Private networks only and click Allow. Do not click Cancel: Windows may then record a block rule for hydranos.exe, and a block rule wins over any allow rule you add later (Windows behaviour, not tested by the maintainer; remove it in Windows Defender Firewall with Advanced Security › Inbound Rules).

Hydranos listens on port 8199 (TCP) for the web UI and APIs, and on 16171 (race) and 16172 (hoard), TCP and UDP, for peers; the full list is on Installation and First Run. To create the rules yourself, open an elevated PowerShell (Start menu, type PowerShell, right-click › Run as administrator) and run, for the peer ports only:

New-NetFirewallRule -DisplayName "Hydranos peers TCP" -Direction Inbound -Program "C:\Hydranos\hydranos.exe" -Protocol TCP -LocalPort 16171,16172 -Action Allow -Profile Private
New-NetFirewallRule -DisplayName "Hydranos peers UDP" -Direction Inbound -Program "C:\Hydranos\hydranos.exe" -Protocol UDP -LocalPort 16171,16172 -Action Allow -Profile Private

Add a rule for TCP 8199 only if you want the web UI from other machines on your network. If you only use it from this PC, also set api_host = "127.0.0.1" in [daemon] and restart; by default it listens on every interface (api_host = "0.0.0.0"). The tray icon opens 127.0.0.1 either way.

Your router. For peers outside your home to reach you, the listen ports must be forwarded on your router. Hydranos tries UPnP, which maps TCP and UDP; NAT-PMP to the router is not available on Windows (see What does not work on Windows). If your router has no UPnP, forward 16171 and 16172, TCP and UDP, to this PC on the router's admin page. See Networking: Ports, Port Forwarding and the Network Tab.

A clean stop closes the API (open web UI tabs no longer hold it: their live connections end themselves, and the wait is bounded to 5 s), tells the trackers stopped (5 s at most), then saves every engine's resume state (one thread per engine) and exits. It starts the moment it is asked, with a WARN line <what>: draining the API and flushing resume data in hydranos.log. The code listens for:

The tray icon disappears at once, before the save: the signal that the save is done is hydranos.exe leaving Task Manager (or shutdown flush complete in hydranos.log).

End task in Task Manager, taskkill /F and a crash end Hydranos without the save.

What you lose each time the save does not run (or is cut short): up to the last 300 seconds of piece progress, upload/download counters and seed time per engine (resume state is saved every 300 s, and immediately when a torrent is added, completes or moves). Torrents affected by the lost progress are re-checked at the next start; it is not a re-check of your whole library. Details on Operating Hydranos.

If you turn the PC off every night, make tray › Quit Hydranos the step before you shut down, and wait until hydranos.exe is gone from Task Manager. Hydranos 4.4 tries to save on shutdown, but as the table says that is not something to rely on.

HYDRANOS_STOP_TIMEOUT bounds the save (default 120 s; 120, 60s, 2m or 1m30s). Past it, Hydranos exits with what is already written and logs shutdown flush hit HYDRANOS_STOP_TIMEOUT; leaving with what is saved. A whole stop therefore lasts at most about 130 s (5 s drain, 5 s for the trackers, then the save).

At sign-in (recommended for a desktop PC). Press Win+R, type shell:startup, and put a shortcut to hydranos.exe (with your --config, if you use one) in the folder that opens. You get the tray icon and its clean Quit Hydranos.

As a service (advanced, not tested by the maintainer). A service wrapper such as NSSM (a separate download from its own website) can run hydranos.exe:

nssm install Hydranos "C:\Hydranos\hydranos.exe" "--config C:\Hydranos\default.toml"
nssm start Hydranos

Pass --config with an absolute path, so where the files go never depends on the service's working folder. A service runs in its own session, so there is no tray icon; use the web UI. A service stop is clean only if the wrapper sends Ctrl+C or Ctrl+Break to a console Hydranos is attached to (it has one of its own only with --console); whether a given wrapper does that has not been checked for 4.4. If losing up to 300 s of resume state per stop matters to you, prefer the Startup folder.

Under a service:

• Restart through the service (nssm restart Hydranos), not with the web UI's restart. The UI's restart makes Hydranos start its own successor outside the wrapper and exit with code 75, which a wrapper may also answer by starting a copy: two instances on the same files and ports (read from the code, not tested).
• Stop the service before updating (nssm stop Hydranos, run the updater, nssm start Hydranos). The updater's stop request is a Local\ event, which reaches only processes of your own sign-in session, not a service (from Windows' rules on object names, not tested).

A shortcut cannot set an environment variable. Hydranos reads them only at start (examples: RUST_LOG, HYDRANOS_LOG_STDOUT, TYPHON_ANNOUNCE_PROXY; the full list is on Configuration: Environment Variables, CLI and Signals).

• For one start, from PowerShell:

  $env:RUST_LOG = "info"; & "C:\Hydranos\hydranos.exe" --config "C:\Hydranos\default.toml"

• Permanently, for your account: run setx RUST_LOG info in PowerShell, or use Start › type environment › Edit environment variables for your account. Programs already running keep the old values: quit Hydranos from the tray and start it again. If a Startup-folder start still does not see the value, sign out and back in.
• To remove it: delete it in the same Edit environment variables for your account window (setx cannot delete).

Most wiki pages show curl commands written for Linux, split over several lines with \. On Windows:

• Type curl.exe, not curl: in Windows PowerShell 5.1, curl is an alias for Invoke-WebRequest, which takes different options. curl.exe is included in Windows 10 and 11.
• Put the whole command on one line (drop the trailing \), or end each line with a backtick ` instead.
• Use http://127.0.0.1:8199 and Windows paths.

Your API key is in Config › Advanced settings (default.toml) › General › api_key, or:

Select-String -Path "C:\Hydranos\default.toml" -Pattern '^api_key'

A read-only call, with PowerShell's own command:

Invoke-RestMethod -Uri http://127.0.0.1:8199/api/categories -Headers @{ "X-Api-Key" = "YOUR_API_KEY" }

Uploads (-F multipart forms) are easier with curl.exe: Windows PowerShell 5.1's Invoke-RestMethod has no -Form option.

The rules (download, recheck or seed mode, and the exact folder layout) are on Adding Torrents and Existing Data; read Download, recheck, or seed mode there first. In short: without seed mode, adding over existing data rechecks it (it reads every byte once). Seed mode, which starts seeding without reading the data, is asked with the Add tab's Skip the hash check, the data is already on disk box, or with seed_mode=true on the REST API, which is easier for a whole folder.

Windows form, for movies under D:\Media\Movies:

1. Create a category, e.g. movies, with Mode hoard and Save Path D:\Media\Movies (Categories tab).
2. Check the layout. A multi-file torrent named Film (2020) must find its files in D:\Media\Movies\Film (2020)\, under exactly that name. If your folder is named differently, the data is not found: rename the folder, or the torrent downloads again (with seed mode: it advertises data it does not have).
3. Add one .torrent:

   curl.exe -H "X-Api-Key: YOUR_API_KEY" -F "torrent=@C:\Torrents\Film (2020).torrent" -F "category=movies" -F "seed_mode=true" http://127.0.0.1:8199/api/torrents/upload

4. Or every .torrent in a folder:

   Get-ChildItem "C:\Torrents\*.torrent" | ForEach-Object { curl.exe -s -H "X-Api-Key: YOUR_API_KEY" -F "torrent=@$($_.FullName)" -F "category=movies" -F "seed_mode=true" http://127.0.0.1:8199/api/torrents/upload }

Only use seed_mode=true when you know the data is complete and in place; otherwise leave it out and let Hydranos recheck. Coming from qBittorrent, the import wizard does this for you: Migrating from qBittorrent.

From the tray (or by hand). Check for updates runs hydranos-update.exe --dir <its folder> in a cmd window. You can also run it yourself; always pass --dir, because the updater reads the installed version by running hydranos.exe --version in that folder (--dir defaults to the current folder, and from anywhere else it prints installed: unknown):

"C:\Hydranos\hydranos-update.exe" --dir "C:\Hydranos" --check
"C:\Hydranos\hydranos-update.exe" --dir "C:\Hydranos"
"C:\Hydranos\hydranos-update.exe" --dir "C:\Hydranos" --tag v4.4.0

Its options: --check, --dir <folder>, --tag <vX.Y.Z>, --yes and, since 4.4, --config <file> (default: default.toml in --dir). The updater reads that config to send its own requests (GitHub API, the zip) the way the daemon sends its own: [daemon] egress, the kill switch and the network mode (see VPN and Egress). When that route is not the direct one, or the kill switch is armed, it prints network: … first. A missing file means the default route; a file that is not valid TOML stops the updater. The tray never passes --config: if your config is not beside hydranos.exe, run the updater by hand with --config.

It prints the installed and the available version, downloads the zip from GitHub releases, and checks it against the published .sha256. It refuses to install when the checksum is missing or wrong. It then asks replace the binaries with <tag>? [y/N] (--yes skips the question). Only the program files that already exist in the folder are replaced: hydranos.exe and hydranos-update.exe (and hydranos-engine.exe, if a release zip held one; 4.4 zips do not). default.toml, data\, the engine folders and the log are not in the archive and are never touched. --tag installs a given release, older ones included.

Before replacing anything it has to stop Hydranos. Since 4.4 it asks through a named event, Local\HydranosStop, that Hydranos waits on: Hydranos logs stop requested by the updater and does the same clean stop as tray › Quit (resume state saved). When there is no such event, the updater falls back to taskkill /IM hydranos.exe /T without /F. That happens with a Hydranos older than 4.4, and with a 4.4 still on its startup screen: the event, like the tray icon, only exists once the torrents are loaded (while the startup screen shows, the tray has no Quit either). taskkill without /F stops neither, since Hydranos has no window for it to close. Either way it then waits up to 60 seconds for hydranos.exe to be gone. So:

1. Click Check for updates (or run the updater) and answer y.
2. Wait. Hydranos stops by itself, the updater replaces the binaries and prints updated to <tag>. Start hydranos again.
3. Start Hydranos again yourself: the updater does not (SmartScreen may ask again: More info › Run anyway).

Known bug in 4.4: an update started while Hydranos is still on its startup screen cannot stop it: there is no stop event yet and taskkill is ignored, so it always ends with still running after 60s, nothing replaced. Found by reading the code, not reproduced. Wait for the startup screen to go before updating.

If it ends with hydranos is still running after 60s -- stop it yourself, nothing was replaced, nothing was changed. A clean stop can take longer than 60 s, since the save alone may use up to HYDRANOS_STOP_TIMEOUT (120 s by default) on a large library; Hydranos keeps stopping regardless. Wait until hydranos.exe is gone from Task Manager and run the updater again.

Updating from 4.3.x to 4.4. The updater that runs is the 4.3 one, and the Hydranos it must stop has no stop event: quit first, as with 4.3. Start the update, wait for the [y/N] question, tray › Quit Hydranos, wait until hydranos.exe is gone from Task Manager, then answer y: the updater finds Hydranos stopped and replaces the binaries.

Under a service, stop the service before updating (see Start with Windows).

flowchart TD
    A["hydranos-update.exe<br/>tray Check for updates, or by hand"] --> R["Reads the route from --config<br/>(default: default.toml in --dir)"]
    R -- "file is not valid TOML" --> X0["Error, nothing replaced"]
    R -- "read, or no file" --> B["Prints installed and available tag"]
    B --> C{"--check given?"}
    C -- yes --> Z["Exit, nothing changed"]
    C -- no --> D{"Same tag installed<br/>and no --tag?"}
    D -- yes --> Z
    D -- no --> E["Download the release zip"]
    E --> F{"Matches its published .sha256?"}
    F -- "no, or no .sha256" --> X["Error, nothing replaced"]
    F -- yes --> G{"--yes given, or you answer y?"}
    G -- no --> Z2["Cancelled, nothing replaced"]
    G -- yes --> H{"hydranos.exe still running?"}
    H -- no --> J["Replace only the binaries<br/>already in the folder"]
    H -- yes --> K{"Stop event Local HydranosStop<br/>exists? (4.4 or later, torrents loaded)"}
    K -- yes --> S["Signal it: Hydranos does<br/>the clean stop, as tray Quit"]
    K -- "no: older Hydranos, or 4.4 still loading" --> T["taskkill without /F,<br/>ignored (no window)"]
    S --> L{"Gone within 60 s?"}
    T --> L
    L -- no --> X2["still running after 60s,<br/>nothing replaced"]
    L -- yes --> J
    J --> M["Start Hydranos again yourself"]

By hand. Quit from the tray, download and check the new zip, copy the files from its folder over the old ones in C:\Hydranos, start again. Your config and data stay where they are.

The update badge in the web UI header only tells you that a newer release exists; see Operating Hydranos.

The setup to use on Windows is a system-wide VPN client (your provider's app, or the official WireGuard/OpenVPN client) that makes the tunnel the default route for the whole PC. Hydranos then follows it like any other program. Turn on the client's kill switch if it has one: Hydranos's own kill switch cannot see a system-wide VPN (see below).

On the Network tab (Config › Advanced settings (default.toml) › Network), the five modes behave like this on Windows:

• bind_interface is refused on Windows since 4.4: interface pinning is Linux-only. POST /api/network/mode and POST /api/engines answer 400 to a non-empty value, and the + Add an engine form has its interface field disabled (Linux only). Advanced settings and a hand edit do not stop you, but an engine whose default.toml still sets it starts off the network: no listener, no outgoing connection, no announce, no DHT or LSD, with a WARN at start (… -- this engine will not announce, accept or dial any peer until the key is removed). Remove the key and restart.
• Leave Daemon interface empty. The Network tab and POST /api/network/egress accept a [daemon] bind_interface on Windows, but every request of the daemon itself (tracker and IP filter lists, the update check, webhooks, .torrent URLs, and hydranos-update) that goes out directly or through [proxy] (egress direct or proxy, or auto when no engine lends a proxy or tunnel) is then refused with [daemon] bind_interface "…" cannot be applied on this platform; set a proxy instead (the request is refused rather than sent by the default route). A route borrowed from an engine (engine:<id>, or auto in SOCKS5 mode with an engine proxy) is not affected. Setting [proxy] does not lift the refusal while the interface is set: to route those requests elsewhere, empty Daemon interface and use [proxy] (see VPN and Egress).
• The kill switch and a system-wide VPN. Hydranos's kill switch knows only its own ways out (proxy, tunnel, interface). With it armed ([daemon] kill_switch = true, or a SOCKS5 mode), an engine with none of them is blocked unless its section says allow_direct = true: with a system-wide VPN, either leave the kill switch disarmed (Direct mode does) or mark those engines allow_direct. The system client's own kill switch is the one that protects you.
• Forwarded port. If your provider gives you a forwarded port, put it in listen_port under [hoard] (or [race]), and add auto_port_forward = false at the top of default.toml (before [daemon]); then restart.
• Check. With the VPN on, the header's Exit IP should show the VPN's address. Your tracker's profile page, which lists the address you announced from, is the definitive check.

What each part of Hydranos sends where, and why a system-wide tunnel is the safe setup, is on VPN and Egress.

• Interface pinning (bind_interface): refused, and an engine that still has it in its file stays off the network. See VPN on Windows above.
• Managed WireGuard: Linux only; the card is greyed out. See VPN on Windows above.
• [daemon] bind_interface: accepted by the Network tab, then every daemon request that does not borrow an engine's route is refused. Leave Daemon interface empty.
• NAT-PMP. Automatic port forwarding (auto_port_forward, on by default) cannot find the gateway on Windows (NAT-PMP: no default gateway), so only UPnP (TCP and UDP) is tried. Behind a VPN that offers port forwarding through NAT-PMP, set the port by hand.
• TRIM after drain. Refused with TRIM is not available on this system, and the option is turned off for that volume until you turn it on again or restart. Windows already trims SSDs itself as files are deleted (Windows behaviour, not something Hydranos does). See Race, Drain and Graduation.
• IP filter list files. A block-list source must be an http(s):// URL or a path starting with /; C:\… is refused. Use a URL.
• Memory diagnostics. The jemalloc allocator and its heap dumps are Linux-only; Windows uses the system allocator. No difference in normal use. System figures read from /proc on Linux (iowait, ZFS ARC, open-file count) are not measured on Windows.

Everything else (categories, race and hoard, the qBittorrent shim, workflows, nodes) behaves as on Linux. Problems specific to a platform are listed on Troubleshooting.

Now do First run on Installation and First Run: create the admin account, find your API key, create a category and add your first torrent.