🇬🇧 English · 🇫🇷 Français

Applies to Hydranos 4.4.

For whoever keeps an instance running: how to stop it without losing resume state, what the restart buttons do, what the start looks like, what to back up and how to restore it, what to do when the store will not open or the password is lost, and how to update on Docker, Linux and Windows.

Short version: every stop and every restart (Docker, systemd, the tray, the web UI's restart buttons) goes through the same clean stop; keep the supervisor's stop limit above HYDRANOS_STOP_TIMEOUT + 10 s. To back up: stop Hydranos, copy its folder(s), start it again.

Hydranos stops the same way on every trigger (signal, tray, console event, the Windows updater's stop request, a restart asked from the UI or the API):

1. The UI's event stream (/api/events) and the Logs live tail end themselves; the HTTP server stops accepting connections and lets in-flight requests finish, for 5 s at most.
2. Departures: every torrent that announced started sends stopped to its trackers, race engines first, 5 s at most for all of them.
3. The resume state of every engine is written (each engine on its own thread, in parallel), bounded by HYDRANOS_STOP_TIMEOUT.
4. Managed WireGuard tunnels are taken down.
5. Exit with code 0, or 75 when the stop is a restart (see Restart from the UI).

Nothing is written to the store at that point: store changes are committed as they happen.

sequenceDiagram
    participant S as Supervisor - Docker, systemd or you
    participant M as hydranos
    participant H as HTTP server
    participant T as trackers
    participant R as race engine thread
    participant D as hoard engine thread
    S->>M: SIGTERM, SIGINT, Ctrl+C, a Windows console event, tray Quit Hydranos or a restart request
    M->>H: event stream and log tail end, stop accepting connections
    H-->>M: in-flight requests finished, or 5 s passed
    M->>T: stopped for every started torrent, race first, 5 s at most
    par one thread per engine
        M->>R: write every resume row to race/state.db
        R-->>M: resume data saved, took_ms
    and
        M->>D: write every resume row to hoard/state.db
        D-->>M: resume data saved, took_ms
    end
    alt every engine done within HYDRANOS_STOP_TIMEOUT
        M->>M: log shutdown flush complete, took_s
    else budget reached
        M->>M: log WARN shutdown flush hit HYDRANOS_STOP_TIMEOUT, leave with what is saved
    end
    M->>M: take managed WireGuard tunnels down
    M-->>S: exit code 0, or 75 for a restart
    Note over S,M: If the supervisor's grace period ends first, it sends SIGKILL.<br/>Rows not yet written fall back to the last 300 s save.

Extra engines get their own thread in the same way. What you see in the log (Linux):

WARN SIGTERM received, draining the API and flushing resume data
INFO stopped sent to the trackers departed=… of=…
INFO resume data saved engine=race took_ms=…
INFO resume data saved engine=hoard took_ms=…
INFO shutdown flush complete took_s=…

The stopped sent to the trackers line is absent only when no torrent had announced started. The first line names the trigger (SIGINT, restart request…); on Windows it reads <trigger>: draining the API and flushing resume data, e.g. tray quit:, console closed:, system shutdown:. A tab still holding a connection after 5 s adds WARN connections still open 5 s into the drain (event stream, log tail); flushing without them. With managed WireGuard, INFO wireguard: tunnels taken down tunnels=… follows the flush.

A stop asked while the catalogue is still loading is heard: the load finishes, nothing more starts, and Hydranos logs stop requested during startup; flushing and leaving, sends the departures, flushes and exits.

HYDRANOS_STOP_TIMEOUT (default 120) bounds the flush: past it, Hydranos stops waiting, logs shutdown flush hit HYDRANOS_STOP_TIMEOUT; leaving with what is saved (budget_s=…) and exits with what is written; each engine's state.db commits per transaction, so what was written stays written. Accepted forms: 120, 60s, 2m, 1m30s, 1h (units largest first, each once). Anything else (30s1m, 1.5m, -5, empty) is refused at startup with WARN HYDRANOS_STOP_TIMEOUT="…" is not a duration (use 120, 60s, 2m or 1m30s); using 120 s. 0 means leave without waiting for the flush. The value is read once, at startup.

A stop takes at most about 5 s (drain) + 5 s (departures) + HYDRANOS_STOP_TIMEOUT, i.e. 130 s by default. The supervisor's limit must be above that, or it kills the flush:

If you raise HYDRANOS_STOP_TIMEOUT for a large catalogue, raise the supervisor's limit with it. Measure your own flush time after a stop:

docker logs hydranos 2>&1 | grep "shutdown flush"     # Docker
journalctl -u hydranos | grep "shutdown flush"        # systemd

On Windows, the log is hydranos.log in the config dir: findstr /C:"shutdown flush" C:\Hydranos\hydranos.log.

If you see SIGTERM received… but neither shutdown flush complete nor shutdown flush hit HYDRANOS_STOP_TIMEOUT before the process dies, the supervisor killed it first: its limit is below HYDRANOS_STOP_TIMEOUT + 10 s.

• Array stop. Stopping the array (or the Docker service) stops every container; whether Unraid honours the container's --stop-timeout there is not tested by the maintainer. Stop the hydranos container yourself on the Docker tab first, wait until it shows stopped, then stop the array. No shutdown flush line in docker logs hydranos means the flush was cut.
• Behind gluetun (network_mode: "service:gluetun"): stop hydranos before gluetun. If gluetun is restarted or updated, hydranos keeps a dead network namespace (no network, no web UI) until you restart it too (Docker behaviour, not tested by the maintainer). Recipe: VPN and Egress.

Several controls restart Hydranos: Restart now (banner on the Nodes tab after an engine change), Apply & restart or Apply and restart (after saving a setting that needs it, e.g. on the Network tab), Save and restart (Duplicate data card, and the leave-page dialog), and Reset and restart (see Resetting settings below). The same happens with POST /api/restart and POST /api/settings/restart.

The daemon answers the request first ({"ok":true,"restarting":true} or {"status":"restarting"}), then, 500 ms (/api/restart) or 300 ms (/api/settings/restart) later, logs restart requested via API: stopping cleanly, then exiting for the supervisor (or restart requested from settings: …) and goes through the clean stop above: drain, departures, flush, tunnels down. It then logs restart: exiting with code 75 for the supervisor and exits with code 75 (EX_TEMPFAIL), not 0, so that a supervisor that restarts on failure brings it back.

flowchart TD
    A["Restart control in the UI,<br/>or POST /api/restart or /api/settings/restart"] --> B["clean stop: drain, departures,<br/>resume flush, tunnels down"]
    B --> C{"What started hydranos?"}
    C -->|"Windows, any launch"| W["starts its successor with the same arguments,<br/>then exits with code 75"]
    W --> UP["Hydranos runs again"]
    C -->|"Linux or Docker"| E["exit code 75"]
    E --> D{"Supervisor policy"}
    D -->|"Docker restart: unless-stopped, always or on-failure"| UP
    D -->|"systemd Restart=on-failure - the shipped unit - or always"| UP
    D -->|"Docker without a restart policy, or started by hand in a shell"| DOWN["stays stopped"]

• Windows: nothing supervises the process, so before exiting it starts its successor itself (restart: successor started; on failure ERROR restart: cannot start the successor: …, and nothing comes back: start it yourself).
• Windows under a service wrapper (NSSM): the successor starts outside the wrapper, and the wrapper sees code 75 and may start another one: two instances, one of which fails to bind the port, the other unsupervised. Deduced from the code, not tested. Under a service, restart through the service, not with the UI's buttons.
• After Apply & restart the page reloads 7 s later (Restart now says to reconnect in about 40 s); during a long flush it may show a connection error until Hydranos is back: reload it then. Once the port is open again you get the startup screen below.

docker restart and systemctl restart send SIGTERM, so they go through the same clean stop (exit code 0, then the supervisor starts it).

Since 4.4 the port opens in the first second (INFO hydra API listening (starting) addr=…), before the catalogue loads: a port already taken fails at once. Until the engines are loaded and the store is open, only a startup surface answers:

• / shows the startup screen: the logo, HYDRANOS, a phase line (Initializing…, then Restoring state…, Connecting to the network…, Opening the database…, Starting…), a bar and <restored> / <total> torrents. It polls /api/startup every 500 ms and fades out when the daemon is ready. The total only counts engines that have started reading, so the bar can step back once per engine.
• /health answers 200 with "status": "starting", /metrics a reduced set, /api/startup the progress.
• Everything else (the API, login, the qBittorrent-compatible /api/v2/*, /mcp) answers 503 with Retry-After: 5 and Hydranos is starting (<phase>): <restored> of <total> torrents restored.

The end of the start is INFO hydra API ready. If the store does not open, the phase becomes rescue and the page reloads into Rescue mode below. Details: Monitoring and Logs.

A crash, a power cut, kill -9, End task or a SIGKILL from a supervisor skips the flush. Each engine then starts from its last saved resume state:

Rechecks after a crash are normal and limited to the affected torrents. Details: Architecture.

Hydranos has no backup feature in 4.4 (no button, endpoint or scheduled copy; backups are the operator's job, as in other BitTorrent clients). You copy the files below yourself. The payload (the files in your save paths) is yours to back up separately; Hydranos does not copy it.

<config dir> is the folder holding default.toml; <data dir> is [daemon] data_dir. They are the same folder only in Docker.

Hydranos writes a starting config, with data_dir set to data beside it, only when the config file does not exist. When in doubt, read data_dir in your default.toml: it is authoritative.

The recommended recipe, on every platform. hydra.db and every state.db must be copied at the same moment and complete (with their -wal files): a stopped Hydranos guarantees both, and its clean stop has just written the latest resume state.

# Docker (compose project in /srv/hydranos, /config mounted from ./config)
cd /srv/hydranos
docker compose stop hydranos
tar czf /backup/hydranos-$(date +%F).tar.gz config
docker compose start hydranos

# Linux, packaged layout
sudo systemctl stop hydranos
sudo tar czf /backup/hydranos-$(date +%F).tar.gz /etc/hydranos /var/lib/hydranos
sudo systemctl start hydranos

• Unraid or a NAS: stop the container in the Docker tab (or the NAS's container manager), copy the whole folder mounted as /config with any file tool or backup app, start the container.
• Windows: tray › Quit Hydranos, wait for the tray icon to disappear, then copy the config dir (and the data dir if it is elsewhere) with Explorer, or in cmd: robocopy C:\Hydranos D:\Backup\Hydranos /E. Start Hydranos again. No tar or sqlite3 needed.

On a network share (Unraid /mnt/user, NFS, SMB) the store keeps SQLite's rollback journal and has no -wal file; the recipe is the same.

Possible when you cannot stop Hydranos, with the sqlite3 tool on the host (it is not in the Docker image) and the files on a local disk (WAL mode). Each copy is consistent for its own file.

# Docker layout: hydra.db and the engine folders in ./config; run as the owner of the files
cd /srv/hydranos/config
mkdir -p /backup/hydranos-$(date +%F)
cp default.toml /backup/hydranos-$(date +%F)/
sqlite3 hydra.db ".backup '/backup/hydranos-$(date +%F)/hydra.db'"
for e in race hoard; do       # every engine id
  mkdir -p /backup/hydranos-$(date +%F)/$e
  sqlite3 $e/state.db ".backup '/backup/hydranos-$(date +%F)/$e/state.db'"
done

What it does not give you, compared with a stopped copy:

• The store and the state.db files are taken at different moments. A torrent added or removed between two copies may be missing after a restore (see Restoring: skipped at load, or its store row dropped by the reconcile). Copy them back to back, at a quiet time.
• state.db holds the resume state of the last periodic save (every 300 s): after a restore, recent pieces are checked again.
• On a busy store, .backup starts over each time Hydranos writes during the copy; sqlite3 hydra.db "VACUUM INTO '/backup/…/hydra.db'" reads one snapshot instead.
• On a network share (rollback journal) or on Windows, use the stopped copy.

• <config file>.bak-reset-<unix time>: the previous config, written by Reset to defaults (see below).
• hydra.db.bak-preconvert-<unix time>: the store before a rescue-mode conversion (see Rescue mode).

They are not deleted automatically.

The store and the engines' resume state must come from the same backup. At start, each engine loads the torrents listed in its state.db and takes their .torrent from the store; then, right after store open and every 5 minutes, a store reconcile compares, engine by engine, the store's rows with the torrents the engine loaded:

• older store, newer state.db: a torrent the store has no row for is skipped at load (WARN [resume] skip …: no metainfo in the store) unless <data dir>/uploads/<hash>.torrent exists (installs carried over from 3.x): it is then imported into the store first. Add skipped ones again.
• newer store, older state.db: the store has rows for torrents the engine did not load. The reconcile treats them as leftovers of a removal and deletes them, .torrent included, when their number is at most max(rows of that engine in the store ÷ 100, 50); one line at INFO: store reconcile: rows without a torrent removed engine=… dropped=N. Above that ceiling it deletes nothing and logs at WARN store reconcile: refusing to drop that many rows at once (would_drop, of), and refuses again every 5 minutes. An engine that loaded no torrent at all (missing state.db) is skipped, so its rows are kept.

At 1 million rows that ceiling is 10,000 torrents, and those .torrents exist nowhere else. The reconcile deletes only that engine's row: a copy of the same torrent held by another engine keeps its own. Rows of records the loader refused (their .torrent on disk is a different torrent) are kept too (store reconcile: rows kept for records the loader refused).

Procedure:

1. Stop Hydranos and keep it stopped.

2. Put default.toml back at the path you start Hydranos with. If the new machine uses other paths, fix data_dir in it.

3. Put hydra.db back in the data dir. Delete any hydra.db-wal and hydra.db-shm already there unless they come from the same backup: a stale -wal next to another copy of the file corrupts it.

4. Put each engine folder back as <config dir>/<engine id>/ with its state.db (same rule for state.db-wal / -shm), from the same backup as hydra.db. The folder name must equal the engine id in the config (race, hoard, or the id of an extra engine): an engine whose folder is missing or renamed starts empty.

5. Make the save paths exist at the same paths as before (same mounts in Docker).

6. Fix ownership: Docker PUID/PGID user, or hydranos:hydranos on the packaged Linux layout.

7. Keep a copy of the restored hydra.db aside, outside the data dir. If the reconcile deletes rows anyway, their .torrent is still in that copy.

8. Optional, if you have the sqlite3 CLI on the host: count, per engine, store rows that have no state.db row (a lower bound of what the reconcile may delete). Any result other than 0 means the files do not match; 0 does not rule out rows dropped because their .torrent fails to parse.

   cd /srv/hydranos/config      # the folder holding hydra.db and the engine folders
   for e in race hoard; do
     sqlite3 hydra.db "ATTACH '$e/state.db' AS s; SELECT '$e', count(*) FROM torrents WHERE session = '$e' AND info_hash NOT IN (SELECT lower(info_hash) FROM s.torrent_state);"
   done

9. Start, and check the log: one engine state loaded line per engine with torrents=… (compare with the counts you had before), no [resume] skip lines, engines up, store open, hydra API ready, and no store reconcile: rows without a torrent removed line.

bench.db can be restored or left out (the Benchmark tab then starts empty).

If hydra.db cannot be opened, or its torrents table lacks columns, Hydranos logs the store could not be opened: <why> -- starting in rescue mode at ERROR and serves a minimal surface on the listener already open, so on your api_host and api_port (default 0.0.0.0:8199). The web UI is not served: http://<host>:8199/ answers the text hydra: the store could not be opened (a startup screen still open in a browser reloads into it). The engines were started before the store was opened and keep running (Architecture).

Rescue mode asks for no API key: anyone who reaches the port can run the conversion and the restart. Keep the port reachable only from trusted hosts, as for the normal UI.

The web UI contains a Hydranos cannot open its database screen with a Back up and convert button, but in 4.4 it never appears: rescue mode does not serve the UI, and the normal API always reports no repair needed. Use the routes directly:

curl http://127.0.0.1:8199/api/store/repair
curl -X POST http://127.0.0.1:8199/api/store/repair

The only repair is for a store in WAL mode on a network filesystem (needed = on_network and in_wal). On Linux "network" means NFS, SMB/CIFS or FUSE (mergerfs, Unraid /mnt/user); on Windows a UNC path or a mapped network drive. It typically happens when a store created on a local disk is moved to a share.

flowchart TD
    A["POST /api/store/repair<br/>(rescue mode only)"] --> B{"on a network filesystem and in WAL?"}
    B -->|no| S["returns the diagnosis, changes nothing"]
    B -->|yes| C["copy hydra.db to hydra.db.bak-preconvert-unix time"]
    C -->|"copy failed"| E5["500, nothing changed"]
    C -->|"copy done"| D["PRAGMA journal_mode=DELETE"]
    D -->|ok| OK["200, method pragma"]
    D -->|"failed, WAL file empty"| H["rewrite header bytes 18-19,<br/>delete -wal and -shm"]
    H -->|ok| OK2["200, method header"]
    H -->|"write failed"| E6["500, backup kept"]
    D -->|"failed, WAL file holds data"| E4["409, store left untouched"]

After a successful conversion, restart: curl -X POST http://127.0.0.1:8199/api/settings/restart exits with code 75, which brings Hydranos back under Docker with a restart policy, under the shipped systemd unit (Restart=on-failure), and on Windows (successor); or restart through your supervisor (docker restart hydranos, sudo systemctl restart hydranos). On a 409, the -wal still holds commits: move the files back to a local disk, start Hydranos there once and stop it cleanly, then move them again; or better, keep data_dir on a local disk.

For any other cause (permissions, disk full, damaged file), POST /api/store/repair does nothing: fix the reason given in the log, or restore from a backup (Restoring).

In rescue mode a SIGTERM (or Ctrl+C) still stops the HTTP server gracefully and the process exits with code 0, but without departures or resume flush: the engines' state is the last periodic save. Deduced from the code, not tested.

Read the release notes first in the changelog. The Changelog tab (and /changelog.md) shows the changelog compiled into the version you are running, so it does not list the new release. Take a backup (stopped copy) before every update: it is also your way back.

Pin a version tag and change it to update:

cd /srv/hydranos
# edit your compose file: image: ghcr.io/kheopsian/hydranos:v4.4.0 → the new tag
docker compose pull
docker compose up -d

up -d stops the old container with your stop_grace_period (clean stop), then starts the new image on the same /config. Nothing in the container updates itself. Unraid: change the tag in the Repository field and Apply. Details: Docker.

hydranos-update downloads the release archive for your architecture from github.com/Kheopsian/Hydranos releases, checks its SHA-256 against the .sha256 published beside it, and replaces the binaries.

sudo /opt/hydranos/hydranos-update --dir /opt/hydranos --config /etc/hydranos/default.toml --check
sudo /opt/hydranos/hydranos-update --dir /opt/hydranos --config /etc/hydranos/default.toml   # download, verify, ask, replace
sudo systemctl restart hydranos

• Nothing is replaced when the download fails, the .sha256 is missing (refusing to install unverified bytes) or the checksum differs (checksum mismatch -- nothing replaced).
• It replaces only hydranos and hydranos-update already in --dir (the archive has no hydranos-engine; an old one left in the folder is not touched); config, store, engine folders and log are never touched.
• On Linux it does not restart anything (note: restart the service for the new binaries to take effect).
• packaging/install.sh installs hydranos-update beside hydranos in /opt/hydranos (Linux (bare metal)).

Without the updater: download and verify the new tarball, unpack it, run sudo ./install.sh again (it keeps the config), then restart.

Tray › Check for updates opens a cmd window running hydranos-update.exe --dir <folder of hydranos.exe>; same options and checks as above. After you answer y, the updater asks the running Hydranos to stop through a named event (Local\HydranosStop), the same clean stop as Quit Hydranos, waits up to 60 s for hydranos.exe to exit, replaces the files and prints updated to <tag>. Start hydranos again. If the stop takes longer than 60 s (a flush close to HYDRANOS_STOP_TIMEOUT), it prints hydranos is still running after 60s -- stop it yourself, nothing was replaced: wait for the tray icon to disappear and run it again. A daemon older than 4.4 has no such event: quit it from the tray first. The step-by-step is on Windows.

When a newer version exists, an update vX.Y.Z link appears next to the version in the header. The server reads the first 100 tags of github.com/Kheopsian/Hydranos (not the releases) and keeps a successful answer for 6 hours. A failure (no network, rate limit, 5 s timeout) means "no update" and is not kept, so the server asks GitHub again on the next request. Turn it off with update_check_disabled = true in [daemon].

The badge only informs: nothing is downloaded or applied by the daemon. Coming from 3.x, read Upgrading from 3.x first.

Config tab › Advanced settings (default.toml) › toolbar button Reset to defaults › Reset and restart:

1. The current config is copied to <config file>.bak-reset-<unix time> next to it (e.g. /config/default.toml.bak-reset-1759600000).
2. default.toml is replaced by the shipped template, keeping only your admin login (username, password_hash), api_key and data_dir (non-empty strings only).
3. Hydranos restarts through the clean stop of Restart from the UI (exit code 75).

Everything else goes back to defaults: ports (16171 race, 16172 hoard), tracker overrides, engine tuning, queue, share and speed limits, the network mode, kill switch, proxy and managed WireGuard settings (the provider files in <data dir>/wireguard/ stay), and extra engines (their folders stay on disk, but they are no longer started). The store (categories, workflows, RSS feeds and rules) and the resume state are not touched. To undo: stop Hydranos, copy the .bak-reset-… file over default.toml, start.

The Personalisation card on the same tab has a button with the same label, Reset to defaults: it only resets the theme and the hidden tabs in this browser and touches nothing on the server.

Signed in, change it under Config › Account › Change password (8 characters minimum; applies at once). Locked out, set a new one on the host with hydranos reset-password <password> [path/to/default.toml], then restart:

# Docker (config at /config/default.toml inside the container; pass the path if you changed HYDRANOS_CONFIG_DIR)
docker exec hydranos hydranos reset-password 'new-password-here'
docker restart hydranos

# Linux, packaged layout
sudo /opt/hydranos/hydranos reset-password 'new-password-here' /etc/hydranos/default.toml
sudo systemctl restart hydranos

On Windows: hydranos.exe reset-password "new-password-here" in cmd in the folder of hydranos.exe (the default config is the one beside it), then Quit Hydranos and start it (not tested on Windows).

• It writes a bcrypt [auth] password_hash into the file, checks that the file still parses, prints hydranos: password set in <path>. Restart Hydranos for it to apply. and exits. The running daemon keeps the old hash until the restart; username and api_key do not change.
• Without a path it uses /config/default.toml (Windows: default.toml beside hydranos.exe, or the \config\default.toml a 4.3 install left when there is none there). Refusals: fewer than 8 characters (hydranos: the password must be at least 8 characters, exit 2), a file it cannot read or write, or an edit that would not parse (… would not parse after the edit; nothing written).
• The password is a command-line argument: it stays in your shell history and shows in ps while the command runs.

hydranos hash-password <password> only prints a bcrypt hash, for editing password_hash by hand. More on accounts and keys: Security and Access.

• Monitoring and Logs: /health, /metrics, the log file and the Logs tab.
• Troubleshooting: symptoms and fixes.
• Docker, Linux (bare metal), Windows: platform specifics.
• Architecture: startup order, files on disk, crash safety.
• Upgrading from 3.x.