# cross-seed for Conservative Automatic Torrent Matching

> cross-seed is a Node.js application that finds possible cross-seeds for existing torrents through Torznab indexers. It is aimed at users of qBittorrent, rTorrent, Deluge, or Transmission who want conservative matching with less manual searching.

**cross-seed/cross-seed** — Fully-automatic cross-seeding with Torznab

- Repository: https://github.com/cross-seed/cross-seed
- Website: https://cross-seed.org
- Stars: 1,584 · Forks: 104
- Language: TypeScript
- License: Apache-2.0
- Published: 2026-10-16 · Updated: 2026-10-16 · Language: en
- Canonical page: https://hysenlabs.com/projects/cross-seed-cross-seed

## cross-seed Targets Existing Torrents, Not Blank-Disc Searches

cross-seed solves a narrow automation problem: it looks for torrent releases that can be cross-seeded against content already represented in a user's torrent client. That starting point distinguishes it from a conventional torrent search interface. The application is designed to "match conservatively to minimize manual intervention," according to the README. Conservative matching is important here because cross-seeding depends on content equivalence, not merely on similar titles. The project does not document its precise candidate acceptance rules in the README, so an engineer should not assume that a returned result proves identical file content.

The intended users are people who already maintain torrents and want to discover corresponding releases from participating trackers. The supported client list is explicit: rTorrent, qBittorrent, Deluge, and Transmission. At least one of those clients is required. On the indexer side, cross-seed requires trackers that support Torznab, reached through Prowlarr or Jackett. This makes it an automation component for an existing private-tracker setup rather than a standalone source of torrents.

The project description and repository topics connect it to BitTorrent, private trackers, cross-seeding, Jackett, and Torznab. Those terms describe its operating context. cross-seed does not remove the need for tracker access, torrent-client configuration, or careful handling of private-tracker credentials. It automates matching work after those surrounding services exist.

## How cross-seed Connects Clients to Torznab

The documented architecture has three external boundaries: a torrent client containing existing torrents, one or more Torznab-capable indexers reached through Prowlarr or Jackett, and the cross-seed application that coordinates the search. The README states that cross-seed finds torrents that can be cross-seeded based on existing torrents, but it does not publish the internal matching algorithm, queue model, injection sequence, or retry policy. Those implementation details should be checked in the linked documentation or source before they are treated as an API contract.

The repository is a TypeScript monorepo. Its `package.json` identifies workspaces named `cross-seed`, `shared`, `webui`, `api-types`, and `cross-seed.org`. This layout suggests that the daemon, web interface, shared code, and API types are maintained as separate packages. The root build command delegates to the `cross-seed` workspace, while separate scripts build API types, the web interface, and documentation. Those package boundaries are confirmed by the repository files, although the README does not describe an external HTTP API.

The application is packaged with a daemon command in the development scripts. The root `dev` script builds the application, starts backend watch mode, launches the daemon, and starts the frontend development server. This is development structure, not an end-user installation tutorial. It does show that cross-seed includes more than a one-file command-line utility. The separate `webui` workspace also indicates a browser-based interface, while `api-types` keeps shared contract types isolated from runtime packages.

## Requirements and the Official First-Run Path

The README sends new users to the official getting-started guide rather than embedding a complete installation procedure. Before configuration, the documented requirements are Node.js 24 or later, at least one supported torrent client, and Torznab-capable indexers accessed through Prowlarr or Jackett. The repository also contains a `Dockerfile`, but the README does not give a complete `docker run` command with volume and environment settings. An engineer who wants container deployment therefore needs the official documentation rather than an example reconstructed from guesswork.

For a source checkout, the repository exposes these development commands:

```bash
npm run build
npm run build:webui
```

The first command builds the `cross-seed` workspace, and the second builds the web interface. They compile the repository but are not presented by the README as a complete production installation. The Docker build uses the following dependency installation and build sequence:

```bash
npm ci --workspaces --no-fund
npm run build:all
```

The first installs the workspace dependencies, and the second performs the application build before production dependencies are pruned. A first real configuration should follow the linked getting-started guide: connect a supported torrent client, configure Prowlarr or Jackett with eligible indexers, and confirm that the application can inspect existing torrents before enabling any download or injection behavior. The README does not state the exact configuration keys or web UI sequence, so it would be inaccurate to invent them.

## Docker Packaging and Network Exposure

The published container path is `ghcr.io/cross-seed/cross-seed`. The README defines several image tag patterns: `:branch`, `:6`, and `latest`. It states that `latest` is the most recent stable release, while `prerelease` points to the most recent release or prerelease. The `master` image represents the main development branch and can contain unreleased work. The `nightly` image is for open experimental pull requests, is not always produced, and may fall behind `master`.

