Unlimited cloud storage via Telegram.
Encrypted. Open source. No servers.
v3.0.0 MIT License Python 3.11+ AES-256-GCM
Install → View Source

Why TeleVault?

TeleVaultCloud Storage
CostFree$5-30/month
LimitUnlimited15 GB - 2 TB
EncryptionAES-256-GCM client-sideServer-side or none
TrustZero-trust (you hold the key)Trust the provider
Max file size2 GBVaries
SpeedParallel chunk transfersSingle connection

🔒 End-to-end encryption

AES-256-GCM with scrypt key derivation. Your password never leaves your machine. Telegram only sees ciphertext.

⚡ Parallel transfers

Upload 3 chunks, download 5 chunks simultaneously. 100 MB default chunk size.

🔄 Resumable uploads

CRC32-protected progress files survive interruptions. Resume with --resume.

🛡️ Data safety

Atomic config writes, sequential index access, cached lookups, crash-safe upload/delete/stream. Your data comes first.

💾 Git-like backups

Incremental snapshots with retention policies. Restore to any point in time.

📁 FUSE mount

Mount your vault as a local filesystem. On-demand chunk streaming with LRU cache.

🌐 WebDAV server

Access files over HTTP from any device. macOS Finder, Windows Explorer, mobile apps.

🖥️ Terminal UI (beta)

Interactive file browser with detail panel. Still improving — CLI commands are the most reliable.

🔀 Pipeable I/O

cat file | tvt push - · tvt cat file | jq · tvt ls --json

⏰ Auto-backup

Schedule backups with systemd timers or cron. Watch directories for live changes.

Installation

pip

pip install televault
# Optional extras
pip install televault[fuse]        # FUSE mount
pip install televault[webdav]      # WebDAV server
pip install televault[preview]    # Image previews

Quick start

# 1) Get API credentials at https://my.telegram.org
export TELEGRAM_API_ID=your_id
export TELEGRAM_API_HASH=your_hash

# 2) Login
tvt login

# 3) Setup (interactive, validates channel, sends test message)
tvt setup

# 4) Go!
tvt push photo.jpg
tvt ls
tvt pull photo.jpg

Commands

tvt push <file>Upload file (use - for stdin)
tvt pull <file>Download file (-o - for stdout)
tvt ls [--json]List files
tvt cat <file>Stream file to stdout
tvt preview <file>Preview without full download
tvt find <query> [--json]Search files by name
tvt info <file> [--json]Detailed file info
tvt stat [--json]Vault statistics
tvt rm <file>Delete file
tvt verify <file>Verify file integrity
tvt gc [--dry-run]Garbage collection
tvt whoamiShow account info
tvt loginAuthenticate with Telegram
tvt setupConfigure channel (interactive)
tvt channelShow channel info
tvt tuiLaunch terminal UI (beta)
tvt --versionShow version
tvt backup create <dir>Create snapshot
tvt backup create --incrementalIncremental backup
tvt backup create --dry-runShow plan without uploading
tvt backup listList snapshots
tvt backup restore <id>Restore from snapshot
tvt backup prunePrune old snapshots
tvt backup verify <id>Verify snapshot integrity
tvt backup delete <id>Delete snapshot
tvt mount -m ~/driveFUSE mount with streaming cache
tvt mount --read-only -m ~/driveRead-only mount
tvt mount --cache-size 500500 MB LRU cache
tvt serveWebDAV server on :8080
tvt serve --host 0.0.0.0 --port 9090Custom host/port
tvt serve --read-onlyRead-only WebDAV
tvt schedule create <dir> --name dailyCreate daily schedule
tvt schedule listList schedules
tvt schedule install dailyInstall as systemd timer
tvt schedule uninstall dailyRemove systemd timer
tvt watch --path /dataWatch directory for changes
tvt watch --path /data --interval 10Custom poll interval

Security Model

📄
Original File
→
✂️
Chunk (100 MB)
→
🔐
AES-256-GCM
scrypt · per-chunk salt
→
📦
zstd Compress
skips incompressible
→
☁️
Telegram
only sees ciphertext

Your password never leaves your machine. Each chunk gets a random 16-byte salt and 12-byte nonce. BLAKE3 hashes verify integrity at every stage. If you lose your password, there is no recovery.

Contributing

git clone https://github.com/YahyaToubali/televault.git
cd televault
python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev,fuse,webdav,preview]"
pytest                          # Run tests
ruff check src/                  # Lint

Project Structure

  • cli.py — Click CLI, command dispatch, friendly errors
  • core.py — TeleVault class: upload, download, stream
  • telegram.py — MTProto client, channel ops, index
  • models.py — FileMetadata, ChunkInfo, VaultIndex
  • chunker.py — File splitting, ChunkWriter, BLAKE3
  • crypto.py — AES-256-GCM, scrypt, streaming
  • compress.py — zstd compression
  • config.py — Config dataclass, atomic persistence
  • fuse.py — FUSE driver with on-demand streaming
  • preview.py — Terminal preview from headers
  • tui.py — Textual TUI with detail panel

Key Concepts

  • All data in a private Telegram channel as pinned messages + reply chains
  • Files chunked → hashed → compressed → encrypted → uploaded
  • VaultIndex maps file IDs to message IDs (version-gated, 3 retries)
  • Cached index message IDs for O(1) lookups, asyncio.Lock for concurrency safety
  • All CLI errors handled by run_async() — friendly messages only
  • Entry points: tvt and televault
  • 168 tests in tests/
  • MIT license, PRs welcome

See ARCHITECTURE.md for detailed system design.