Kubespider: a download orchestration layer bolted onto your NAS

Turning an idle home server into a download centre

Kubespider began as a personal fix. The README describes its origin plainly: an idle server on a local network gets pressed into service as a NAS, and from there the project grew into what the maintainers call a global resource download orchestration system. The repository description says it plainly too, build your home download centre. It is a self-hosted tool for people who want to hand a machine one URL and let it work out which adapter can turn that into something Aria2 or qBittorrent will accept, then queue the transfer and put the file in the right folder.

The design assumption is that you already own the storage and the download clients. Kubespider is not a media server and it is not a tracker. It is the layer that decides what to fetch and hands the work to the program that is good at fetching. The stated trigger modes are a request trigger, a cycle trigger, and an update trigger, which is a way of saying that a task can arrive on demand from the browser, arrive because a scheduled series provider noticed a new episode, or arrive because something the provider watches has changed. Language is Python, licence is Apache-2.0, and the topics list names the ecosystem it plugs into: aria2, qbittorrent, magnet, torrent, docker, nas, synology, qnap, asustor, terramaster.

Three modules and two YAML files

The architecture section splits the system into three pieces, and the split is the single most useful thing to understand before you configure anything. `kubespider-core` accepts a trigger, asks a resource provider to resolve it into a standard form, then calls a download provider to do the transfer. The README makes the normalisation concrete with an example: a user pastes a bilibili blogger page and the corresponding provider outputs the list of MP4 download addresses for that blogger's videos. Separately, the core also calls providers on a schedule, so a TV series provider can pull new episodes without anyone asking.

`source-provider` is the adapter for each resource website. It accepts a general resource address and returns standard URLs, and its configuration lives in `.config/source_provider.yaml`. `download-provider` is the adapter for each piece of download software. It receives the task from the core and calls the matching service, configured in `.config/download_provider.yaml`. Because both sides are file-driven, adding a site means writing a source provider and pointing it at a config entry, and adding a new client means writing a download provider. That is the extension seam, and it is also why the requirements file pulls in such a wide set of libraries: `aria2p==0.11.3`, `qbittorrent-api==2023.7.52`, `transmission-rpc==4.3.0`, and `telepot==12.7` all sit in the same dependency list because the project speaks to all of them from one core.

The top-level tree confirms the shape. Alongside the `kubespider/` package there are `downloaders/`, a `chrome-extension/` and a `kubespider-extension/`, a `Dockerfile`, a `docker-compose.yml`, a `hack/` directory holding the install scripts, and `docs/` with a `mkdocs.yml` at the root. Configuration lives in a `.config/` directory that ships with the repository and is mounted into the container rather than baked in.

The bundled install script and what it tells you

The documented install path is three commands, and the script does more than clone a repo:

# Define KUBESPIDER_HOME to specify the installation path
# export KUBESPIDER_HOME=xxx
git clone https://github.com/opennaslab/kubespider.git
cd kubespider
bash hack/install_kubespider.sh

Running it deploys with the default configuration, which the README explains installs Kubespider and Aria2 together as the default downloader. It then prints a summary block, and that block is the most useful output in the whole project because it names every path and address you need later. The config path lands in `/root/kubespider/.config/`, downloaded files land in `/root/kubespider/nas/`, the webhook listens on `http://<server_ip>:3080`, and Aria2 answers on its JSON-RPC endpoint at `http://<server_ip>:6800/jsonrpc`. The block also states plainly that the Aria2 default secret is `kubespider`, which is fine on a home LAN and worth changing if the host is ever reachable from anywhere else.

The README frames this as the default install with Docker and lists three premises: your computer and the server share the same LAN, the server is Linux, and Docker is installed. The author is candid about the first one, noting they have not tried installing outside the same LAN. If you want to see what the Aria2 endpoint is doing, the README suggests the AriaNg Chrome extension or the AriaNg desktop program; if you want to submit tasks by hand, it points at the Kubespider Chrome plugin configured against `http://<server_ip>:3080`, which lets you right-click a link and send it to the server. The compose file is a development setup, and its `server` service runs `network_mode: host`, which is a useful clue about how the webhook address becomes reachable.

Where files land and how triggers reach the core

