TDrive

Your files, organized around your own Telegram account.

A desktop and mobile file manager with media streaming, encrypted photo and video backup, shared drives, and a scriptable CLI.

Download TDrive · Get started · Features · Photo backup · CLI and agents · Build

[!IMPORTANT] TDrive is an independent educational project and is not affiliated with Telegram. Use it responsibly and follow Telegram's terms. Do not treat Telegram or TDrive as the only copy of irreplaceable data.

Download

Download packages from GitHub Releases, not from unofficial mirrors. Open the release's Assets list and choose the package for your device.

The Windows installer runs per user without administrator rights. The portable zip contains the same application without the installer.

Linux AppImages require glibc 2.35 or newer (Ubuntu 22.04 or a compatible distribution). For the first upgrade from v2.0.0 or earlier, download TDrive-v2.0.1-x86_64.AppImage manually, make it executable, and launch it. Earlier versions' in-app updater expects the old filename; v2.0.1 recognizes the new name for subsequent updates. Your existing account and drive data are retained.

Android installation

1. Download the signed ARM64 APK from a release that includes it.
2. Open the APK and allow installation from your browser or file manager if Android asks.
3. Install TDrive, then follow Quick start.

Updates are manual: download a newer APK from GitHub and install it over the existing release build. Official release updates use the same signing certificate.

Quick start

1. Install the app for your platform.
2. Create your own Telegram API ID and API hash at my.telegram.org/apps. Telegram provides setup instructions.
3. Enter those credentials in TDrive's setup screen.
4. Sign in with your phone number, Telegram login code, and 2FA password if enabled.
5. Choose the Telegram channel containing your existing My Drive, or create a new empty drive if this is your first setup.
6. Upload a file, create a folder, open the gallery, or join a shared drive.

TDrive stores your API credentials locally; it does not ship a shared project-wide Telegram credential. Keep the API hash, login session, and vault password private.

Already use TDrive on another device? Sign into the same Telegram account and select the same personal-drive channel. If encryption is configured, unlock it with your existing vault password. A new device does not need a new encryption password for that drive.

Screenshots

Gallery	File viewer	Encrypted file unlock

Features

Store and organize

• A private My Drive plus collaborative shared drives.
• Nested folders with rename, move, drag-and-drop, search, and delete.
• Files larger than 2 GB, automatically split across Telegram messages and presented as one file.
• Recursive folder downloads with transactional publishing to the destination.
• Light and dark themes on desktop and mobile.

Import and transfer

• Upload files or whole folders from the desktop app or CLI.
• Import .zip, .tar, and .tar.gz archives, with optional extraction.
• Drop files and folders from the operating system directly into TDrive.
• Concurrent uploads, cancellable transfers, progress, speed, and resilient retries.

Preview and stream

• Browse photos in a drive-wide gallery.
• Preview images, PDF, text, code, audio, and video without leaving the app.
• Stream media directly from Telegram, including encrypted personal-drive media.
• Desktop mpv playback for formats the system webview cannot decode, including MKV and HEVC.
• Audio-track, subtitle, playback-speed, picture-fit, and subtitle-appearance controls.
• Drag or swipe the video timeline to seek. Available codecs and playback controls depend on the platform and player.

Back up photos and videos

• Encrypted backup to My Drive from selected desktop folders or folders on Android device storage.
• A persistent queue with pause, resume, retries, and upload progress.
• Original files stay on your device. See Photo and video backup for permissions and background limits.

Share and collaborate

• Shared drives backed by Telegram megagroups.
• Instant-join or approval-required invite links.
• Join-request approval and uploader attribution inside TDrive.
• Collaborative file and folder organization for drive members.

Mount and automate

• Mount TDrive in Finder, Explorer, or a Linux file manager through a private local WebDAV endpoint.
• Personal drives are read/write, including encrypted content; shared drives are read-only.
• Use the CLI for terminal workflows, scripts, imports, vault access, synchronization, and mounts.
• Interrupted personal-drive writes are journaled and recovered safely.

Protect and recover

• Optional client-side XChaCha20-Poly1305 encryption for personal-drive file contents.
• Live synchronization while Telegram activity arrives.
• Local SQLite state can be rebuilt from Telegram history after cache or configuration loss.

Photo and video backup

