Deployment Topologies

Deployment Topologies

Hydra runs in three shapes. All three speak the same UI/API; the difference is where the engines live.

Monolith (default)

One process, race + hoard local. Simplest, one container. Use it whenever you control real inbound ports (home router forwarding, or a VPS): race and hoard each bind and forward their own port.

Agent (--agent-only)

A headless node hosting one or more engines, exposed over gRPC (token + TLS) for a remote front to drive. No local UI. Used to place engines on other machines.

Front-only (--front-only)

A UI/controller with no local engine. It dials remote agents and aggregates them into one dashboard, one torrent list, one add/route surface.

Sharding a monolith

A monolith can also register remote agents and add extra local engines to spread load — via the UI (Agents → Local engines) or [[engine]] blocks in the config. Each engine has an id and a role (race/hoard); you can run, say, one race + several hoards on one box.

Choosing a deployment

• You control real inbound ports (home router, or a VPS) → monolith. race and hoard each forward their own port. One container, done.

• You're behind a VPN that forwards a single port (gluetun + Proton / PIA / …) → do not cram both engines behind one tunnel (one port can't serve two engines). Instead:

  • a front-only controller, plus
  • one --agent-only per engine, each in its own gluetun, so each engine gets its own forwarded port.

  Each agent's gluetun UP_COMMAND pushes its rotated port to its local engine (hydra set-listen-port …), and the front-only node aggregates and drives them from one UI. This is the recommended way to seed over single-port VPNs without losing inbound on either engine.

See Categories and Routing for how new torrents get placed across engines/agents.