Telegram Drive turns Telegram's familiar file storage into a focused, desktop-style workspace. The app connects directly to Telegram with credentials you provide; it does not run a separate file-storage or relay service. Every application feature is available without payment.

[!IMPORTANT] Telegram Drive is an independent project and is not affiliated with Telegram FZ-LLC. Files remain subject to Telegram's account, service, and per-file limits. Telegram Drive should not be treated as literally unlimited storage or as the only backup of important data.

Contents

• Download and install
• First-time setup
• Features
• Screenshots
• Folder Sync
• Encryption
• Privacy and security
• Android and Google TV
• Documentation
• Build from source

At a glance

Download and install

Desktop 4.1.0 and Android / Google TV 4.1.0 use separate version lines. The desktop release does not update or include Android or Google TV. Downloads are listed below.

The new desktop workspace adds collections, saved searches, a media timeline, Continue Watching, offline trip packs, transfer activity, storage controls, cleanup, and sync previews. Android 4.1.0 includes the latest native media and offline improvements and fixes the folder sidebar reported in issue #212. Install the signed APK over your existing app to preserve its data and activation.

Desktop release assets also include updater/signature sidecars where applicable. Download installers only from this repository's GitHub Releases page. See the Linux packaging and rendering guide for Arch installation, updater ownership, diagnostics, and AppImage safe mode.

First-time setup

Telegram requires third-party clients to use an application API ID and API hash. Telegram Drive does not provide shared credentials.

1. Sign in at my.telegram.org and open API development tools.
2. Create a Telegram application and copy its api_id and api_hash.
3. Install and open Telegram Drive, then enter those credentials locally.
4. Authenticate with your phone number and login code, or use QR login. If Telegram cloud-password protection is enabled, complete that step as well.
5. Open Saved Messages or select/create Telegram channels to use as folders.

[!WARNING] Treat the API hash, Telegram login codes, session data, encryption credentials, REST keys, and WebDAV links as secrets. Do not paste them into issues, logs, screenshots, or support messages.

How it works

Telegram Drive uses Telegram's MTProto API for authentication and file operations:

• Saved Messages appears as the main personal storage location.
• Telegram channels created or selected by the app can appear as folders.
• Transfers move directly between the application and Telegram.
• Desktop metadata, settings, queues, sync state, thumbnails, and preview caches stay on the local device.
• Standard uploads are stored in Telegram in their normal form. Optional TDENC2 uploads are encrypted locally before transfer.

The application caps a Telegram object at exactly 2,000,000,000 bytes. Encrypted files need additional envelope space, so their maximum original plaintext size is slightly lower.

Features

File management and organization

• Grid and list views with virtualized rendering for large folders.
• Adjustable file-card sizing from 50% to 200%.
• Filename search, persistent sorting, multi-select, range selection, and bulk actions.
• Upload, download, rename, copy, move, and delete workflows where Telegram permits them.
• Drag-and-drop uploads and internal drag-and-drop organization.
• Folder creation, rename, deletion, visibility controls, and custom local folder groups.
• Whole-folder uploads with optional ZIP creation before transfer.
• Remote URL uploads with progress, cancellation, retries, redirects, bounded size checks, and resumable ranges when supported by the source server.
• Duplicate-file, empty-folder, media-metadata, and storage-insight tools through the local REST API.

Reliable transfers and desktop operation

• Durable desktop upload and download queues that recover across window and application restarts.
• Independent upload/download concurrency controls, bandwidth controls, pause, resume, retry, cancel, cooldown, network-waiting, and vault-unlock states.
• Background operation from the system tray while transfers are active.
• Native transfer notifications for completion, failure, pause, and attention-required states, with per-category controls.
• Suspend, resume, network-recovery, and Telegram flood-wait handling.
• Verified downloads written through private temporary files and atomically published to their destination.
• A versioned local desktop file inventory so previously scanned folders appear while Telegram reconciliation continues.

Viewing, playback, and archives

