# rats-search: BitTorrent DHT indexer and full-text search engine for desktop and server

> rats-search is a C++ application that crawls the BitTorrent DHT network, indexes torrent metadata via Manticore Search, and serves results through a Qt UI or a REST API. Pre-built binaries exist for Windows, Linux and macOS; headless server deployment runs on --console mode without any GUI dependency.

**librats/rats-search** — rats-search: BitTorrent P2P multi-platform search engine for Desktop and Web servers with integrated torrent client

- Repository: https://github.com/librats/rats-search
- Stars: 2,019 · Forks: 199
- Language: C++
- License: MIT
- Published: 2026-10-11 · Updated: 2026-10-11 · Language: en
- Canonical page: https://hysenlabs.com/projects/librats-rats-search

## DHT crawling without trackers, and Manticore Search as the index backend

Most torrent search tools depend on a central tracker or an external API to find content. rats-search takes a different path: it connects directly to the BitTorrent Mainline DHT network, which consists of millions of nodes, and crawls it to build a local index without any tracker involvement. The full-text search layer runs through Manticore Search, a bundled search engine that handles queries over the indexed torrent metadata.

The crawler collects only statistical information and does not save internal torrent data, according to the feature list. What it does store is metadata: names, categories, file counts, seeder counts, and whatever descriptions it can pull from trackers. That metadata feeds the search filters, which cover size ranges, seeder thresholds and file-level filtering.

For deployments that go beyond a single node, rats-search also operates its own P2P protocol that allows search queries and database segments to flow between Rats clients. That secondary network is separate from the BitTorrent DHT and uses end-to-end encryption.

## Installing from pre-built packages or compiling with CMake and Qt

Pre-built packages are available for Windows (RatsSearch-Windows-x64.zip), Linux (RatsSearch-Linux-x64.AppImage or .tar.gz) and macOS (RatsSearch-macOS-Intel.zip and RatsSearch-macOS-ARM.zip). These download from the GitHub Releases page without any compilation step.

For a source build, clone with submodules to pull in the librats dependency:

```bash
git clone --recurse-submodules https://github.com/DEgITx/rats-search.git
cd rats-search
```

Then configure and build:

```bash
cmake -B build -G "Ninja" -DCMAKE_BUILD_TYPE=Release
cmake --build build --config Release
```

The executable lands in build/bin/. The build requires CMake 3.16 or newer, Qt 6.9 with its WebSockets module, a C++17-compatible compiler (MSVC, GCC or Clang) and Ninja as the recommended generator. Two CMake options control optional components: RATS_SEARCH_BUILD_TESTS (ON by default) and RATS_SEARCH_USE_SYSTEM_LIBRATS (OFF by default), which controls whether to use a system-installed librats or the bundled one.

## rats.json configuration and the three ports it assigns

After first launch, rats-search writes a configuration file named rats.json in the data directory. The default content is:

```json
{
    "p2pPort": 4445,
    "dhtPort": 4446,
    "httpPort": 8095,
    "restApi": true,
    "indexer": true,
    "darkMode": true
}
```

Three ports serve distinct roles. The p2pPort (4445 TCP/UDP) handles the Rats P2P protocol between Rats clients. The dhtPort (4446 UDP) handles BitTorrent DHT operations. The httpPort (8095) serves the REST API and WebSocket connections for custom clients.

Setting restApi to false disables the HTTP server entirely, which removes the only programmatic interface for a running instance. The indexer key controls whether the DHT spider runs at startup; setting it to false stops new torrent collection without stopping the application. These two settings work independently, so a read-only deployment can disable indexer while keeping restApi running.

## Console mode for headless servers and the --spider override

Headless deployments use the --console flag, which starts all subsystems without opening a GUI window. Console mode logs to a file named rats-search.log in the data directory rather than to a terminal. The application reads no commands from stdin in this mode, so the only way to query or control a running instance is through the REST API with restApi set to true in rats.json.

To start a headless server with the DHT spider forced on and a custom data directory:

```bash
./RatsSearch --console --spider --data-dir /var/lib/rats-search
```

Or with custom ports:

```bash
./RatsSearch -c -p 4445 -d 4446 -s
```

The --spider flag forces DHT crawling even when indexer is set to false in rats.json. This override matters when you want to start indexing without editing the config file. The --max-peers flag sets the maximum P2P connections between 10 and 1000, with the config value as the default.

The Docker image ships with a Dockerfile at the repository root that runs console mode on the ubuntu:24.04 base and exposes port 8095. It copies Manticore Search binaries from the imports/ directory rather than installing them from a package manager.

