WalrusHF deploys a Telegram bot within a Hugging Face Space to handle file transfers to Rubika, an Iranian messaging app. Users send files or links via Telegram, where the bot manages downloads and queues uploads to either Rubika Saved Messages or a specified channel. The Hugging Face Space serves as a live dashboard displaying process health, queue status, storage usage, and logs. This setup provides a serverless option compared to the original VPS-hosted Walrus project.

The project, written in Python with 44 GitHub stars, uses Gradio for the dashboard interface in app.py. It targets users familiar with Telegram and Rubika who need automated file bridging without managing their own server. A Persian README is available for Farsi speakers.

Core features

WalrusHF handles file operations through Telegram commands and the dashboard:

  • Accepts files from Telegram messages or direct http:///https:// links.
  • Queues Rubika uploads to avoid overlaps, with progress updates in Telegram for downloads, uploads, retries, and failures.
  • Supports commands like cancel, cleanup, retry, retry-all, and Rubika login.
  • Allows queuing direct file URLs straight from the Space dashboard, bypassing Telegram.
  • Downloads files within the Space runtime and stores sessions, queues, and data in /data/walrus (or /tmp/walrus without persistent storage).

Telegram acts as the primary control interface, while the Space page on port 7860 offers real-time monitoring.

Getting it running

Deployment relies on Hugging Face Spaces infrastructure. Start by creating a new Space at https://huggingface.co/spaces with these settings:

  • Space SDK: Gradio
  • Gradio template: Blank
  • Hardware: CPU Basic
  • Visibility: Private (recommended)
  • Space name: Something like walrushf

Enable persistent storage by mounting a bucket:

  • Create or select a private bucket.
  • Set Mount path to /data.
  • Choose Access mode: Read & Write.

Without this, data persists only in /tmp/walrus, which clears on Space restarts.

Clone and push the repository to the Space:

git clone [email protected]:rezaaa/WalrusHF.git
cd WalrusHF
git remote add space https://huggingface.co/spaces/USERNAME/SPACE_NAME
git push space main:main

Replace USERNAME/SPACE_NAME with your details. If the push fails due to existing files, use:

git push --force-with-lease space main:main

After pushing, add secrets in Space settings > Variables and secrets > Secrets:

API_ID=123456
API_HASH=your_telegram_api_hash
BOT_TOKEN=123456:your_bot_token
OWNER_TELEGRAM_ID=123456789

Obtain these from:

  • API_ID and API_HASH at https://my.telegram.org.
  • BOT_TOKEN via Telegram's BotFather.
  • OWNER_TELEGRAM_ID as your numeric user ID (strongly recommended to restrict access).

Optional environment variables adjust defaults, such as RUBIKA_TARGET=me for Saved Messages, RUBIKA_SESSION=rubika_session, WALRUS_MAX_FILE_BYTES=8589934592 (8 GB limit), and others listed in the README.

Restart the Space, then send /start to your Telegram bot. The app.py script launches the bot, Rubika upload worker, and Gradio dashboard.

Free CPU Basic Spaces sleep after 48 hours of inactivity, halting the bot until woken by a visit. Paid hardware avoids this.

Who this is for

WalrusHF suits Rubika users who receive files via Telegram and want automated forwarding without a VPS. It works for personal file management, like saving media to Saved Messages, or channel uploads. Dashboard queuing helps monitor bulk transfers directly in the browser.

Owners benefit from Telegram commands for fine control—retry failed uploads or clear queues—while the Space provides visibility into storage and health metrics. Restrict access with OWNER_TELEGRAM_ID to keep it private. If you handle frequent file links exceeding Telegram's limits, the 8 GB max file size (configurable) and queueing prevent overloads.

It's less ideal for high-volume or always-on needs due to sleep behavior on free tiers.

How it compares

The VPS-hosted Walrus offers full control without platform limits but requires server management. WalrusHF trades that for zero-cost hosting on Hugging Face, at the expense of potential downtime.

Other file transfer bots exist for Telegram-to-other-apps, but few integrate Rubika uploads with a Gradio dashboard. Tools like Telethon-based scripts handle Telegram sessions manually, lacking built-in queuing or HF deployment. For Rubika-specific automation, custom Pyrogram bots are common, though they demand more setup.

WalrusHF stands out for its hybrid interface: Telegram for input, browser for oversight.

This Python project at https://github.com/rezaaa/WalrusHF fills a niche for Rubika-Telegram bridging on free infrastructure—skip it if you need guaranteed uptime or avoid Hugging Face dependencies.

View on GitHub →