• Lazy-loaded thumbnails and bounded memory/disk preview caches.
• Desktop HEIC/HEIF still images use bounded JPEG display renditions in previews, gallery/slideshow and offline viewing. macOS tries /usr/bin/sips first; other desktops need user-installed FFmpeg 8.1 or newer. External opening and downloads keep the original. See HEIC preview limits.
• A desktop image viewer with zoom, pan, fit-to-window, actual-size, wheel, double-click, and keyboard navigation controls.
• Built-in PDF viewer and audio player.
• Video playback with seeking, HLS/fMP4 streaming, remuxing/transcoding fallbacks, and cache recovery for supported plaintext media.
• Native Android playback with system media controls, resume, subtitle/audio-track selection, playback speed, and Picture-in-Picture where supported.
• ZIP, RAR, and 7z archive browsing and extraction, including extraction back into Telegram Drive where the platform supports it.
• Offline preview-cache controls for recently viewed standard files.
• Recorded plain previews, thumbnails and ready offline copies from 3.9.x retain external opening after an update. The first open verifies and registers each private cache file; arbitrary files and edited copies remain refused.

Some media depends on operating-system codec support or FFmpeg. Supported protected audio, video, and PDF content can use authenticated local byte-range streaming while the vault is unlocked, without publishing a persistent plaintext copy. See encrypted-file limitations.

Sharing and local integrations

• Password-protected local download links with optional expiration, listing, and revocation.
• Native Telegram message links for files in public channels.
• An opt-in desktop REST API for programmatic file, folder, bulk, storage, thumbnail, and media operations.
• Opt-in desktop WebDAV access for mounting Telegram Drive in compatible file managers.
• Optional, passphrase-encrypted settings backup through the user's own Telegram Saved Messages. Credentials, API/WebDAV keys, supporter activation, proxy details, and file data are excluded.

[!NOTE] REST, WebDAV, and Telegram Drive share links are served by the running desktop application. They are not hosted public internet links. Keep the app open, do not forward its local ports, and protect every generated password, key, and capability URL.

Personalization, language, and network controls

• System, light, dark, and default appearance preferences.
• Built-in theme presets and a custom-theme editor.
• Reduced-motion and interface-performance preferences.
• 24 selectable production locales with locale-aware dates, numbers, file sizes, and transfer rates.
• Right-to-left document direction and bidirectional-text protections for Arabic, Persian, and Urdu.
• SOCKS5 and HTTP/HTTPS proxy routing with proxy credentials stored in the operating system's secure credential manager.
• Configurable VPN-oriented timeouts, retries, keep-alive behavior, polling, bandwidth, transfer chunk size, and archive limits.
• Signed desktop updates on supported self-updating packages; pacman-managed Arch installs open the verified release for package-manager updates.
• Android share-sheet intake, foreground transfers, and native downloaded-file publication.

Screenshots

Screenshots show representative workflows; small details may change between releases.

Desktop

Android

Additional desktop and mobile captures are available in the screenshots directory.

Folder Sync (desktop)

Folder Sync is an opt-in, bidirectional mapping between a local directory and one Telegram channel on Windows, macOS, or Linux. It compares three states—the current local tree, the current remote tree, and the last successfully synced tree—before changing either side.

Safety behavior includes:

• Explicit conflicts instead of silent overwrites when local and remote versions both change.
• Keep Local, Keep Remote, and Keep Both conflict choices.
• A greater-than-50% mass-deletion guard.
• Atomic temporary-file downloads and exact transfer-size checks.
• Protection against nested mappings, duplicate remote paths, reserved temporary names, incomplete remote scans, and platform-incompatible filenames.
• Vault-aware queue pauses for encrypted mappings.
• A 50,000 file-bearing-message safety ceiling per mapped channel.

Folder Sync is disabled until enabled in Settings → Folder Sync. Read the Folder Sync guide before mapping an important directory, and keep a separate tested backup.

Optional client-side encryption (beta, format frozen)

See the frozen format specification and recovery drill.

