Overview
pyTMbot lets you manage Docker containers and monitor server health directly from Telegram — without opening a
terminal. It supports both polling and webhook modes, enforces access control with allowlists and TOTP-based
2FA, and extends via a modular plugin system.
Built
on pyTelegramBotAPI, psutil,
and docker-py.
Quick Start
1. Prepare your config
Create /etc/pytmbot/pytmbot.yaml following the settings guide.
2. Deploy with Docker Compose
services:
pytmbot:
image: orenlab/pytmbot:stable
container_name: pytmbot
restart: on-failure
environment:
TZ: UTC
PYTMBOT_STATE_DIR: /run/pytmbot
group_add:
- "${DOCKER_GID:-1001}"
volumes:
- /var/run/docker.sock:/var/run/docker.sock:ro
- /etc/pytmbot/pytmbot.yaml:/opt/app/pytmbot.yaml:ro
security_opt:
- no-new-privileges:true
read_only: true
cap_drop:
- ALL
pid: host
tmpfs:
- /run/pytmbot:noexec,nosuid,nodev,size=10m,mode=0700,uid=1001,gid=1001
command: [ "--log-level", "INFO" ]
To grant access to the Docker socket, set DOCKER_GID once, next to the compose file (without it, group_add
falls back to the bot's own group 1001 and changes nothing):
echo "DOCKER_GID=$(stat -c %g /var/run/docker.sock)" > .env
docker compose up -d
For a hardened production setup with resource limits, tmpfs, network isolation, and health checks —
see the Docker runtime guide.
Features
Docker management
- Start, stop, restart, inspect, and browse containers
- View logs with pagination and export
- Manage images: metadata, tag details, update checks against Docker Hub
- Browse volumes and networks (optionally protected by 2FA)
- Inline Telegram interactions for faster operations
Server monitoring
- Live summary pages for system and Docker state with refresh
- Per-metric views: CPU, memory, swap, disk, network, sensors, fans, users
- Load average, uptime, filesystem, and process insights
- Startup and component-level health checks
Telegram interface
- Structured screens rendered as Telegram Rich Messages with native tables (Bot API 10.1+)
- Persistent section keyboards with color accents and color-coded container actions
- Oversized screens trimmed to Telegram limits, with a plain-text fallback if rich content is rejected
Security
- Access restricted by
allowed_user_ids and allowed_admins_ids
- TOTP-based 2FA for sensitive actions
- Rate limiting and duplicate update protection
- Webhook deployments with trusted proxy / IP validation
- Secure message deletion scheduling
- Improved credential masking in structured logs
Extensibility
- Plugin system for custom modules with minimal configuration
- Jinja2-based templating for bot responses
Plugins
Two plugins are included out of the box:
Monitor Plugin — push notifications for CPU, memory, disk, temperature, and container/image state changes.
Outline VPN Plugin — monitor your Outline VPN server from Telegram.
See the plugins guide for the plugin API and configuration reference.
Requirements
| Component | Requirement |
|---|
| Python | >=3.12,<4 (CI: 3.12-3.14) |
| Docker Engine | 20.10+ |
| Docker Compose | v2.0+ |
| Docker socket | required for container management |
Operating modes
Polling — simplest deployment; no HTTPS or public endpoint required.
Webhook — lower latency; requires a public hostname for Telegram setWebhook.
See the webhook guide.
Documentation
Full docs: orenlab.github.io/pytmbot
Contributing
Bug reports, feature requests, and pull requests are welcome. Please read the development guide
before submitting a PR.
License
Licensed under the MIT License.