Open Photo & video backup from the desktop account menu or the Android Account tab. Choose your folders and start backup. Files go into Photo backup / <device> / <source> inside My Drive, under your selected destination parent if configured.

Backup is encrypted and personal-drive-only. It reuses your drive's existing vault: unlock it with the same password used on your other devices. If that drive has no vault yet, TDrive asks you to set one up.

Backup never deletes device originals. Removing a source does not delete files already uploaded to TDrive. Pause, queue state, and confirmed uploads are remembered across restarts.

Mobile permissions determine which media TDrive can see. Discovery runs while the app is active; an in-flight upload may continue with a native background allowance. Backup is not a continuously scheduled uploader and cannot continue after the app process is terminated. Keep the app open for the initial backup of a large library.

For the detailed recovery, staging, and platform limits, see the backup documentation.

How it works

1. My Drive is a private Telegram channel owned by you.
2. Shared drives are Telegram megagroups whose members can collaborate.
3. File bodies are sent as Telegram document messages. Large files use multiple immutable parts.
4. Folders, moves, renames, deletes, policies, and encryption information are represented by small TDX1|... metadata messages.
5. SQLite is a rebuildable local projection of that Telegram-backed state. TDrive replays Telegram history to synchronize or recover it.

[!WARNING] TDX1|... messages are part of the drive history. Do not edit or delete them in the Telegram app; doing so can damage or desynchronize the projected filesystem.

Privacy and encryption

Manual uploads on My Drive can use client-side XChaCha20-Poly1305 encryption. Photo and video backup always uses encryption. TDrive encrypts file contents before sending them to Telegram and decrypts them after the correct vault password is entered.

Important limits:

• Encryption currently applies to personal-drive file contents, not shared drives.
• File names, folder names, sizes, Telegram relationships, and operational metadata remain visible.
• Encrypted streams detect modification and truncation, but the current format does not authenticate namespace/control metadata or bind an entire ciphertext object to one filename.
• One vault password protects the encrypted personal files. It stays in memory only until the app or CLI daemon exits or the vault is locked.
• Changing the password re-wraps the existing master key; it does not re-encrypt every stored file.
• There is no password reset. The optional hint cannot decrypt content.

Shared drives

Shared drives support file and folder upload, download, rename, move, and delete. Members can see who uploaded a file and can organize the shared namespace.

Invite links should be treated like passwords. Use approval-required links when membership needs review, and revoke links that should no longer grant access.

Deleting a shared folder also deletes its contained files after confirmation. Shared drives mount read-only even though they remain writable through the app and CLI.

Command-line interface

The CLI is available for macOS, Linux, and Windows amd64. Most commands automatically start a local daemon that keeps the Telegram connection, sync state, and unlocked vault key warm between commands.

The GUI and CLI daemon cannot use the same backend state simultaneously. Close the GUI before using CLI commands; the CLI reports this conflict instead of starting a second backend.

Install on macOS or Linux

Download and extract the CLI archive for your platform. Open a terminal in the extracted TDrive-...-cli directory, then run:

./install-cli.sh

Reload the shell if the installer updated its configuration, then set up and log in:

tdrive version
tdrive setup --api-id YOUR_ID --api-hash-stdin
tdrive login +15551234567
tdrive whoami
tdrive ls

Run on Windows

Extract the *-windows-amd64-cli.zip release asset and run tdrive.exe from PowerShell:

.\tdrive.exe setup --api-id YOUR_ID --api-hash-stdin
.\tdrive.exe login +15551234567
.\tdrive.exe whoami

Common commands

tdrive drives
tdrive drive use <name|id>
tdrive ls -l
tdrive mkdir -p /Photos
tdrive put photo.jpg /Photos/
tdrive get /Photos/photo.jpg .
tdrive mkdir -p /Imports
tdrive put --extract archive.zip /Imports/
tdrive mv /old /new
tdrive rm -r /folder
tdrive sync
tdrive rebuild
tdrive unlock
tdrive mount
tdrive mount status
tdrive mount stop

Folder and archive imports require the destination folder to exist. Single-file uploads can create or rename the final file path.

Shared-drive commands include drive create, drive link, drive join, drive requests, drive approve, drive deny, and drive leave. Run tdrive help or tdrive <command> --help for the complete command reference.

Automation and agent use

Start with the offline version and command manifest. Neither needs a daemon or Telegram connection. tdrive commands --json is the authoritative list of JSON-supported commands, flags, and mutation behavior.

