Watch

A Telegram bot that downloads files/torrents and uploads them to Google Drive

Python 99.4%
Dockerfile 0.6%

Find a file

Repository files (latest commit first)
Filename	Latest commit message	Latest commit date
Vaibhav Sijaria 0287d8bea3 fix(lint): resolve lint warnings and await async get_total_stats		2026-07-02 16:10:06 +05:30
docs	Add MAX_CONCURRENT_JOBS documentation and env example parameters	2026-06-29 15:29:10 +05:30
downloaders	fix(cancel): store status_msg in active_jobs and update queue positions on cancel	2026-07-02 14:40:26 +05:30
handlers	fix(lint): resolve lint warnings and await async get_total_stats	2026-07-02 16:10:06 +05:30
.dockerignore	Fix SQLite disk I/O error in Docker by migrating to directory-based session mounting	2026-06-29 18:55:38 +05:30
.env.example	config: Add configuration for GDProxy and job isolation	2026-06-30 16:41:52 +05:30
.gitignore	Fix SQLite disk I/O error in Docker by migrating to directory-based session mounting	2026-06-29 18:55:38 +05:30
bencode.py	Implement torrent file and directory selection browser with magnet metadata pre-fetching	2026-06-29 12:40:26 +05:30
bot.py	Fix SQLite disk I/O error in Docker by migrating to directory-based session mounting	2026-06-29 18:55:38 +05:30
config.py	fix(reliability): refine concurrency check, parse config safely, and add download timeouts	2026-07-02 16:08:42 +05:30
docker-compose.yml	Fix rclone configuration path mounting in docker-compose	2026-06-29 20:06:00 +05:30
Dockerfile	Fix Pixi Docker image repository source path and remove obsolete compose version	2026-06-29 17:34:29 +05:30
LICENSE	Initialize Pixi configuration and lockfile	2026-06-28 23:52:53 +05:30
pixi.lock	Isolate ruff and pyright to dev environment to exclude them from production Docker image	2026-06-29 17:42:05 +05:30
pixi.toml	Fix SQLite disk I/O error in Docker by migrating to directory-based session mounting	2026-06-29 18:55:38 +05:30
pyproject.toml	Add ruff and pyright configuration, fix linting and typecheck warnings	2026-06-29 11:16:55 +05:30
README.md	Refactor README.md to be short and serious, move setup instructions to docs/setup.md	2026-06-29 11:16:34 +05:30
utils.py	fix(concurrency): implement asyncio locks for global mutable states	2026-07-02 14:27:35 +05:30

README.md

HerdBot

HerdBot is a modular Telegram downloader and uploader bot. It automates downloading files, direct URLs, magnet links, and torrent files to a local server, uploading them recursively to Google Drive, and cleaning up the local filesystem storage after successful transfers.

Key Features

Protocols Supported: Direct links (HTTP/HTTPS), Torrent files, Magnet links, and Telegram native media.
Large File Handling: Utilizes Telethon (MTProto API) and cryptg to support downloading native Telegram files up to 2GB.
Robust Uploads: Integrates with rclone to support chunked, multi-threaded uploads while preserving directory structures for multi-file torrents.
Auto-Cleanup: Guarantees deletion of temporary files from local storage upon successful upload.
Queue & Metrics: Includes /status to track active transfer statistics (speed, ETA, progress bars) and /stats for host server performance tracking.
Access Control: Restricts usage to whitelisted Telegram User IDs.

Project Structure

herdbot/
├── bot.py                # Session entry point
├── config.py             # Config parsing & validation
├── utils.py              # Shared helpers & active jobs registry
├── downloaders/
│   ├── aria2.py          # aria2c downloader interface
│   └── rclone.py         # rclone uploader interface
└── handlers/
    ├── __init__.py       # Event router configuration
    ├── start.py          # /start and /help commands
    ├── stats.py          # /stats and /status commands
    └── mirror.py         # Link & media processing pipeline

Documentation

For setup, Google Drive remote authentication, and running instructions, refer to docs/setup.md.