Storage and configuration both follow `${HOME}/kubespider` by default, with `nas` for downloads and `.config` for YAML, and both are volumes mounted into the container rather than living inside the image. The Dockerfile makes the runtime assumptions explicit: it builds from `python:3.11-alpine`, installs nodejs, npm, bash, su-exec, tzdata and shadow, then creates a dedicated `kubespider` user with uid and gid 911 and sets `TZ=Asia/Shanghai` as the default timezone. That last detail matters more than it looks, because a lot of the source providers are regional and will misbehave if the clock is off. The `HOME` environment variable is set to `/app` inside the container, which is why the `${HOME}` paths expand cleanly whether you run the script on the host or the image elsewhere.

Triggers reach the core through a small number of surfaces, and the README names three of them. A browser extension is the most obvious, sending a task straight to the webhook address. A Telegram path is real, though it is documented in the release notes rather than the README: the v0.7.0 changelog records adding a Telegram bot, fixing the Telegram download trigger, and keeping the original URL that was received, so you can trace a task back to what you actually asked for. Cycle and update triggers are the scheduled kinds, driven by the core polling providers such as the TV series provider. The webhook is a plain HTTP endpoint on port 3080, and nothing in the documentation describes authentication on it, which is the second reason to keep this on a trusted network.

Plex and Jellyfin are both offered as optional next steps, each behind its own installation document, and Baidu netdisk support is listed as available in China only. The Plex and Jellyfin pages are where the project hands off to the media-server side of the setup, and neither is part of the core.

What the release history reveals about direction

The tag history is short and recent enough to be readable. v0.7.0 shipped on 2024-06-26, v0.6.2 on 2024-03-17 with a single bugfix for the yutto downloader failing to recognise a URL from the app, and v0.6.1 on 2024-03-12. Each release body carries the same three-line install snippet pointing at a tarball for that tag, so installing a specific version means wget-ing the archive and running `hack/install_kubespider.sh` from the extracted directory rather than cloning main.

The v0.7.0 list is the best single view of what the maintainers were actually working on, and it is mostly plumbing rather than new sources: a repository-management config, an alist download bugfix, bilibili short URL support, several documentation passes, a mikanani README correction, and a change titled cleanup: install the latest release version. That last one pairs oddly with a setup.py that declares `version='latest'` as a literal string. The same pattern shows up in the dependencies, which are pinned to exact patch versions such as `flask==2.3.3` and `watchdog==3.0.0`, so the pinning discipline is applied to libraries but not to the project's own version field. If you are packaging Kubespider rather than cloning it, that literal is the thing to notice.

GitHub reports a push on 2026-04-14, which is recent enough that the project is not sitting abandoned, and the repository is not archived. Stars sit at a little over two thousand with 122 forks and 37 open issues. The gap between the last release in mid-2024 and continued commits afterwards is the honest tension in the timeline: development continues, but the release tags stopped moving.

Where the README stops and the docs take over

The English README is cut off partway through its installation section, ending on the line Install Kubespider on Synology, s. That is a real limit on what can be said from the front page alone, and it is worth naming rather than glossing. Several installation paths are therefore visible only as links: a manual route using docker-cli and docker-compose, the Synology path whose documentation exists but is not described in the README text, and the Plex, Jellyfin and Baidu netdisk guides. The Chinese README is linked alongside the English one, and the documentation site is a MkDocs build configured at the repository root.

What the front page does settle is enough to make a decision. If you run a Linux box with Docker on your LAN and you already use Aria2, qBittorrent or Transmission, the default install gives you a webhook, a scheduled provider loop, and a browser hand-off, with files landing in one predictable directory. If you need Plex or Jellyfin wired up next, or you are installing onto a Synology NAS rather than generic Linux, you are moving into the linked documentation and out of what this README covers. The topic list names synology, qnap, asustor and terramaster explicitly, so the project clearly aims at those devices, but the README itself only promises the generic Linux and Docker path, and it says the author has not tried the setup outside a single LAN.

Editorial conclusion

Kubespider earns its keep on the specific problem of turning scattered website links into queued downloads on a machine that already has storage and clients, and the core plus two-provider split is a clean way to extend it to sites nobody has written an adapter for yet. What the repository does not settle is how much of the media-server story is your job after install: Plex, Jellyfin, Baidu netdisk and Synology installs live behind separate documentation links, and the last of those README lines breaks off mid-sentence, so budget time for the gap. Begin with the bundled `hack/install_kubespider.sh` on a LAN Linux host with Docker, read the printed config paths before you change anything, and treat the default `kubespider` Aria2 secret as something to replace before the server is reachable beyond your own network.

Frequently asked questions

Official sources

1. License: Apache-2.0
2. opennaslab/kubespider on GitHub
3. Project website
4. README
5. Releases