Cuhi is a self-hosted premium media archival ecosystem featuring a Telegram bot, an iOS-inspired Telegram Mini App, and a fully optimized Native Android App. Archiving content from Instagram, TikTok, Facebook, and X (Twitter) has never been this seamless — delivered directly to your Telegram channels, local documents, or phone gallery.
v2.1.0 · Stable Release · Production Hardened
Most downloaders are black boxes. You don't know who has your cookies or where your data goes. Cuhi is different:
- Self-Hosted — You own the code. Your cookies and sessions live on your server, not ours.
- Async Native — Full non-blocking I/O with a dedicated thread pool. Stays responsive under heavy multi-user load.
- Mini App Dashboard — A native iOS-style control panel built right inside Telegram. Manage sources, trigger downloads, view history — all without leaving the app.
- Standalone Android Companion — Packageable as a high-fidelity native app featuring robust offline local saving, fluid layouts, and persistent media gallery integration.
- Production Hardened — OS-level file locking, atomic writes, executor-backed async I/O, and zero bare exceptions.
- Set & Forget — Designed to run 24/7 with automatic schedule recovery after restarts.
The Cuhi Mini App is a full-featured dashboard that runs natively inside Telegram. Built with an iOS-inspired design language.
Cuhi is fully integrated and optimized to run as a native mobile application via Capacitor.
- Interactive Google OAuth Selector: Features a gorgeous, Google-designed Account Selector modal that mimics authentic OAuth flows. Easily switch between cached suggested profiles or add new custom emails seamlessly.
- Responsive Keyboard Viewport Integration: Re-engineered with top-aligned flex-start structures and dynamic scroll calculations. When the virtual keyboard is shown, input fields and headers adjust gracefully with zero layout squashing or overlapping glitches.
- Lenient Scoped Storage Permission Handlers: Engineered specifically for modern Android 11+ and 13+ Scoped Storage guidelines. The app requests media permissions but never halts the sync loop if optional gallery permissions are disabled, writing files natively to your device's standard
Documents/Cuhifolder. - Adaptive Native Settings Panel: Dynamically hides Telegram-specific forward channels and Cron server schedulers, keeping the mobile interface clean, responsive, and tailored for standalone on-device archival.
| Feature | Description |
|---|---|
| Dashboard | Real-time stats — sources, files sent, data used, history count, and disk usage |
| Account Page | View your Telegram profile photo, name, username, ID, and premium status |
| Sources Manager | Add and remove profiles across all platforms with one tap |
| Download Control | Choose media type, toggle stories/highlights/force refresh, start/stop downloads |
| History | Browse recent downloads with clear-all support |
| Settings | Configure output channel, schedule, cookies, and appearance |
| Theme System | Dark, Light, and Auto (follows your Telegram theme) |
| Animations | Spring-physics transitions, staggered content entrance, animated counters |
- iOS-authentic border radii (10px groups, 12px cards)
- Glassmorphic nav bar and tab bar with
backdrop-filterblur - Gradient stat card accents (blue, green, orange, purple)
- Apple Color Emoji font stack for consistent icons across platforms
- Haptic feedback on all interactions via Telegram WebApp API
- 📸 Multi-Platform — Instagram, TikTok, Facebook, and X/Twitter
- 🎬 Everything Included — Photos, videos, stories, highlights — packaged into 10-item media groups
- 📡 Auto-Forwarding — Send media to your private channels or groups automatically
- ⏱️ Scheduled Downloads — Set 6h / 12h / 24h intervals with restart recovery
- 🍪 Cookie Support — Upload your own cookies for private and age-restricted content
- 🗂️ Smart Archive — Remembers what was downloaded to avoid duplicates
- 🔗 Instant Links — Use
/link <url>for one-off downloads - 📤 Import/Export — Move your sources between instances
- 🔒 Secure — Admin system, user allowlists, rate limiting, and URL validation
We recommend Railway for the easiest setup, but it runs anywhere with Python 3.11+.
- Fork this repo
- Connect it to a new Railway project
- Add a persistent volume mounted at
/app/data - Set environment variables:
BOT_TOKEN— from @BotFatherALLOWED_USERS— comma-separated Telegram user IDsADMIN_IDS— your Telegram ID
- Deploy
git clone https://github.com/Copyright-News/cuhibot.git
cd cuhibot
pip install -r requirements.txt
export BOT_TOKEN="your-token-here"
python bot.py| Variable | Description | Default |
|---|---|---|
BOT_TOKEN |
Telegram bot token from @BotFather | Required |
ALLOWED_USERS |
Comma-separated list of allowed user IDs | All users |
ADMIN_IDS |
Admin user IDs for /admin panel |
None |
DATA_ROOT |
Path for archives, history, and user data | ./data |
COOKIES_ROOT |
Path for cookie storage | ./cookies |
RAILWAY_PUBLIC_DOMAIN |
Auto-set by Railway for Mini App hosting | Auto |
bot.py — Main bot: handlers, download engine, scheduler, persistence
server.py — FastAPI backend for Mini App (runs in daemon thread)
app.html — Mini App frontend (single-file, zero dependencies)
Key internals:
ThreadPoolExecutorfor non-blocking file I/Oasyncio.Queuefor Mini App → Bot download communicationPTB JobQueuewithpost_initrecovery for scheduled tasks- HMAC-verified
initDataauthentication for all Mini App API calls
We are a small group of developers passionate about open-source tools.
ebnycuhie & sayfalse
Lead Maintainers @ Copyright News
Copyright News
Open Source for Content Archival
📧 mintdmca@gmail.com
- 📋 Changelog: See CHANGELOG.md for version history
- 🗺️ Roadmap: Check out ROADMAP.md to see what's next
- 🛡️ Security: Read SECURITY.md before reporting vulnerabilities
- 📢 Updates: Join @copyrightnews on Telegram
- ⚖️ License: MIT — free to use, free to fork
Made with ❤️ for the Open Source Community
