Contribution guide
Keep the weights alive
Every mirrored model ships as a BitTorrent swarm, and swarms live or die by their seeds. The seeder daemon turns spare disk into durable hosting: it downloads the models the network needs most, verifies every file against an anchor-signed manifest, and keeps them online. This page walks you from zero to seeding โ and explains how the flock recognizes the people who do it.
Before you start
- A machine that stays on โ a home server, NAS, or VPS โ with Docker. (No Docker? See without Docker below.)
- Spare disk. Even 50 GB helps; the daemon never exceeds the budget you set.
- Comfort with the trade-offs of public swarms: peers can see your IP address, and you are redistributing models under their listed licenses.
Start seeding in three steps
Run it
# One command. The first run prints a link โ approve it in your browser, then it seeds.
# Disk budget is a cap: the box fills it from the need queue, thinnest swarms first.
docker run -it --name duckweights --restart unless-stopped \
-v duckweights:/data -p 6881:6881 -p 6881:6881/udp \
ghcr.io/vinnychase28/duckweights-seeder join --disk 200GB
# Already downloaded it from Hugging Face? Mount the cache and add `--adopt /hf`:
# -v ~/.cache/huggingface:/hf โฆ join --disk 200GB --adopt /hf
# Matching files are hash-checked and seeded in place instead of downloaded again.The image bundles the torrent engine, so there is nothing else to install. Everything the box remembers โ its sign-in, its torrents, the weights โ lives in the duckweights volume; the container itself is disposable. Ctrl-C stops it; docker start duckweights brings it back in the background.
Approve it in your browser
On first run the terminal prints a link and a short code like DUCK-7K2M4Q. Open the link while signed in, check the device name, and approve. That mints a personal read token for the box โ it can send heartbeats and read public torrent data, and can never publish or modify anything. Revoke it any time under Settings โ Access tokens.
Watch it appear
The daemon reads the need queue โ official torrents ranked by fewest seeds โ fills your disk budget starting with the most fragile swarms, verifies every file's SHA-256 against the signed manifest, and seeds. Within a few minutes your box appears under Settings โ Seeding and on the flock leaderboard. From then on it heartbeats on its own; there is nothing to babysit.
Advanced: without Docker
The CLI is on PyPI as duckweights-seeder. It needs Python 3.11+ and a running qbittorrent-nox whose WebUI listens on localhost:8080 (set QBT_URL, QBT_USERNAME and QBT_PASSWORD if yours differs). login does the same browser approval as the container; the token lands in ~/duckweights-seeder/credentials.json. Prefer to manage tokens yourself? Mint one under Settings โ Access tokens and export it as DUCKWEIGHTS_TOKEN instead.
# Needs Python 3.11+ and qbittorrent-nox with its WebUI on localhost:8080
uv tool install duckweights-seeder # or: pipx install duckweights-seeder
duckweights-seeder login # opens the browser, saves a read token
duckweights-seeder join --disk 200GB
# Already downloaded it from Hugging Face? Add --adopt ~/.cache/huggingface
# to hash-check and seed those files in place instead of downloading again.Points and badges
Seeding credit is measured in GiB-hours: one point for every GiB of verified weights you keep online for an hour. Thin swarms pay more โ the fewer seeders a torrent already has, the more each of those hours is worth โ so filling from the need queue is the fastest way to climb. Points accrue automatically from your daemon's heartbeats; 100 GB on a typical swarm earns roughly 2,400 points a day. Your badge appears next to your name on your profile and on every comment you post.
Coming soon: verified seeders will also receive free playground allowance. Use it to try newly added Chat models before deciding whether their weights belong on your disk. Seeding points and playground allowance remain separate rewards.
| Badge | Points | Roughly |
|---|---|---|
| Duckling | 0+ | Your first heartbeat โ welcome to the flock |
| Paddler | 500+ | 100 GB kept online for ~5 hours |
| Keeper | 25,000+ | 1 TB kept online for a day |
| Flight Leader | 500,000+ | 1 TB kept online for ~3 weeks |
Questions people ask
- Is this safe to run?
- The daemon can only serve files whose hashes match the anchor-signed manifest, and its token cannot write anything to the catalog. The usual BitTorrent caveats apply: swarm peers see your IP, and your ISP sees BitTorrent traffic.
- What decides which models my box seeds?
- The join daemon fills from published torrents with the fewest seeds โ those are also the ones that pay more points. The flock page's need list is the other half: the most-downloaded Hugging Face chat and vision models we have not hosted yet, from 1B laptops up to Flash-class workstations.
- I already downloaded it from Hugging Face. Do I have to download it again?
- No. Point the daemon at your cache with
--adopt ~/.cache/huggingface(in Docker, mount it:-v ~/.cache/huggingface:/hfand--adopt /hf). Every file whose SHA-256 matches the signed manifest is hardlinked into the seeding folder โ a copy when the mount is read-only or on another disk โ qBittorrent rechecks it, and only the missing pieces come from the swarm. Files that do not match are simply ignored; the box can still never serve anything the manifest does not vouch for. Plain folders work too when you name the model:--adopt ./Qwen3-0.6B --repo Qwen/Qwen3-0.6B. - Do downloads earn points?
- No โ points reward availability, not traffic. What counts is verified GiB kept online, measured between heartbeats. Seeder scarcity is the other lever: a quiet box on a thin swarm out-earns the same disk on a crowded one.
- How do I stop?
- Stop the daemon and delete its data directory (
docker rm -f duckweights && docker volume rm duckweights). Your box drops off the leaderboard after 15 minutes; the points you earned are yours to keep. Revoke its token under Settings โ Access tokens if you want to be sure.