Telegram Drive includes opt-in encrypted transfers using the versioned TDENC2 envelope. Standard uploads remain the default. Encryption can be selected as a default for future uploads or chosen for an individual upload.

The implementation provides streaming XChaCha20-Poly1305 encryption before upload, authenticated streaming downloads, optional protection of the original filename and MIME type, vault auto-lock controls, recovery-bundle export/import, per-file state badges, and encryption-aware transfer queues.

[!CAUTION] Telegram Drive cannot recover, reset, or reconstruct a lost vault passphrase, file passphrase, encryption key, or unusable recovery bundle. Protect and test your recovery material and keep an independent backup of important files. Lost credentials or damaged recovery material can make encrypted data permanently unrecoverable.

The encryption design and implementation have not received an independent security audit. Use isolated test data first. This frozen-format beta is not a substitute for a tested backup strategy.

Current encrypted-file limitations

The following operations fail closed for encrypted objects while retaining their normal behavior for standard files:

• In-app encrypted image and archive previews.
• Encrypted thumbnails, HLS/fMP4 remuxing, and transcoding.
• Local plaintext share links and REST/local-server plaintext access.
• WebDAV read, overwrite, rename, move, copy, and delete operations.
• Remote rename of encrypted Telegram media.
• Plaintext-to-encrypted migration, decrypt-in-place migration, rekey/slot-management UI, and full format migration.

TDENC2-protected audio, video, and PDF content can stream in supported in-app viewers while the vault is unlocked. The session-scoped credential is revoked when the vault locks, and the app does not publish a persistent plaintext copy. Download and authenticate other encrypted files before opening them in another application.

Privacy and security

• The Telegram API ID and application state are stored locally. The API hash is kept separately in the desktop operating-system credential manager or Android Keystore; legacy plaintext values are removed only after secure migration succeeds.
• Telegram session data, settings, transfer state, sync metadata, encryption registry data, and vault material are stored locally in the application's data directories.
• Standard uploads send ordinary file content to Telegram. TDENC2 uploads send ciphertext, although Telegram can still observe transport/account metadata such as ciphertext size, time, account, and destination channel.
• The project does not operate a separate file-relay service.
• Crash reporting is disabled by default and requires explicit consent. Reports exclude file names, paths, contents, messages, Telegram identifiers, credentials, phone numbers, and user-entered values.
• The REST API and WebDAV server are disabled by default and bind only to 127.0.0.1.
• The REST API stores only a hash of its generated key; the plaintext key is shown once.
• WebDAV capability links are shown once and can be revoked by regeneration.
• Proxy credentials use the operating system's secure credential manager.
• Optional supporter verification receives no Telegram credentials or file activity and does not create a purchaser email profile.

Read the complete Privacy Policy, WebDAV guide, and REST API reference.

Languages

Telegram Drive supports a System language preference and these 24 selectable locales:

Locale selection and formatting are production-supported. Authentication, encryption, desktop supporter copy and visible data arrays use canonical translations, and the eleven large locales have zero copied-English findings. Mobile follow-up changes remain local under the owner’s pre-commit hook. Noncritical English copy and full native-language, legal-copy, RTL, long-string, CJK and device review remain outstanding; see the measured locale review.

Optional $5 lifetime ad-free supporter license

Every Telegram Drive feature is available to non-paying users. Supported desktop and Android builds offer an optional $5.00 USD Lifetime Ad-Free Supporter License that removes sponsor placements on up to three supported Windows, macOS, Linux, or Android devices in total after one verified PayPal payment.

• It is a one-time purchase, not a subscription.
• Existing purchasers are not required to pay again after normal application updates.
• Active and offline-grace entitlements keep sponsor placements hidden.
• Reinstallation or another device can be restored with the recovery code, subject to the three-device allowance.
• Checkout is available only inside Settings → Privacy → Supporter.
• Payment does not create a Telegram Drive account or purchaser email profile.

[!WARNING] Save the recovery code shown after activation. Payment alone does not bypass verification. Refunds are not automatic or guaranteed except where required by law. A refund, payment reversal, chargeback, or upheld dispute revokes the associated ad-free entitlement. Read the Supporter Terms before paying.

