Run a fleet of BitTorrent seed boxes as one cluster.
A central Control Plane places torrents on the right machine, keeps every Seed Node healthy and tells you what needs attention — from a single web Portal.
English · Português
Seeding from one machine is easy. Seeding thousands of torrents across a few machines — a mini PC, a NAS, a Raspberry Pi with a USB disk — turns into chores: which box has room, which disk is failing, which torrent stalled, which one should move. SeedGrid does that bookkeeping for you:
- One cluster, not N boxes. Add a torrent once; the Scheduler puts it on a Node that has the disk for it. Moving it to another Node later is one click, verified at the destination.
- It notices before you do. Node offline, disk filling up, storage unmounted, a Node nobody can reach from outside — alerts in the Portal and, if you want, on Telegram, Discord or a webhook.
- Built for private trackers. It shares your account's download slots across the cluster and publishes to UNIT3D sites with the site's own categories, wording and image host.
flowchart LR
op(("Operator")) --> portal["Portal<br/>(React)"]
portal -- "HTTP API" --> cp["Control Plane<br/>(Go)"]
cp --> db[("PostgreSQL")]
cp <--> prom["Prometheus +<br/>Alertmanager"]
cp -. "notifications" .-> chat["Telegram · Discord · webhook"]
cp -. "publish" .-> trk["UNIT3D trackers"]
subgraph n1 ["Seed Node"]
a1["Agent<br/>(Go)"] --> q1["qBittorrent"]
end
subgraph n2 ["Seed Node"]
a2["Agent<br/>(Go)"] --> q2["qBittorrent"]
end
a1 -- "heartbeat · inventory · commands" --> cp
a2 -- "heartbeat · inventory · commands" --> cp
The Control Plane decides, the Agent executes, the Portal shows. Agents always call the Control Plane — never the other way around — so a Node behind NAT or a firewall just works: it sends its heartbeat and inventory, and picks up its commands (add, pause, migrate, update) from a durable queue. Only the Control Plane touches the database, and the Portal only talks to the API.
 |
 |
| Health & Metrics — per-Node disk, I/O, network and peers, with one-command onboarding of new Nodes. | Alerts & Events — what needs attention now, and what happened, in your language. |
 |
 |
| Analytics — throughput, rankings and duplicates across the cluster. | Settings — every tunable live, with per-Node overrides. |
- Zero-touch Nodes: one command on a new machine and it joins the cluster.
- Disk-aware scheduling and migration between Nodes, verified at the destination.
- Admission control that shares a tracker's download slots and rotates stalled downloads.
- Agent self-update from the Portal.
- Publishing to UNIT3D trackers with shareable site profiles.
- English and Brazilian Portuguese — the Portal, the alerts and the docs.
You need one Linux host with Docker for the Control Plane and one per Seed Node (a server, a VM, a mini PC or a Raspberry Pi).
# 1. On the Control Plane host
git clone https://github.com/rbferreira/seedgrid.git /opt/seedgrid && cd /opt/seedgrid
sh scripts/bootstrap-controller.sh # creates the secrets, starts everything, prints the Portal URL
# 2. On each Seed Node — the Portal gives you this line, token included (Health & Metrics → Add Node)
curl -fsSL http://<control-plane>/node/bootstrap-node.sh | sudo CP_URL=http://<control-plane> JOIN_TOKEN=<token> sh
# 3. Check the whole setup end to end
sudo sh scripts/acceptance.shUpdating is git pull && git fetch --tags && sh scripts/bootstrap-controller.sh on the Control
Plane host; Nodes update from the Portal. Opening the BitTorrent port (a port forward on IPv4, or inbound IPv6) is
up to you — SeedGrid tells you which port each Node uses.
Everything else — topology, environment variables, networking, upgrades — is in Deployment.
- Index — start here
- Architecture and ADRs — why it is built this way
- API
- Site profiles — how to add a tracker, even without running SeedGrid
All docs exist in English and Brazilian Portuguese.
Repository layout
control-plane/ the Control Plane (Go): API, Scheduler, workers, migrations
agent/ the Agent (Go): runs on each Seed Node, drives the Torrent Engine
portal/ the web Portal (React + Tailwind)
shared/ contracts shared by the three (settings, messages, Agent config)
profiles/ site profiles for trackers, one file per site
deploy/ Docker Compose files for the Control Plane, the Nodes and observability
scripts/ bootstrap, build and acceptance scripts
tools/ the project's policy checks, run by CI
docs/ the documentation — the source of truth
SeedGrid is young (0.x) but runs a real cluster every day. Publishing is tested end to end with one UNIT3D site; other UNIT3D sites share the same API and should work — if you try one, open an issue and contribute its profile.
Issues and pull requests are welcome — see CONTRIBUTING. Security issues go through private reporting.