A private NAS file management bot for Telegram — upload, browse, search, and organize files directly from your phone.
- Upload — Send any file; the bot detects its category and suggests the right folder. Navigate the full directory tree to pick a custom destination.
- Browse — Browse NAS contents by category with pagination, file sizes, and timestamps.
- Search — Recursive filename search across the entire NAS with pagination.
- Rename — Rename any file inline from the file options menu.
- Folder Manager — Create, rename, or delete directories via an interactive inline menu.
- Trash — Deleted items move to
.trash/. View, restore, or permanently delete from within the bot. - Storage Monitor — Disk usage with a visual progress bar and health indicator.
- Single-user auth — One authorized Telegram ID. All others are blocked at every entry point.
- Path traversal protection — All paths are validated to stay within the NAS root.
| Layer | Tool |
|---|---|
| Language | Python 3.12+ |
| Bot Framework | aiogram v3 |
| Runtime | Docker |
telegram-nas-manager/
├── main.py # Entry point
├── config.py # Config, auth
├── requirements.txt
├── Dockerfile
├── docker-compose.yml
├── setup.sh
├── handlers/
│ ├── commands.py # /start, /space, keyboard buttons
│ ├── files.py # Upload flow, rename
│ ├── search.py # Browser, /find, file actions
│ ├── folders.py # Create/delete folder wizards
│ └── trash.py # Trash viewer and management
└── utils/
└── storage.py # Disk utils, path validation, sanitization
git clone https://github.com/AssachanDev/telegram-nas-manager.git
cd telegram-nas-managercp .env.example .env| Variable | Description |
|---|---|
BOT_TOKEN |
From @BotFather |
TELEGRAM_CHAT_ID |
Your Telegram user ID — get from @userinfobot |
HOST_DATA_DIR |
Absolute path to your NAS directory on the host |
bash setup.shLogs: docker compose logs -f
The bot uses a persistent Reply Keyboard — no commands needed.
| Button | Description |
|---|---|
| Browse | Browse NAS by category with pagination |
| Find | Search files by name across the entire NAS |
| Folders | Create, rename, or delete directories |
| Trash | View, restore, or permanently delete trashed items |
| Storage | Disk usage and health status |
| (send any file) | Upload flow — select destination folder |
Auto-suggested destination based on extension:
| Category | Extensions |
|---|---|
| Documents | .pdf .docx .xlsx .txt .pptx .md |
| Media | .png .jpg .jpeg .mp4 .mov .gif .mp3 .wav .mkv |
| Data | .csv .json .sql .xml .yaml .yml |
| Scripts | .py .sh .js .ts .go .c .cpp |
| Archives | .zip .tar .gz .7z .rar |
| Other | (everything else) |
Files and folders are moved to .trash/ with a Unix timestamp prefix — never immediately deleted.
/mnt/nas/.trash/
├── 1711900000_report.pdf
└── 1711900050_old-project/
From the Trash menu you can restore items to /Restored/ or delete them permanently. Empty Trash wipes all items at once.