## Manticore Search binaries ship pre-built in imports/, not compiled from source

The feature list describes full-text search as being powered by Manticore Search, but the README does not explain how Manticore is distributed. The Dockerfile reveals the mechanism: three pre-built binaries (searchd, indexer and indextool) are copied from imports/linux/x64/ into the Docker image at /app/ alongside the main executable. These are bundled binary artifacts, not packages installed from apt or compiled as CMake targets.

That bundling choice has practical implications. Upgrading Manticore Search requires replacing the binaries in imports/ rather than running a package manager update. On architectures or operating systems not covered by the imports/ subdirectory structure, a source build would need to supply the appropriate Manticore binaries separately. The build options table in the README does not document a flag for using a system-installed Manticore, unlike the RATS_SEARCH_USE_SYSTEM_LIBRATS option for librats.

This is the detail most users skip: the Qt application and the search engine are two separate processes that rats-search manages together. The searchd process handles index queries; RatsSearch handles the DHT crawl, the UI and the REST API.

## Encrypted P2P layer for search and database transfers between Rats clients

Beyond the standard BitTorrent DHT, rats-search operates its own P2P protocol that connects Rats clients to each other. This secondary network carries three types of traffic: search queries across clients, descriptions and votes, and full database transfers. End-to-end encryption uses the Noise Protocol with Curve25519 key exchange and ChaCha20-Poly1305 for data encryption.

Database transfers between clients are opt-in on the serving side. A client that shares its index allows peers to download the entire .ratsdb database file over P2P. The .ratsdb format also supports local export and import with a resumable merge, so an operator can seed a new node with an existing index rather than starting from an empty crawl.

Local network peers are discovered via mDNS without requiring internet access. For peers behind NAT or firewalls, STUN/ICE traversal is supported. The GossipSub messaging protocol handles the publish-subscribe layer for the feed list and voting system.

## REST and WebSocket API, translation support, and the MIT terms

The REST and WebSocket API is documented in docs/API.md and allows custom clients to query the running instance without the Qt GUI. Port 8095 is the default HTTP port; changing httpPort in rats.json moves it. The README does not describe authentication mechanisms for the REST API, which means any client that can reach port 8095 on the network can issue queries.

The application ships with translations for 8 languages: English, Russian, Japanese, Chinese, Korean, German, Spanish and French. These live in the translations/ directory at the repository root.

v2.3.4 was released on 2026-10-03, with the last push to the repository on the same date; source code is under the MIT licence.

## Conclusion

rats-search fits teams or individuals who want to index the BitTorrent DHT network locally without depending on external trackers. Pre-built packages for Windows, Linux and macOS cover most deployments; source builds require Qt 6.9 and CMake 3.16. Skip it if you need a search engine covering a curated catalog rather than the open DHT, or if you cannot expose ports 4445, 4446 and 8095. Before deploying headless, confirm the REST API on port 8095 is protected by a network layer, since the README does not document authentication for the REST endpoint.

## FAQ

### What is rats-search?

rats-search is a C++ BitTorrent DHT search engine that indexes torrent metadata from the DHT network without requiring trackers, then serves results through a Qt desktop UI or a REST API. It runs on Windows, Linux and macOS.

### How do I install rats-search?

Pre-built packages are available for Windows, Linux and macOS from the GitHub Releases page. Linux packages come as an AppImage or a tar.gz archive. Building from source requires CMake 3.16 or newer, Qt 6.9 with the WebSockets module, and a C++17 compiler.

### Can rats-search run on a server without a GUI?

Yes. Run with the --console flag for headless operation. In console mode, the application logs to rats-search.log in the data directory and accepts no stdin commands; management goes through the REST API on port 8095.

### What ports does rats-search use?

The default configuration uses three ports: 4445 for P2P communication, 4446 for DHT, and 8095 for the HTTP and REST API server. All three are configurable in rats.json.

### Does rats-search support Docker?

Yes. A Dockerfile is included at the repository root. It builds on ubuntu:24.04 and runs in console mode, exposing port 8095 for the REST API.

## Sources

- [Issues](https://github.com/librats/rats-search/issues)
- [librats/rats-search on GitHub](https://github.com/librats/rats-search)
- [License: MIT](https://github.com/librats/rats-search/blob/master/LICENSE)
- [README](https://github.com/librats/rats-search/blob/master/README.md)
- [Releases](https://github.com/librats/rats-search/releases)

---

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