tdrive version --json
tdrive commands --json

After interactive setup and login, use JSON output and explicit drive IDs for scripts:

tdrive drives --json
tdrive ls /Photos --drive-id 123456789 --json --non-interactive
tdrive put photo.jpg /Photos/photo.jpg --drive-id 123456789 --json --non-interactive

Use the numeric drive ID returned by tdrive drives --json, replacing the example ID above. Drive-scoped JSON commands require --drive-id and canonical absolute remote paths. They do not change the daemon's shared active drive or working directory, so concurrent scripts can target different drives safely. Human-readable output remains the default; --json (or --output json) is opt-in and rejects unsupported commands.

Desktop mount

Use Mount in the app, or close the GUI and run tdrive mount. TDrive starts a private localhost WebDAV endpoint and attaches the selected drive to the operating system until it is ejected.

If the selected encrypted drive is locked, the CLI prompts for its existing vault password and retries the mount. Scripts can supply the password through stdin with tdrive mount --password-stdin --non-interactive; mount start does not support JSON mode.

• macOS: appears in Finder as Tdrive personal.
• Windows: defaults to drive T:. Windows WebDAV has a default 50,000,000-byte file-size limit that must be changed in the OS for larger files.
• Linux: uses the active GIO/GVfs desktop session and requires the GVfs WebDAV backend, such as gvfs-backends on Debian or Ubuntu.

Personal-drive mounts support create, replace, rename, move, and delete. Encrypted writes are staged as ciphertext before Telegram commit. Encrypted uploads require a known content length. Shared-drive mounts remain read-only.

Linux mount behavior depends on the desktop's GIO/GVfs integration and should still be treated as beta.

Known limitations

• TDrive depends on Telegram availability, account access, API behavior, and rate limits.
• It is not a substitute for keeping an independent backup of important files.
• Shared-drive mounts are read-only.
• The Windows CLI is a portable beta without an installer or background system service.
• Folder and archive import is copy-style import, not synchronization or merge; importing the same folder repeatedly may create numbered names.
• tdrive cat may stage decrypted content in a temporary file before writing it to standard output.
• Mobile backup stages originals locally, requires available device storage, and rejects resources larger than 4 GiB. It cannot keep running after the app process is terminated.
• Backup does not deduplicate content across devices or mirror cloud albums. Album and whole-library backup sources are not available.
• iOS can be built from source but has no public App Store, TestFlight, or installable release download yet.

Build from source

Use the Go version declared in go.mod, Node.js 22 with npm, and the pinned Wails v3 CLI below. Install the native dependencies for your platform first; see the build guide and Wails installation guide.

Run these commands from the repository root:

go install github.com/wailsapp/wails/v3/cmd/wails3@v3.0.0-beta.22

# Dependencies and embedded frontend
npm --prefix frontend ci
npm --prefix frontend run build

# CLI
go build -o build/bin/tdrive ./cmd/tdrive

# Desktop development/build
wails3 dev
wails3 task build      # binary only, into build/bin
wails3 task package    # + platform packaging (.app / NSIS installer / AppImage)

Android and iOS build commands are in the mobile build guide.

go test ./...
go vet ./...
npm --prefix frontend run typecheck
npm --prefix frontend run lint
npm --prefix frontend run test:coverage
npm --prefix frontend run build
bash scripts/test-android-version-code.sh
bash scripts/test-android-signer-digests.sh

npx playwright install --with-deps chromium webkit
npm run test:e2e
npx playwright test --config playwright.gallery-webkit.config.ts

Native playback packaging is handled by the scripts under scripts/ and the release workflow. When a bundled runtime is unavailable, TDrive can fall back to mpv from PATH; TDRIVE_MPV_BIN overrides that binary.

Project background

TDrive began as my first Go project and a way to learn Go, Wails, and Telegram APIs. I used AI to help with frontend styling, planning, and some implementation areas where the Telegram documentation was difficult, while focusing my learning on the Go and Telegram side.

Releases and support

• Latest release
• All release notes
• Telegram community: questions, feedback, and discussion
• Report a problem

For bug reports, include the TDrive version, operating system, expected behavior, and steps to reproduce. Redact API hashes, passwords, session data, private filenames, and invite links from logs and screenshots.

Star history

License

TDrive is licensed under the MIT License.