Control your torrent client from Telegram
10K+
VERSIÓN EN ESPAÑOL | ENGLISH VERSION
Lleva el control de tu gestor de torrents desde un único lugar.
.torrent, un enlace magnet o una URL a un fichero .torrent, eligiendo el directorio de descargaThe.Matrix.1999.1080p.mkv → The Matrix (1999) - 1080p.mkv)/config)Actualmente soporta Transmission, qBittorrent, Deluge y Download Station de Synology como gestores de torrents. La arquitectura interna es agnóstica al cliente, por lo que en el futuro podrán añadirse otros gestores. No todos ofrecen las mismas operaciones en su API: tienes el detalle en qué puede hacer el bot con cada gestor.
📦 Código fuente, incidencias y documentación completa en GitHub.
Antes de levantar el contenedor necesitas un bot propio en Telegram y conocer tu identificador de usuario.
/newbot. Sigue las instrucciones (un nombre y un username acabado en bot).⚠️ Atención No le pongas al bot el nombre TCB ni un username que lo contenga: Telegram lo asocia con términos relacionados con drogas y puede banear el bot automáticamente. Usa un nombre más descriptivo, como por ejemplo
TorrentControllerBot.
TELEGRAM_TOKEN.TELEGRAM_ADMIN), habla con @MissRose_bot y envíale /id. Te responderá con un número, ese es tu ID.TELEGRAM_GROUP./setuserpic.| Comando | Descripción |
|---|---|
/start | Panel de control con el estado general y los torrents agrupados por estado |
/list | Listado completo de torrents con filtros y paginación |
/find texto | Busca torrents por nombre o por ruta, sin importar mayúsculas ni tildes. Cada palabra puede ir en cualquier orden (/find casa papel encuentra La.Casa.de.Papel); una ruta tiene que aparecer tal cual (/find /ssd/peliculas no encuentra /media/Peliculas) y lo que va entre comillas, como frase exacta (/find "la casa") |
/add | Añade un torrent (también puedes enviar directamente un fichero .torrent o un enlace magnet) |
/settings | Ajustes del gestor: modo tortuga, límites de velocidad y ratio |
/tortuga /turtle | Activa o desactiva el modo tortuga (qBittorrent y Transmission) |
/version | Muestra la versión actual y el gestor al que está conectado |
/help | Lista de comandos |
/donate /donors | Dona al desarrollador / lista de donantes |
Al pulsar ✏️ Renombrar sobre un torrent, el bot intenta generar una sugerencia de nombre limpio:
The.Matrix.1999.1080p.BluRay.x264.mkv → The Matrix (1999) - 1080p.mkvOperaciones Especiales Lioness [HDTV 1080p][Cap.103] → 1x03 - Operaciones Especiales Lioness - 1080p (soporta formatos Cap.103, S01E03, T01E03, 3x05 y Temporada 1 Capitulo 3, rangos como Cap.101_107 o S01E01E02, y packs como 2ª Temporada o Temporada Completa 1-5)El Hoyo 2 [WEB-DL 1080p] → El Hoyo 2 - 1080p). Las plantillas personalizadas no cambian: si la tuya exige {año}, sigue sin sugerir nadaSi no puede generar sugerencia, siempre puedes escribir el nombre manualmente.
En un torrent que es una carpeta, 🪄 Renombrar lo renombra todo de una vez, con previsualización antes de confirmar: la carpeta principal, las subcarpetas de temporada y los episodios.
Mad.Men.2007.COMPLETE.1080p.NF.WEB-DL/ Mad Men (2007) - 1080p/
├── Mad.Men.2007.S01.NF.WEB-DL.1080P.AV1-Txv2/ → ├── T1 - Mad Men - 1080p/
│ └── Mad.Men.S01E01.1080p.mkv │ └── 1x01 - Mad Men - 1080p.mkv
└── Extras/ └── Extras/
Las subcarpetas usan la plantilla de temporada (o la de series o películas si la carpeta es un episodio o una película con su año) y toman del torrent lo que les falta, así que Temporada 2 o S04 también se renombran. Las carpetas que no identifican nada, como Extras o Subs, se quedan como están.
Desde el detalle de un torrent, el botón 🗂️ Archivos permite navegar por sus carpetas (entrar en una subcarpeta, ⬆️ subir a la anterior) y renombrar la carpeta en la que estás, cada archivo uno a uno o todo lo que hay en la carpeta de golpe (con previsualización antes de confirmar). Los archivos heredan de su carpeta de temporada y del nombre del torrent lo que no llevan encima (título, año y temporada, nunca el episodio), así que un episodio suelto como 01.mkv dentro de Show.Name.S02.1080p se convierte en 2x01 - Show Name - 1080p.mkv. Los subtítulos que acompañan a un vídeo se renombran con él para no romper el emparejamiento, y todo se hace a través del gestor de torrents, por lo que el seeding se mantiene.
Las plantillas de renombrado admiten el título del episodio y el relleno con ceros: detalles en GitHub.
Si descargas algo que ya tenías (una copia mejor de la misma película, por ejemplo), el renombrado automático no lo renombra porque su nombre ya lo tiene el torrent antiguo, y te lo avisa al añadirlo. Cuando la descarga termina, el aviso de completado trae el botón 🔁 Sustituir el anterior: tras confirmarlo, el bot borra el torrent antiguo con sus datos y renombra el nuevo al nombre que le tocaba (y sus subcarpetas y archivos, si el renombrado automático los incluye).
✅ Descarga completada
🧲 Weapons (2025) 1080p NF WEB-DL DD+5.1 AV1-HDZ.mkv
♻️ Ya hay un torrent llamado Weapons (2025) - 1080p.mkv
[🔁 Sustituir el anterior] [❌ No sustituir]
❌ No sustituir deja los dos torrents como están y el aviso como un aviso de completado normal, sin botones.
Con «Sustituir sin preguntar si el nombre ya existe» (dentro del renombrado automático, desactivado por defecto) lo hace solo al terminar la descarga y te cuenta lo que ha borrado. Nunca se sustituye un torrent que comparte ficheros con el nuevo, porque borrar sus datos borraría también la descarga nueva. Tampoco sustituye nada una descarga de la que has dejado archivos sin bajar, ni una con menos vídeos que el torrent anterior: no es una copia completa de lo que borraría. Y la confirmación borra exactamente lo que lista, aunque mientras tanto aparezca otro torrent con ese nombre.
Cuando llega un episodio o un pack de temporada, el bot busca entre los torrents del gestor otros de la misma serie y te propone su carpeta.
/media/series), te la propone en lugar de decidir por ti. Opcionalmente se aplica también a los torrents añadidos fuera del bot, que en ese caso sí se mueven, porque ya están en el gestor./ssd/SERIES, el primer episodio de The Bear va a /ssd/SERIES/The Bear (o Doctor Who (2005) si lleva año), y los siguientes ya la encuentran ahí.Pensado para quien descarga en un disco rápido y pequeño (un SSD, una caché) y guarda a la larga en otro grande con las mismas carpetas, como hace el mover de UnRAID. Se configura en /settings → 🚚 Mover automático y está desactivado por defecto:
/ssd y destino /media, lo que está en /ssd/PELICULAS va a /media/PELICULAS.El bot lo comprueba cada cinco minutos. Cuando mueve algo manda un aviso con la lista, y ese mismo mensaje cambia cuando los torrents están de verdad en el destino. 👀 Ver qué se movería enseña qué torrents irían ahora mismo y a qué carpeta, y desde ahí se puede lanzar a mano sin esperar al mínimo.
Qué hace cuando algo no cuadra (no cabe, mismo disco, errores del gestor...): detalles en GitHub.
Transmission no responde a nada mientras mueve datos entre discos: durante un movimiento grande el bot dará error de conexión hasta que termine, y el aviso del mover se actualiza entonces. Lo que envíes mientras tanto queda en cola y se añade cuando termine.
El espacio libre se le pregunta al gestor, así que el bot no necesita tener montados los discos. qBittorrent solo lo sabe de su carpeta de descargas por defecto: el origen tiene que ser esa carpeta o estar dentro de ella, y la pantalla lo avisa si no es así.
La arquitectura del bot es agnóstica al gestor, pero sus APIs no ofrecen las mismas operaciones. El bot oculta los botones de lo que el gestor configurado no sabe hacer, así que no verás opciones que fueran a fallar.
| Transmission | qBittorrent | Deluge | Download Station | |
|---|---|---|---|---|
Añadir por magnet o .torrent | ✅ | ✅ | ✅ | ✅ |
| Pausar y reanudar | ✅ | ✅ | ✅ | ✅ |
| Listados, búsqueda y filtros | ✅ | ✅ | ✅ | ✅ |
| Filtrar por tracker | ✅ | ✅ | ✅ | ✅ |
| Acciones masivas | ✅ | ✅ | ✅ | ✅ |
| Notificaciones de completado, error y añadidos externos | ✅ | ✅ | ✅ | ✅ |
| Mover los datos a otra carpeta | ✅ | ✅ | ✅ | ✅ |
| Borrar el torrent con sus datos | ✅ | ✅ | ✅ | ✅ |
| Espacio libre y aviso de disco | ✅ | ✅ | ✅ | ✅ |
| Estadísticas de transferencia, de la sesión y desde siempre | ✅ | ✅ | ⚠️ ⁹ | ❌ ⁹ |
| Límites de velocidad | ✅ | ✅ | ✅ | ✅ |
| Velocidad alternativa (modo tortuga) | ✅ | ✅ | ❌ ¹ | ❌ ¹ |
| Límite de ratio, por torrent y del gestor | ✅ | ✅ | ✅ ⁵ | ❌ ⁶ |
| Quitar del gestor al llegar a su límite | ✅ ¹³ | ✅ ¹³ | ✅ ¹³ | ❌ ⁶ |
| Límite de velocidad por torrent | ✅ | ✅ | ✅ | ❌ ⁶ |
| Límites por tracker | ✅ | ✅ ⁸ | ✅ ⁸ | ❌ ⁶ |
| Reanunciar al tracker | ✅ | ✅ | ✅ | ❌ ⁷ |
| Verificar los datos | ✅ | ✅ | ✅ | ❌ ² |
| Renombrado inteligente, manual y automático | ✅ | ✅ | ✅ | ❌ ³ |
| Categorías | ❌ ⁴ | ✅ | ❌ ⁴ | ❌ ⁴ |
| Ordenar los listados | ✅ | ✅ | ✅ | ✅ ¹⁰ |
| Elegir los archivos a descargar y su prioridad | ✅ | ✅ ¹¹ | ✅ | ✅ ¹² |
Las notas numeradas de la tabla están explicadas en GitHub.
Para usar Download Station (TORRENT_CLIENT=download_station) el bot se conecta a la API web de DSM con un usuario del NAS, el mismo tipo de cuenta con la que entras a DSM. Lo recomendable es crear un usuario dedicado al bot:
Panel de control → Usuario y grupo → Crear.Esos datos van en TORRENT_CLIENT_USER y TORRENT_CLIENT_PASSWORD. El puerto es el de DSM: 5000 en http o 5001 en https (si usas 5001 pon TORRENT_CLIENT_PROTOCOL=https).
ℹ️ Nota Las rutas de descarga de Download Station son relativas a la carpeta compartida, no absolutas: se escriben
Downloadsovideo/pelis, no/volume1/Downloads. El bot crea la carpeta que le escribas si aún no existe, salvo que sea una carpeta compartida, que solo puede crearse desde DSM.
ℹ️ Nota El bot lista todas las tareas de Download Station, también las descargas HTTP o FTP que hayas añadido desde DSM. Con esas, Download Station considera la descarga cerrada en cuanto termina y ya no permite cambiarle el destino: si intentas moverla, el bot te lo dice y no toca los ficheros.
ℹ️ Nota Mover un torrent que está compartiendo lo deja unos segundos en espera y con una verificación rápida antes de volver a compartir. Es el comportamiento normal de DSM al cambiarle el destino, no un error.
| CLAVE | OBLIGATORIO | VALOR |
|---|---|---|
| TELEGRAM_TOKEN | ✅ | Token del bot |
| TELEGRAM_ADMIN | ✅ | ChatId del administrador (se puede obtener hablándole al bot Rose escribiendo /id). Admite múltiples administradores separados por comas. Por ejemplo 12345,54431,55944 |
| TELEGRAM_GROUP | ❌ | ChatId del grupo. Si este bot va a formar parte de un grupo, es necesario especificar el chatId de dicho grupo. Es necesario que el bot sea administrador del grupo |
| TELEGRAM_THREAD | ❌ | Thread del tema dentro de un supergrupo; valor numérico (2,3,4..). Por defecto 1. Se utiliza en conjunción con la variable TELEGRAM_GROUP |
| TZ | ✅ | Timezone (Por ejemplo Europe/Madrid) |
| LANGUAGE | ❌ | Idioma, puede ser ES / EN. Por defecto ES (Spanish) |
| TORRENT_CLIENT | ❌ | Gestor de torrents: transmission, qbittorrent, deluge o download_station. Por defecto transmission |
| TORRENT_CLIENT_HOST | ✅ | Host o IP donde está el gestor de torrents |
| TORRENT_CLIENT_PORT | ❌ | Puerto del gestor de torrents. Por defecto 9091 (Transmission), 8080 (qBittorrent), 8112 (Deluge Web UI) o 5000/5001 (DSM de Synology) |
| TORRENT_CLIENT_USER | ❌ | Usuario del gestor de torrents, si tiene autenticación |
| TORRENT_CLIENT_PASSWORD | ❌ | Contraseña del gestor de torrents, si tiene autenticación |
| TORRENT_CLIENT_PROTOCOL | ❌ | Protocolo de conexión, http o https. Por defecto http |
| TORRENT_CLIENT_RPC_PATH | ❌ | Ruta del RPC. Por defecto /transmission/rpc (Transmission) o /webapi (Synology) |
| TORRENTS_PER_PAGE | ❌ | Número de torrents por página en los listados, entre 1 y 90. Por defecto 10 |
| TELEMETRY | ❌ | false para desactivar las estadísticas anónimas sin pasar por /settings. Lo normal es desactivarlas desde /settings; esto es para quien prefiera dejarlo fijado en el compose |
services:
torrent-controller-bot:
environment:
- TELEGRAM_TOKEN=
- TELEGRAM_ADMIN=
- TZ=Europe/Madrid
- TORRENT_CLIENT=transmission
- TORRENT_CLIENT_HOST=
#- TELEGRAM_GROUP=
#- TELEGRAM_THREAD=1
#- LANGUAGE=ES
#- TORRENT_CLIENT_PORT=9091
#- TORRENT_CLIENT_USER=
#- TORRENT_CLIENT_PASSWORD=
image: dgongut/torrent-controller-bot:latest
container_name: torrent-controller-bot
restart: always
tty: true
volumes:
- /ruta/de/tu/eleccion:/config # Ajustes persistentes del bot
Desde la 1.7.0 el bot envía una vez al día unas cifras anónimas para saber cuánta gente lo usa, con qué gestor de torrents y qué funciones se usan más. Así sé dónde poner el esfuerzo. Las estadísticas son públicas: stats.dgongut.com/torrent-controller-bot.
Qué se envía: el gestor y su versión principal, cuántos torrents gestiona, qué ajustes están activados, la versión del bot, la arquitectura, cuántas veces al día se ha usado cada comando y cada botón, y cómo le llegan los torrents (fichero, magnet o URL). La lista completa, campo a campo, está en la página de privacidad. El servidor descarta cualquier dato que no esté en ella. Desde /settings → Estadísticas anónimas → Ver qué se envía puedes ver exactamente lo que saldría en el siguiente envío.
Qué no se envía nunca: nombres de torrents, rutas, categorías, trackers, direcciones del gestor, IDs de Telegram ni nada de lo que escribes. Tu IP no se guarda.
Cómo se desactiva: desde /settings → Estadísticas anónimas, o con TELEMETRY=false. Al desactivarlas se borra también el identificador de la instalación.
Están activadas por defecto. Nada se envía hasta que el bot lleva al menos 10 minutos en marcha. Tampoco se envía si /config no está en un volumen, porque sin él cada vez que se recreara el contenedor contaría como una instalación nueva.
ℹ️ Nota El bot no necesita acceso a los ficheros descargados: se comunica con el gestor de torrents únicamente por RPC. El único volumen que hay que mapear es
/config, donde el bot guarda sus ajustes para que persistan entre reinicios.
ℹ️ Nota Si Transmission corre en la misma máquina que el bot pero fuera de Docker, usa
host.docker.internalcomoTORRENT_CLIENT_HOST(en Linux añadeextra_hosts: ["host.docker.internal:host-gateway"]).
Content type
Image
Digest
sha256:9772fbee9…
Size
29.8 MB
Last updated
3 days ago
docker pull dgongut/torrent-controller-bot