https://github.com/orenlab/pytmbot
pyTMbot is a Docker-first Telegram bot for Docker operations, server monitoring, and secure remote administration.
https://github.com/orenlab/pytmbot
docker dockercontainers dockerimages jinja2 linux management psutil pytelegrambotapi python system-monitoring telegram-bot
Last synced: 25 days ago
JSON representation
pyTMbot is a Docker-first Telegram bot for Docker operations, server monitoring, and secure remote administration.
- Host: GitHub
- URL: https://github.com/orenlab/pytmbot
- Owner: orenlab
- License: mit
- Created: 2024-03-04T13:27:12.000Z (over 2 years ago)
- Default Branch: master
- Last Pushed: 2026-04-07T11:13:05.000Z (2 months ago)
- Last Synced: 2026-04-07T13:15:58.907Z (2 months ago)
- Topics: docker, dockercontainers, dockerimages, jinja2, linux, management, psutil, pytelegrambotapi, python, system-monitoring, telegram-bot
- Language: Python
- Homepage: https://orenlab.github.io/pytmbot/
- Size: 18.8 MB
- Stars: 19
- Watchers: 1
- Forks: 3
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
- Security: SECURITY.md
- Roadmap: docs/roadmap.md
Awesome Lists containing this project
README
Docker-first Telegram bot for container management, server monitoring, and secure remote administration.
---
## 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](https://github.com/eternnoir/pyTelegramBotAPI), [psutil](https://github.com/giampaolo/psutil),
and [docker-py](https://github.com/docker/docker-py).
---
## Quick Start
### 1. Prepare your config
Create `/etc/pytmbot/pytmbot.yaml` following the [settings guide](docs/settings.md).
### 2. Deploy with Docker Compose
```yaml
services:
pytmbot:
image: orenlab/pytmbot:stable
container_name: pytmbot
restart: on-failure
environment:
TZ: UTC
PYTMBOT_STATE_DIR: /run/pytmbot
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,uid=1001,gid=1001
command: [ "--log-level", "INFO" ]
```
```bash
docker compose up -d
```
For a hardened production setup with resource limits, tmpfs, network isolation, and health checks —
see [docs/docker.md](docs/docker.md).
---
## 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
### 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](https://getoutline.org/) server from Telegram.
See [docs/plugins.md](docs/plugins.md) 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 [docs/webhook.md](docs/webhook.md).
---
## Documentation
Full docs: [orenlab.github.io/pytmbot](https://orenlab.github.io/pytmbot/)
| Guide | Description |
|----------------------------------------------|---------------------------------------|
| [Installation](docs/installation.md) | Step-by-step setup |
| [Docker](docs/docker.md) | Docker-specific deployment |
| [Settings](docs/settings.md) | `pytmbot.yaml` reference |
| [Commands](docs/commands.md) | All bot commands |
| [Webhook mode](docs/webhook.md) | Webhook setup and proxy config |
| [Security](docs/security.md) | Hardening and threat model |
| [Access control & 2FA](docs/auth_control.md) | Allowlists and TOTP |
| [Health system](docs/health.md) | Startup and runtime checks |
| [Plugins](docs/plugins.md) | Plugin API and bundled plugins |
| [CLI arguments](docs/bot_cli_args.md) | `--log-level`, `--health_check`, etc. |
| [Architecture](docs/architecture.md) | Internal design overview |
| [Development](docs/development.md) | Contributing and local setup |
| [Roadmap](docs/roadmap.md) | Planned features |
| [Debugging](docs/debug.md) | Logging and troubleshooting |
---
## Contributing
Bug reports, feature requests, and pull requests are welcome. Please read [docs/development.md](docs/development.md)
before submitting a PR.
---
## License
Licensed under the [MIT License](LICENSE).