{"id":24772627,"url":"https://github.com/orenlab/pytmbot","last_synced_at":"2026-05-16T13:04:58.574Z","repository":{"id":225827434,"uuid":"766971799","full_name":"orenlab/pytmbot","owner":"orenlab","description":"pyTMbot is a Docker-first Telegram bot for Docker operations, server monitoring, and secure remote administration.","archived":false,"fork":false,"pushed_at":"2026-04-07T11:13:05.000Z","size":19693,"stargazers_count":19,"open_issues_count":3,"forks_count":3,"subscribers_count":1,"default_branch":"master","last_synced_at":"2026-04-07T13:15:58.907Z","etag":null,"topics":["docker","dockercontainers","dockerimages","jinja2","linux","management","psutil","pytelegrambotapi","python","system-monitoring","telegram-bot"],"latest_commit_sha":null,"homepage":"https://orenlab.github.io/pytmbot/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/orenlab.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":"docs/roadmap.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2024-03-04T13:27:12.000Z","updated_at":"2026-03-23T19:45:42.000Z","dependencies_parsed_at":"2024-03-07T17:47:22.724Z","dependency_job_id":"2a723293-0cc6-40fa-8b48-e3527d36c443","html_url":"https://github.com/orenlab/pytmbot","commit_stats":null,"previous_names":["orenlab/pytmbot"],"tags_count":22,"template":false,"template_full_name":null,"purl":"pkg:github/orenlab/pytmbot","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/orenlab%2Fpytmbot","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/orenlab%2Fpytmbot/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/orenlab%2Fpytmbot/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/orenlab%2Fpytmbot/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/orenlab","download_url":"https://codeload.github.com/orenlab/pytmbot/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/orenlab%2Fpytmbot/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33103971,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-16T04:41:52.686Z","status":"ssl_error","status_checked_at":"2026-05-16T04:41:52.009Z","response_time":115,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["docker","dockercontainers","dockerimages","jinja2","linux","management","psutil","pytelegrambotapi","python","system-monitoring","telegram-bot"],"created_at":"2025-01-29T04:31:20.933Z","updated_at":"2026-05-16T13:04:58.568Z","avatar_url":"https://github.com/orenlab.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n  \u003cpicture\u003e\n    \u003csource\n      media=\"(prefers-color-scheme: dark)\"\n      srcset=\"https://raw.githubusercontent.com/orenlab/pytmbot/master/docs/assets/pytmbot-wordmark-dark.svg\"\n    \u003e\n    \u003csource\n      media=\"(prefers-color-scheme: light)\"\n      srcset=\"https://raw.githubusercontent.com/orenlab/pytmbot/master/docs/assets/pytmbot-wordmark.svg\"\n    \u003e\n    \u003cimg\n      alt=\"pyTMbot\"\n      src=\"https://raw.githubusercontent.com/orenlab/pytmbot/master/docs/assets/pytmbot-wordmark.svg\"\n      width=\"280\"\n    \u003e\n  \u003c/picture\u003e\n\n  \u003cp\u003eDocker-first Telegram bot for container management, server monitoring, and secure remote administration.\u003c/p\u003e\n\n  \u003cp\u003e\n    \u003ca href=\"https://hub.docker.com/r/orenlab/pytmbot/\"\u003e\u003cimg src=\"https://img.shields.io/docker/pulls/orenlab/pytmbot?style=flat-square\u0026logo=docker\u0026logoColor=white\u0026label=pulls\u0026color=1a7fd4\u0026labelColor=2b3137\" alt=\"Docker Pulls\"\u003e\u003c/a\u003e\n    \u003ca href=\"https://hub.docker.com/r/orenlab/pytmbot/\"\u003e\u003cimg src=\"https://img.shields.io/docker/image-size/orenlab/pytmbot?style=flat-square\u0026logo=docker\u0026logoColor=white\u0026label=image%20size\u0026color=1a7fd4\u0026labelColor=2b3137\" alt=\"Image Size\"\u003e\u003c/a\u003e\n    \u003ca href=\"https://github.com/orenlab/pytmbot/releases\"\u003e\u003cimg src=\"https://img.shields.io/github/v/release/orenlab/pytmbot?style=flat-square\u0026logo=github\u0026logoColor=white\u0026color=1a7fd4\u0026labelColor=2b3137\" alt=\"Release\"\u003e\u003c/a\u003e\n    \u003ca href=\"LICENSE\"\u003e\u003cimg src=\"https://img.shields.io/github/license/orenlab/pytmbot?style=flat-square\u0026logo=opensourceinitiative\u0026logoColor=white\u0026color=1a7fd4\u0026labelColor=2b3137\" alt=\"License\"\u003e\u003c/a\u003e\n  \u003c/p\u003e\n\n\u003c/div\u003e\n\n---\n\n## Overview\n\n**pyTMbot** lets you manage Docker containers and monitor server health directly from Telegram — without opening a\nterminal. It supports both **polling** and **webhook** modes, enforces access control with allowlists and TOTP-based\n2FA, and extends via a modular plugin system.\n\nBuilt\non [pyTelegramBotAPI](https://github.com/eternnoir/pyTelegramBotAPI), [psutil](https://github.com/giampaolo/psutil),\nand [docker-py](https://github.com/docker/docker-py).\n\n---\n\n## Quick Start\n\n### 1. Prepare your config\n\nCreate `/etc/pytmbot/pytmbot.yaml` following the [settings guide](docs/settings.md).\n\n### 2. Deploy with Docker Compose\n\n```yaml\nservices:\n  pytmbot:\n    image: orenlab/pytmbot:stable\n    container_name: pytmbot\n    restart: on-failure\n    environment:\n      TZ: UTC\n      PYTMBOT_STATE_DIR: /run/pytmbot\n    volumes:\n      - /var/run/docker.sock:/var/run/docker.sock:ro\n      - /etc/pytmbot/pytmbot.yaml:/opt/app/pytmbot.yaml:ro\n    security_opt:\n      - no-new-privileges:true\n    read_only: true\n    cap_drop:\n      - ALL\n    pid: host\n    tmpfs:\n      - /run/pytmbot:noexec,nosuid,nodev,size=10m,uid=1001,gid=1001\n    command: [ \"--log-level\", \"INFO\" ]\n```\n\n```bash\ndocker compose up -d\n```\n\nFor a hardened production setup with resource limits, tmpfs, network isolation, and health checks —\nsee [docs/docker.md](docs/docker.md).\n\n---\n\n## Features\n\n### Docker management\n\n- Start, stop, restart, inspect, and browse containers\n- View logs with pagination and export\n- Manage images: metadata, tag details, update checks against Docker Hub\n- Browse volumes and networks (optionally protected by 2FA)\n- Inline Telegram interactions for faster operations\n\n### Server monitoring\n\n- Live summary pages for system and Docker state with refresh\n- Per-metric views: CPU, memory, swap, disk, network, sensors, fans, users\n- Load average, uptime, filesystem, and process insights\n- Startup and component-level health checks\n\n### Security\n\n- Access restricted by `allowed_user_ids` and `allowed_admins_ids`\n- TOTP-based 2FA for sensitive actions\n- Rate limiting and duplicate update protection\n- Webhook deployments with trusted proxy / IP validation\n- Secure message deletion scheduling\n- Improved credential masking in structured logs\n\n### Extensibility\n\n- Plugin system for custom modules with minimal configuration\n- Jinja2-based templating for bot responses\n\n---\n\n## Plugins\n\nTwo plugins are included out of the box:\n\n**Monitor Plugin** — push notifications for CPU, memory, disk, temperature, and container/image state changes.\n\n**Outline VPN Plugin** — monitor your [Outline VPN](https://getoutline.org/) server from Telegram.\n\nSee [docs/plugins.md](docs/plugins.md) for the plugin API and configuration reference.\n\n---\n\n## Requirements\n\n| Component      | Requirement                       |\n|----------------|-----------------------------------|\n| Python         | `\u003e=3.12,\u003c4` (CI: 3.12-3.14)       |\n| Docker Engine  | 20.10+                            |\n| Docker Compose | v2.0+                             |\n| Docker socket  | required for container management |\n\n## Operating modes\n\n**Polling** — simplest deployment; no HTTPS or public endpoint required.\n\n**Webhook** — lower latency; requires a public hostname for Telegram `setWebhook`.\nSee [docs/webhook.md](docs/webhook.md).\n\n---\n\n## Documentation\n\nFull docs: [orenlab.github.io/pytmbot](https://orenlab.github.io/pytmbot/)\n\n| Guide                                        | Description                           |\n|----------------------------------------------|---------------------------------------|\n| [Installation](docs/installation.md)         | Step-by-step setup                    |\n| [Docker](docs/docker.md)                     | Docker-specific deployment            |\n| [Settings](docs/settings.md)                 | `pytmbot.yaml` reference              |\n| [Commands](docs/commands.md)                 | All bot commands                      |\n| [Webhook mode](docs/webhook.md)              | Webhook setup and proxy config        |\n| [Security](docs/security.md)                 | Hardening and threat model            |\n| [Access control \u0026 2FA](docs/auth_control.md) | Allowlists and TOTP                   |\n| [Health system](docs/health.md)              | Startup and runtime checks            |\n| [Plugins](docs/plugins.md)                   | Plugin API and bundled plugins        |\n| [CLI arguments](docs/bot_cli_args.md)        | `--log-level`, `--health_check`, etc. |\n| [Architecture](docs/architecture.md)         | Internal design overview              |\n| [Development](docs/development.md)           | Contributing and local setup          |\n| [Roadmap](docs/roadmap.md)                   | Planned features                      |\n| [Debugging](docs/debug.md)                   | Logging and troubleshooting           |\n\n---\n\n## Contributing\n\nBug reports, feature requests, and pull requests are welcome. Please read [docs/development.md](docs/development.md)\nbefore submitting a PR.\n\n---\n\n## License\n\nLicensed under the [MIT License](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Forenlab%2Fpytmbot","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Forenlab%2Fpytmbot","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Forenlab%2Fpytmbot/lists"}