pyTMbot

pyTMbot is a Docker-first Telegram bot for Docker operations, server monitoring, and secure remote administration. It supports both polling and webhook modes and can be extended through a modular plugin system.

Why pyTMbot

• Manage Docker from Telegram: containers, images, logs, volumes, and networks
• Monitor host health: CPU, memory, disk, network, sensors, uptime, users, and quick views
• Secure administration: allowlists, admin-only actions, 2FA/TOTP, rate limiting, safer webhook handling
• Production-ready Docker deployment with structured logging, health checks, and config migration
• Extensible architecture through plugins and Jinja2-based templating

pyTMbot is built on pyTelegramBotAPI, psutil, and docker-py.

Key capabilities

Docker management

• Start, stop, restart, inspect, and browse containers
• View container logs with pagination and export support
• Inspect and manage Docker images with metadata and tag details
• Browse Volumes and Networks with optional 2FA protection
• Check for newer image versions against Docker Hub
• Use inline interactions for faster Telegram-based operations

Server monitoring

• Quick system and Docker summary pages with live refresh
• Detailed CPU, memory, swap, network, disk, user, fan, and sensor views
• Load average, uptime, filesystem, and process insights
• Health monitoring subsystem with startup and component-level checks

Security and reliability

• Access restricted by allowed_user_ids and allowed_admins_ids
• TOTP-based 2FA for sensitive actions
• Request rate limiting and duplicate update protection
• Safer webhook deployments with trusted proxy / IP validation
• Secure message deletion scheduling and improved masking in logs
• Better handling of Telegram API edge cases such as long messages and rate limits

Plugins

• Extend the bot with custom modules and simple configuration
• Included examples:
  • Monitor Plugin — notifications for CPU, memory, disk, temperature, container, and image changes
  • Outline VPN Plugin — monitor your Outline VPN server from Telegram

See docs/plugins.md for details.

What's new in 0.3.0

• Expanded server monitoring views and streamlined quick-view navigation
• Docker UI pagination for containers, images, and logs
• Log export and configurable log format (human / json)
• Health checks with clearer startup reporting
• Automatic configuration migration/versioning
• Improved performance, caching, masking, and strict typing
• Updated build/runtime stack: Python 3.12+ and modern Docker toolchain

Requirements

Current 0.3.x builds are supported in Docker / Docker Compose deployments.

• Python 3.12+ runtime baseline
• Docker Engine 20.10+
• Docker Compose v2.0+ recommended
• Docker socket access for container-management features

Operating modes

• Polling — easiest to deploy; no HTTPS or public endpoint required
• Webhook — lower latency; requires a public hostname for Telegram setWebhook

Logging defaults

• INFO and above: concise errors without full traceback dumps
• DEBUG: full stack traces preserved

Install

Use the Docker-focused setup guides:

• docs/installation.md
• docs/docker.md

Documentation

Live docs site: orenlab.github.io/pytmbot

• Docs index
• Installation
• Architecture
• Settings
• Command reference
• Webhook mode
• Health system
• Security
• Access control and 2FA
• Plugins
• CLI arguments
• Debugging
• Development
• Roadmap

Docker Hub

Official image: orenlab/pytmbot

License

Licensed under the MIT License. See LICENSE.