The `Dockerfile` uses a two-stage build based on `node:26-alpine`. Its runtime layer installs `catatonit`, `curl`, and `tzdata`, then links the `cross-seed` workspace as the executable. It sets `CONFIG_DIR=/config`, enables `DOCKER_ENV=true`, exposes port `2468`, and uses `/config` as the working directory. These are concrete container facts. The README does not document authentication defaults, all persisted paths, or a complete production invocation, so those points require verification in the deployment guide.

Tag selection changes the upgrade risk. `latest` corresponds to the most recent release, whereas `master`, `prerelease`, and `nightly` can expose code ahead of that release. An operator should decide whether automatic replacement of a container is acceptable before selecting a moving tag. The README warns that git branches do not represent released code, a distinction worth keeping in mind when comparing a branch checkout with a published image.

## Conservative Matching Still Leaves Responsibility with the User

The clearest design goal in the README is conservative matching. This reduces the need for manual intervention, but it does not make automated decisions authoritative. The documentation does not publish acceptance thresholds, content-hash checks, episode handling rules, excluded release groups, failure messages, or an explanation of what happens when multiple candidates match. Those omissions limit what can be concluded from the README alone.

cross-seed is also the wrong tool when the objective is to discover content that has no relationship to torrents already in the client. Its stated input is the user's existing torrents. It is unsuitable as a replacement for a general torrent search interface, and it cannot operate without at least one supported client. Users whose indexers do not offer Torznab through Prowlarr or Jackett also fall outside the documented setup.

A further constraint is private-tracker access. The repository topics explicitly include private trackers, but the README does not describe passkey handling, tracker-specific credential storage, or how authentication failures are reported. Those are operational details that must not be inferred from the presence of Torznab support. The application may reduce search effort while leaving users responsible for confirming release identity, tracker permissions, and client-side outcomes.

## Maintenance, Releases, and Apache-2.0 Obligations

The repository is not archived, and its last push was on 2026-10-14. The recent release list includes `v7.0.0-22` from 2026-06-01, followed by `v7.0.0-21` and `v7.0.0-20` on 2026-05-29. These dates support recent repository activity, but they do not guarantee compatibility with a particular tracker, client version, or Node.js installation. cross-seed roughly follows semantic versioning, and every release has a corresponding Git tag.

The README distinguishes stable releases such as `v0.0.0` from prereleases such as `v0.0.0*-0*`. It also warns that Git branches do not represent released code. An upgrade process should therefore identify the exact release tag or container digest being deployed rather than assuming that `master` is equivalent to the latest release. The Docker tags provide convenience, but they also make it important to record which tag was selected.

The repository is licensed under Apache-2.0. That permits use and modification under the license's terms, with obligations including preservation of applicable notices and the license text. Distribution and modifications should be reviewed against the actual `LICENSE` file. This is a licensing inventory point, not legal advice. Runtime upgrade cost also depends on reconciling Node.js, the torrent client, Prowlarr or Jackett, and private-tracker configuration, none of which can be bundled into a single upgrade command based on the README.

## Conclusion

Adopt cross-seed if you operate a supported torrent client, already have Torznab-capable indexers, and want to reduce manual cross-seeding searches. Do not choose it as a general torrent search engine or assume that every candidate is safe to inject. Verify first that your client and indexers expose the required connections, then follow the official getting-started documentation for the exact installation and first-run configuration.

## FAQ

### What does cross-seed require before it can run?

The README requires Node.js 24 or later, at least one of rTorrent, qBittorrent, Deluge, or Transmission, and Torznab-capable indexers through Prowlarr or Jackett.

### Does cross-seed find torrents without using existing client data?

No. Its stated function is to find torrents that can be cross-seeded based on torrents already present in the user's client. It is not documented as a general torrent search engine.

### Which Docker image should an installer use?

The README states that `latest` is the most recent release. It also documents `prerelease`, `master`, and `nightly`, which can contain code newer than that release.

## Sources

- [cross-seed/cross-seed on GitHub](https://github.com/cross-seed/cross-seed)
- [License: Apache-2.0](https://github.com/cross-seed/cross-seed/blob/master/LICENSE)
- [Project website](https://cross-seed.org)
- [README](https://github.com/cross-seed/cross-seed/blob/master/README.md)
- [Releases](https://github.com/cross-seed/cross-seed/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/cross-seed-cross-seed