[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-80149":3},{"id":4,"name":5,"fullName":6,"owner":7,"repo":5,"description":8,"homepage":9,"htmlUrl":10,"language":11,"languages":10,"totalLinesOfCode":10,"stars":12,"forks":13,"watchers":14,"openIssues":15,"contributorsCount":16,"subscribersCount":16,"size":16,"stars1d":16,"stars7d":16,"stars30d":15,"stars90d":16,"forks30d":16,"starsTrendScore":16,"compositeScore":17,"rankGlobal":10,"rankLanguage":10,"license":10,"archived":18,"fork":18,"defaultBranch":19,"hasWiki":20,"hasPages":18,"topics":21,"createdAt":10,"pushedAt":10,"updatedAt":27,"readmeContent":28,"aiSummary":29,"trendingCount":16,"starSnapshotCount":16,"syncStatus":30,"lastSyncTime":31,"discoverSource":32},80149,"WalrusHF","rezaaa\u002FWalrusHF","rezaaa","WalrusHF runs a Telegram bot inside a Hugging Face Space and uploads received files to Rubika. Telegram is the control panel; the Space page is a live dashboard for process health, queue state, storage, and logs.","",null,"Python",51,23,52,1,0,4.14,false,"main",true,[22,23,24,25,26],"bot","huggingface","rubika","telegram","walrus","2026-06-12 02:03:58","---\ntitle: WalrusHF\nemoji: ⛵\ncolorFrom: red\ncolorTo: yellow\nsdk: gradio\npython_version: '3.11'\napp_file: app.py\npinned: false\n---\n\n# WalrusHF\n\n[فارسی](README.fa.md)\n\nWalrusHF runs a Telegram bot inside a Hugging Face Space and uploads received files to Rubika. Telegram is the control panel; the Space page is a live dashboard for process health, queue state, storage, and logs.\n\nFor the VPS-hosted version of Walrus, see https:\u002F\u002Fgithub.com\u002Frezaaa\u002Fwalrus.\n\nThe name Walrus is inspired by the Black Sails series: Captain Flint's ship, Walrus.\n\n\u003Cimg width=\"3456\" height=\"3228\" alt=\"587988794-00199bb8-1882-4ec5-b6cf-b38c8b57d14c\" src=\"https:\u002F\u002Fgithub.com\u002Fuser-attachments\u002Fassets\u002F82472063-baaf-4bfb-bbc6-34b458fbba2a\" \u002F>\n\n## Features\n\n- Accept Telegram files and direct `http:\u002F\u002F` or `https:\u002F\u002F` file links\n- Queue direct file URLs from the Space dashboard without using Telegram\n- Download files inside the Space runtime\n- Queue Rubika uploads so transfers do not overlap\n- Upload to Rubika Saved Messages or a Rubika channel\n- Show Telegram progress for download, queue, upload, retries, and failures\n- Support cancel, cleanup, retry, retry-all, and Rubika login commands\n\n## Install\n\n\u003Cimg width=\"1536\" height=\"1024\" alt=\"Generated image 1\" src=\"https:\u002F\u002Fgithub.com\u002Fuser-attachments\u002Fassets\u002F45187c3e-650a-4435-b9a4-4cd1bf44d4f3\" \u002F>\n\n\n### 1. Create A Hugging Face Space\n\nOpen https:\u002F\u002Fhuggingface.co\u002Fspaces and create a new Space with these settings:\n\n- **Space SDK:** `Gradio`\n- **Gradio template:** `Blank`\n- **Hardware:** `CPU Basic`\n- **Visibility:** `Private` is recommended\n- **Space name:** any name, for example `walrushf`\n\n### 2. Add A Storage Bucket\n\nOn the same Create Space page, enable **Mount a bucket to this Space**:\n\n- **Bucket:** create a new private bucket, or mount an existing private bucket\n- **Mount path:** `\u002Fdata`\n- **Access mode:** `Read & Write`\n\nWalrusHF stores sessions, downloads, and queue data under `\u002Fdata\u002Fwalrus`. Without durable `\u002Fdata`, the app falls back to `\u002Ftmp\u002Fwalrus`, which can be lost when the Space restarts.\n\n### 3. Deploy From GitHub\n\nClone this repo and push it to your Space:\n\n```bash\ngit clone git@github.com:rezaaa\u002FWalrusHF.git\ncd WalrusHF\ngit remote add space https:\u002F\u002Fhuggingface.co\u002Fspaces\u002FUSERNAME\u002FSPACE_NAME\ngit push space main:main\n```\n\nReplace `USERNAME\u002FSPACE_NAME` with your Hugging Face Space path.\n\nIf the Space already has starter files and the push is rejected:\n\n```bash\ngit push --force-with-lease space main:main\n```\n\n### 4. Finish Setup\n\n1. Add the required secrets below in the Space settings.\n2. Restart the Space.\n3. Open your Telegram bot and send `\u002Fstart`.\n\nHugging Face runs [app.py](app.py). It starts the Telegram bot, the Rubika upload worker, and the dashboard on port `7860`.\n\n## Hugging Face Free Plan Sleep\n\nOn the free `CPU Basic` hardware, Hugging Face Spaces automatically go to sleep after 48 hours of inactivity. A new visit to the Space wakes it up again, but the bot and workers are not running while the Space is asleep.\n\nCustom sleep times, including never sleeping, are only available after upgrading the Space to paid hardware. See Hugging Face's [Spaces GPU and sleep time settings](https:\u002F\u002Fhuggingface.co\u002Fdocs\u002Fhub\u002Fspaces-gpus#set-a-custom-sleep-time) docs for the current behavior.\n\n## Required Secrets\n\nAdd these in **Space settings -> Variables and secrets -> Secrets**:\n\n```env\nAPI_ID=123456\nAPI_HASH=your_telegram_api_hash\nBOT_TOKEN=123456:your_bot_token\nOWNER_TELEGRAM_ID=123456789\n```\n\nWhere to get them:\n\n- `API_ID` and `API_HASH`: https:\u002F\u002Fmy.telegram.org\n- `BOT_TOKEN`: create a Telegram bot with BotFather\n- `OWNER_TELEGRAM_ID`: your numeric Telegram user ID\n\n`OWNER_TELEGRAM_ID` is strongly recommended. If it is missing or invalid, anyone who can message the bot can use it.\n\n## Optional Variables\n\nAdd these only if you want to change the defaults:\n\n```env\nTELEGRAM_SESSION=walrus\nRUBIKA_SESSION=rubika_session\nRUBIKA_TARGET=me\nRUBIKA_TARGET_TITLE=Saved Messages\nWALRUS_MAX_FILE_BYTES=8589934592\nWALRUS_MIN_FREE_BYTES=536870912\n```\n\nNotes:\n\n- `RUBIKA_TARGET=me` uploads to Rubika Saved Messages.\n- `WALRUS_MAX_FILE_BYTES` defaults to 8 GiB.\n- Set `WALRUS_MAX_FILE_BYTES=0` to disable the app-level file size limit.\n- Telegram bot file downloads are limited by Telegram to 2 GB per file. For larger direct files, use the Space dashboard URL form instead.\n- `file:\u002F\u002F` links are disabled by default. Enable them only if you understand the risk:\n\n```env\nWALRUS_ALLOW_FILE_URLS=true\n```\n\n## Rubika Login\n\nThe easiest setup is through Telegram:\n\n1. Start the Space.\n2. Open your Telegram bot.\n3. Send `\u002Fstart`.\n4. If no Rubika session exists, WalrusHF asks for the Rubika phone number.\n5. Send the OTP or password when prompted.\n\nAfter login, the Rubika session is saved under `\u002Fdata\u002Fwalrus\u002Fsessions`.\n\n## Bot Commands\n\n- `\u002Fstart` - open setup or main menu\n- `\u002Fsettings` - show Rubika account and destination\n- `\u002Fset_rubika` - start Rubika login\n- `\u002Fstatus` - show queue, active transfers, failures, and storage\n- `\u002Ftransfers` - list active, queued, and retryable transfers\n- `\u002Fcleanup` - preview removable files, stale upload state, and dead failed records\n- `\u002Fcleanup confirm` - delete safe cleanup candidates and clear stale state\n- `\u002Fcancel` - show cancel buttons\n- `\u002Fretry \u003Ctask_id>` - retry one failed transfer\n- `\u002Fretry_all` - retry all retryable failed transfers\n\n## Dashboard\n\nThe Space page updates live every 2 seconds. Useful endpoints:\n\n```text\n\u002Fhealth\n\u002Fstatus.json\n```\n\nUseful dashboard checks:\n\n- `Telegram bot: running` means the Telegram process is alive.\n- `Rubika worker: running` means the upload worker is alive.\n- `Config: ok` means required secrets are present.\n- `Queue` shows waiting upload jobs.\n- `Active upload` shows the current Rubika worker task.\n\nYou can also paste a direct `http:\u002F\u002F` or `https:\u002F\u002F` file URL into the dashboard. WalrusHF downloads it inside the Space, queues it for Rubika, and tracks download\u002Fupload progress on the web page. Dashboard URL transfers can be cancelled from the web page, and completed\u002Ffailed\u002Fcancelled items can be cleared with **Clear Done**. This path is separate from Telegram and does not send Telegram status messages.\n\n## Optional Telegram YouTube Downloader Bot\n\nIf you want to turn YouTube video links into Telegram files before sending them to WalrusHF, this third-party bot may be useful:\n\n- [@allsaverbot](https:\u002F\u002Ft.me\u002Fallsaverbot) - converts YouTube video links into downloadable Telegram files\n\nThis bot is not part of WalrusHF and may change, stop working, or apply its own limits. Use it only for content you have permission to download and share.\n\n## Troubleshooting\n\nIf the bot does not respond:\n\n- Check the Space logs.\n- Confirm `API_ID`, `API_HASH`, and `BOT_TOKEN` are real values, not placeholders.\n- Confirm `OWNER_TELEGRAM_ID` is numeric.\n- Restart the Space after changing secrets.\n\nIf uploads stay queued:\n\n- Check dashboard logs for `Rubika worker`.\n- Run `\u002Ftransfers` in Telegram.\n- Make sure Rubika login has completed with `\u002Fstart` or `\u002Fset_rubika`.\n- Confirm the bucket or persistent storage is mounted at `\u002Fdata`.\n\nIf the main progress message does not update:\n\n- The Rubika worker writes progress events locally.\n- The Telegram bot applies those events through Pyrogram.\n- Check logs for `Telegram event bridge failed`.\n\n## Local Test\n\n```bash\npython3 -m venv venv\nsource venv\u002Fbin\u002Factivate\npip install -r requirements.txt\npython app.py\n```\n\nThen open:\n\n```text\nhttp:\u002F\u002Flocalhost:7860\n```\n\n## Safety\n\nThis project is for personal transfer workflows, research, and experimentation. Do not use it for spam, abuse, unauthorized access, privacy violations, or unlawful activity. You are responsible for respecting platform rules, local laws, and other people's rights.\n","WalrusHF 是一个运行在 Hugging Face Space 中的 Telegram 机器人，用于将接收到的文件上传到 Rubika。其核心功能包括接受 Telegram 文件和直接的 HTTP\u002FHTTPS 链接、从 Space 仪表板排队文件 URL、下载文件、队列管理以避免传输重叠、以及上传至 Rubika 的保存消息或频道。此外，它还支持取消、清理、重试等命令，并通过 Telegram 显示进度。技术上基于 Python 和 Gradio 框架构建，适合需要远程管理和监控文件传输过程的场景使用，如数据备份、文件共享等。",2,"2026-06-11 03:59:26","CREATED_QUERY"]