# TorrentNG compatible-client WebUI/API service

This directory is the current repository path for TorrentNG's compatible-client
WebUI/API service. The executable built here is `torrentng`: it serves the
shared WebUI, TorrentNG REST API, qBittorrent/Transmission/Deluge compatibility
APIs, cache, workflows, auth, and metrics. It does not perform BitTorrent
transfers itself.

The separate `webui/` directory contains the React frontend. The TorrentNG
client is `torrentngd` in
[crates/torrentngd/](../crates/torrentngd/), which can serve the same WebUI/API
directly while also owning transfer, storage, and durable session state.

## What this is

`torrentng` connects to one selected compatible torrent client. Supported
integrations include rTorrent through a trusted local or remote SCGI/XMLRPC
connection, qBittorrent through its Web API, Transmission through RPC, Deluge
through JSON-RPC, and a separate `torrentngd` through its TorrentNG HTTP API.
The selected client owns peer traffic, payload storage, and session state;
TorrentNG supplies the shared WebUI/API, authentication, cache, workflows,
metrics, and compatibility projections.

### WebUI login

When API-token authentication is enabled, use the configured token in either
the WebUI username or password field. Tokens come from `[auth].api_tokens` in
the service config or `TNG_API_TOKENS` / `RTNG_API_TOKENS` in the environment.
Fresh installs generate a unique WebUI password in the service data directory;
run `torrentng auth-token [config.toml]` from an interactive terminal to
retrieve the active login. It writes credentials only to the controlling
terminal, never stdout, and refuses non-interactive use. Configure a custom
username/password in `[auth]`, `TNG_USERNAME` / `TNG_PASSWORD`, or
**Settings -> Security**. Public binds require an API token and a WebUI password
of at least 16 characters. Runtime changes persist in the service data
directory; API tokens remain enabled for automation.

On Unraid, open the **Docker** tab, click the icon for the
`torrentng-webui` container, and choose **Console**. At the prompt, run
`torrentng auth-token`; it prints the current TorrentNG WebUI username and
password in that interactive console. The qBittorrent (or other backend)
credentials configured in the template are used by TorrentNG to connect to the
backend and are not the TorrentNG WebUI login. You can instead sign in with a
configured API token in either login field. See the
[Unraid deployment guide](../deploy/unraid/README.md#webui-login) for both
Unraid templates.

For the Docker Compose deployment, run this from the repository directory
while the TorrentNG service is running. For an optional backend, add its
matching `deploy/docker/compose.<backend>.yml` file and `--profile <backend>`;
use `torrentng-qbittorrent`, `torrentng-transmission`, or `torrentng-deluge`
as the service name for the corresponding profile.

```sh
docker compose --env-file .env -f deploy/docker/compose.yml \
  exec torrentng torrentng auth-token
```

The command needs an interactive terminal. You can also sign in with one of
the `TNG_API_TOKENS` values from the protected `.env` file in either login
field.

Use this when you:

- already have a supported torrent client and want a modern WebUI/API without
  moving its library,
- want one interface for automation tools that speak qBittorrent,
  Transmission, or Deluge APIs, or
- want to compare a compatible client with the next-generation TorrentNG
  client before migrating.

If you want TorrentNG to own transfer, storage, persistence, rechecks, and
durable jobs, run the TorrentNG client directly
(`torrentngd`, [crates/torrentngd/](../crates/torrentngd/)). It is the primary
first-party client and does not require an external torrent client.

## Why a separate Cargo workspace

This directory has its own `Cargo.toml`/`Cargo.lock` and is intentionally
outside the root workspace under `crates/`. It contains the compatible-client
integration service, not the TorrentNG transfer client. Keeping the workspace
separate prevents external-client adapter and WebUI-service changes from
coupling the TorrentNG client build to every upstream API dependency.

## Layout

| Module | Purpose |
|---|---|
| `config` | TOML config loading, `TNG_*` env overrides |
| `rtorrent::client` | Async XMLRPC/SCGI client over Unix socket or TCP |
| `rtorrent::torrents` | `d.multicall2` torrent queries, CRUD ops, user-agent push |
| `api::server` / `api::handlers` | axum router and TorrentNG REST handlers |
| `api::ws` | WebSocket event broadcast |
| `qbcompat` | qBittorrent v2 API shim |
| `cache::db` / `cache::query` | rusqlite cache schema and server-side filter/sort/paginate |
| `sync` | Background poll -> cache upsert -> WS broadcast loop |

## Build and run

```sh
cd sidecar
cargo build
cargo test
```

Or via Docker Compose with the rTorrent-compatible integration:

```sh
docker compose -f ../deploy/docker/compose.yml up --build
```

## Related docs

- [docs/ENGINE_REWRITE.md](../docs/ENGINE_REWRITE.md) — compatible-client
  integrations and the TorrentNG client, side by side
- [docs/DEPLOYMENT.md](../docs/DEPLOYMENT.md) — compatible-client deployment
- [docs/MIGRATION.md](../docs/MIGRATION.md) — moving state in or out, in
  either direction
- [docs/TRACKER-IDENTITY.md](../docs/TRACKER-IDENTITY.md) — user-agent/peer-id
  policy shared by both engines