HKML-X Docs

Appearance

Configuration ​

The bot is configured through config.py (a Python file, not .env). This page explains every setting in plain English.

Where's the config file? ​

bash
# In your HKML-X folder:
cp config_sample.py config.py   # Create it
nano config.py                   # Edit it

Python syntax rules:

  • Strings need quotes: "hello"
  • Numbers don't: 42
  • Booleans are capitalized (no quotes): True, False
  • Lists use brackets: ["a", "b"]
  • Dicts use braces: {"key": "value"}

After editing, restart: docker compose restart

Required (bot won't start without these) ​

VariableWhat it is
BOT_TOKENYour bot's token from @BotFather
OWNER_IDYour Telegram user ID (from @userinfobot)
TELEGRAM_APIAPI ID from my.telegram.org
TELEGRAM_HASHAPI hash from my.telegram.org
DATABASE_URLMongoDB connection string

Upload destinations ​

VariableWhat it doesDefault
DEFAULT_UPLOADDefault upload target: "gd" (Google Drive) or "rc" (Rclone)"rc"
GDRIVE_IDDefault Google Drive folder ID for uploads""
GD_DESPDescription text for Google Drive uploads"Uploaded with WZ Bot"
IS_TEAM_DRIVESet to True if your GDrive ID is a Team DriveFalse
STOP_DUPLICATESkip upload if file already exists in GDriveFalse
INDEX_URLYour Google Drive index URL for shareable links""
USE_SERVICE_ACCOUNTSUse Google Service Accounts for higher quotaFalse
RCLONE_PATHDefault Rclone remote path (e.g., "main:folder")""
RCLONE_FLAGSExtra Rclone flags ("key:value|key")""
SHOW_CLOUD_LINKShow cloud link button on leeched filesTrue
RCLONE_SERVE_URLPublic URL for Rclone serve""
RCLONE_SERVE_PORTPort for Rclone serve8081
RCLONE_SERVE_USERUsername for Rclone serve auth""
RCLONE_SERVE_PASSPassword for Rclone serve auth""
DRIVE_CATEGORY_MODEEnable GDrive categories for organizing uploadsFalse
DRIVE_CATEGORY_SAService account to use for drive category uploads""

Leech settings (uploading to Telegram) ​

VariableWhat it doesDefault
LEECH_SPLIT_SIZEMax file size per part in bytes (Telegram limit is ~2GB)0 (max allowed)
AS_DOCUMENTUpload all files as documents (not media)False
EQUAL_SPLITSSplit into equal-sized partsFalse
MEDIA_GROUPGroup split parts as a media albumFalse
TRANSMISSION_MODEWho sends leeched files: "both", "bot", or "user""both"
LEECH_PREFIXText added before filename""
LEECH_SUFFIXText added after filename""
LEECH_FONTFont style: "b", "i", "u", "s", "code", "spoiler"""
LEECH_CAPTIONCustom caption text for leeched files""
THUMBNAIL_LAYOUTThumbnail layout format (e.g., "1280x720")""
LEECH_DUMP_CHATChat ID where all leeched files are dumped""

Limits & queue ​

VariableWhat it doesDefault
STATUS_LIMITMax tasks shown in /status10
STATUS_UPDATE_INTERVALHow often the status message refreshes (seconds)15
QUEUE_ALLMax total parallel tasks (download + upload)0 (unlimited)
QUEUE_DOWNLOADMax parallel downloads0 (unlimited)
QUEUE_UPLOADMax parallel uploads0 (unlimited)
BOT_MAX_TASKSMax tasks per user (across all users)0 (unlimited)
USER_MAX_TASKSMax concurrent tasks per user0 (unlimited)
USER_TIME_INTERVALCooldown between tasks per user (seconds)0 (disabled)
STORAGE_LIMITMin free disk space to maintain (GB). Downloads cancel if exceeded0 (disabled)

Per-engine limits (size in GB, 0 = unlimited) ​

VariableLimits
DIRECT_LIMITDirect link downloads
MEGA_LIMITMega downloads
TORRENT_LIMITTorrent downloads
GD_DL_LIMITGoogle Drive downloads
RC_DL_LIMITRclone downloads
CLONE_LIMITGoogle Drive clone operations
YTDLP_LIMITyt-dlp downloads
PLAYLIST_LIMITMax items from a playlist
LEECH_LIMITLeech (Telegram upload) size
EXTRACT_LIMITExtracted file size
ARCHIVE_LIMITArchive (zip) size
RSS_SIZE_LIMITRSS download size

User access control ​

VariableWhat it does
AUTHORIZED_CHATSUser/Chat IDs allowed to use the bot (space-separated)
SUDO_USERSUser IDs with admin powers (space-separated)
FORCE_SUB_IDSChannel/Group IDs users must join before using (space-separated)
BOT_PMForce files/links to be sent via bot PM
VERIFY_TIMEOUTVerification timeout in seconds
LOGIN_PASSPassword to skip verification (leave empty to disable)

Web UI ​

VariableWhat it doesDefault
BASE_URLPublic URL for torrent file selection web UI""
WEB_PINCODERequire a pincode to access the web UITrue
WEB_ACCESS_PASSWORDSecret for deriving web passwords"" (auto-generated)

Appearance ​

VariableWhat it doesDefault
TIMEZONETimezone for timestamps"Asia/Kolkata"
DEFAULT_LANGBot language code"en"
AUTHOR_NAMEAuthor name shown on Telegraph pages"HKML-X"
AUTHOR_URLAuthor link"https://t.me/HKML_X"
USE_IMAGESEnable random photo backgrounds on messagesFalse
IMG_SEARCHComma-separated keywords to auto-fetch wallpapers""
IMG_PAGENumber of pages to search for images1
IMG_SOURCESImage source sites: ["wallpaperflare"]["wallpaperflare"]
IMAGESThe gallery itself. Don't edit by hand — use /addimage and /images[]
IMDB_TEMPLATEHTML template for IMDB search results(built-in)
COLORED_BTNSUse colored inline buttonsFalse

Feature toggles ​

Set True to disable a feature:

VariableWhat it disablesDefault
DISABLE_TORRENTSAll torrent downloadsFalse
DISABLE_LEECHAll leech tasks (/leech, /qbleech, ...)False
DISABLE_MIRRORAll mirror tasks (/mirror, /qbmirror, ...)False
DISABLE_BULKThe -b flag — many links from one messageFalse
DISABLE_MULTIThe -i flag — multiple replied linksFalse
DISABLE_SEEDThe -d flag — seeding after torrent downloadFalse
DISABLE_FF_MODEThe -ff flag — FFmpeg processingFalse
DISABLE_MEGAMega.nz downloadsFalse
DISABLE_RSSRSS feed monitoringFalse
DISABLE_SEARCHTorrent searchFalse
DISABLE_YTDLPyt-dlp downloads (YouTube, social media)False

Download engines ​

qBittorrent / Aria2 ​

VariableWhat it doesDefault
TORRENT_TIMEOUTDead torrent timeout (seconds)0 (disabled)
CPU_LIMITCPU limit for background services20
THROTTLE_SERVICESPause services during heavy operations: "auto" or "off""auto"

BASE_URL and WEB_PINCODE are documented under Web UI above.

Mega ​

VariableWhat it does
MEGA_EMAILMega account email
MEGA_PASSWORDMega account password
DISABLE_MEGADisable Mega entirely

Filename & processing ​

VariableWhat it does
NAME_SWAPRename files using pattern: "old:new|old2:new2"
FFMPEG_CMDSCustom FFmpeg command presets (dict format)
UPLOAD_PATHSCustom upload paths per file extension (dict format)
EXCLUDED_EXTENSIONSFile extensions to skip (space-separated, no dots)
CMD_SUFFIXText appended to all commands (e.g., "x" → /mirrorx)
SET_COMMANDSAuto-register bot commands with Telegram on start

Debrid & DDL services ​

VariableWhat it does
FILELION_APIFileLion API key
STREAMWISH_APIStreamWish API key
ALLDEBRID_API_KEYAllDebrid API key. Powers the -ad flag on /mirror and /leech
DEBRID_LINK_APIDebrid-Link API key
GOFILE_APIGofile.io API token
GOFILE_FOLDER_IDGofile.io folder ID
GOFILE_AUTO_CREATE_FOLDERAuto-create a new folder per upload on Gofile
PIXELDRAIN_KEYPixelDrain API key
PROTECTED_APIProtectedFiles API key
BUZZHEAVIER_APIBuzzHeavier API key
DEVUPLOADS_KEYDevUploads API key
DEVUPLOADS_FOLDERDevUploads folder ID
VIKINGFILE_HASHVikingFile.to hash
VIKINGFILE_FOLDERVikingFile folder name
VIKINGFILE_FOLDERVikingFile.to folder ID
INSTADL_APIInstagram downloader API key

RSS ​

VariableWhat it doesDefault
RSS_DELAYCheck interval in seconds600
RSS_CHATDefault chat ID for RSS notifications""
RSS_SIZE_LIMITRSS download size limit (GB)0
VariableWhat it does
SEARCH_API_LINKSearch API app URL for multi-search
SEARCH_LIMITMax results per site
SEARCH_PLUGINSList of qBittorrent search plugin URLs

Logging ​

VariableWhat it does
MIRROR_LOG_IDChat ID for mirror logs
LINKS_LOG_IDChat ID for link logging
LEECH_DUMP_CHATChat ID where leeched files are dumped
MEDIA_STOREStore media metadata for re-upload
DELETE_LINKSAuto-delete source links on task start

Updates ​

VariableWhat it doesDefault
UPSTREAM_REPOYour GitHub fork URL for auto-updates""
UPSTREAM_BRANCHBranch to track for updates"master"

Advanced / Hyper TG Downloader ​

VariableWhat it doesDefault
USE_HYPEREnable Hyper DL/UP for faster Telegram transfersTrue
ENABLE_TELEMETRYSend crash reports to remote worker for debuggingTrue
HELPER_TOKENSExtra bot tokens for parallel Telegram transfers (space-separated)""
HELPER_STRINGSExtra user session strings, paired with the helper bots""
HELPER_BOT_PROXIESProxies for the helper bot tokens""
HELPER_USER_PROXIESProxies for the helper user sessions""
USER_SESSION_STRINGPyrogram session string for user account tasks""
HYPER_THREADSNumber of parallel download parts0 (auto)
HYPER_PIPELINEConcurrent GetFile requests per part4
HYPER_CHUNKDownload chunk size (bytes)524288
TG_PROXYSOCKS5 proxy for Telegram: {"scheme": "socks5", "hostname": "...", "port": 1234}{}
INC_TASK_NOTIFYNotify about incomplete tasks on restartFalse
INC_TASK_RESUMEAuto-resume incomplete tasks on restartFalse

YouTube upload settings ​

VariableWhat it doesDefault
YT_DESPDescription for YouTube uploads"Uploaded with HKML-X bot"
YT_TAGSTags for YouTube uploads["telegram", "bot", "youtube"]
YT_CATEGORY_IDYouTube category ID22
YT_PRIVACY_STATUSPrivacy: "public", "unlisted", or "private""unlisted"
YT_DLP_OPTIONSDefault yt-dlp options ("key:value|key:value")""