Android and Google TV (signed APK)

The Android build is currently distributed separately from the desktop release as a signed sideload release. It is not available through Google Play.

1. Open the Android / Android TV 4.1.0 release.
2. Download the signed universal Android APK listed in that release.
3. On Android, allow Install unknown apps for the browser or file manager you used.
4. Open the APK and choose Install.
5. Enter your own Telegram API ID and API hash on first launch.

Android requirements and notes:

• Android 7.0 / API 24 or newer.

• One signed APK supports phones, tablets, Android TV, and Google TV.

• Google TV users can transfer the APK to the television or install it with ADB:

  adb install -r Telegram-Drive-v4.1.0-android-universal.apk
  

• Android validates the package signature during installation. Future compatible updates must use the same signing identity.

• Release maintainers should follow the Android and Google TV release runbook.

Local REST API and WebDAV

Both integrations are desktop-only, disabled by default, and loopback-only.

Do not expose these ports to a LAN or the internet. See the REST API endpoint reference and WebDAV guide for setup, security behavior, examples, and limitations.

Documentation

User documentation

Maintainer and release documentation

Build from source

Prerequisites

• Node.js: 20.19.0+ within Node 20, or 22.12.0+.
• Rust: the latest stable toolchain installed with rustup.
• Telegram API credentials: an api_id and api_hash created at my.telegram.org.
• Tauri system dependencies: follow the official Tauri 2 prerequisites for your platform.

Common requirements:

• macOS: Xcode Command Line Tools (xcode-select --install).

• Windows: Visual Studio Build Tools with Desktop development with C++ and the Microsoft Edge WebView2 Runtime.

• Ubuntu/Debian:

  sudo apt-get update
  sudo apt-get install -y libwebkit2gtk-4.1-dev build-essential curl wget file \
    libssl-dev libdbus-1-dev libgtk-3-dev libayatana-appindicator3-dev \
    librsvg2-dev libfuse2
  

Install and run

git clone https://github.com/caamer20/Telegram-Drive.git
cd Telegram-Drive/app
npm ci
npm run tauri dev

The first run downloads and compiles the Rust dependency graph and may take several minutes. Later builds reuse Cargo's compilation cache.

Create release bundles with:

cd app
npm run tauri build

On Windows, the build scripts download and validate Microsoft's signed Visual C++ Redistributable before creating the NSIS installer.

Validation

Behavioral tests are end-to-end journeys; there are no unit suites. Run the relevant checks from app/ before submitting changes:

npm run build:verify
npm test
npm run i18n:check
cd src-tauri
cargo fmt --all -- --check
cargo clippy --locked --features native-e2e --lib --all-targets -- -D warnings
cargo test --locked --features native-e2e --test native_e2e

node scripts/run-e2e.cjs from the repository root runs every host suite. See TESTING.md for what each suite covers and what still needs installed-app or device acceptance.

The application is built with Tauri 2, Rust, React 19, TypeScript, Tailwind CSS 4, TanStack Query/Virtual, SQLite, Tokio, Actix Web, Grammers, PDF.js, HLS.js, and MP4Box.

Support and community

• Report reproducible, non-sensitive problems through GitHub Issues.
• Use GitHub Discussions for questions, ideas, and general feedback.
• Never include Telegram credentials, session data, payment identifiers, recovery codes, encryption keys, private filenames, or file contents in a public report.
• For a sensitive security report, follow the private-disclosure guidance in the Security Policy.

Direct cryptocurrency tips help support development but do not activate the lifetime ad-free entitlement:

---

TV field navigation

With TV directional navigation, arrows edit a focused native field. After finishing an edit (or closing a native select picker), press Escape to return that field to directional navigation; the next arrow moves focus to another control. Enter resumes editing. A second Escape while already in navigation mode keeps the normal dialog-close behavior. Browser Escape is verified; physical Google TV Back event delivery and remote acceptance remain unrun.