pytmbot

KO | EN

gitlite — search

#javascript #python #ai #llm #go #android #linux #windows #awesome #cli #vue #mcp #openai #open-source

(★ 18)

pyTMbot is a Docker-first Telegram bot for Docker operations, server monitoring, and secure remote administration.

pytmbot Latest Version Download

Download Latest Version (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

<p>Docker-first Telegram bot for container management, server monitoring, and secure remote administration.</p>

</div>

---

## 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](https://orenlab.github.io/pytmbot/settings/).

### 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 the [Docker runtime guide](https://orenlab.github.io/pytmbot/docker/).

---

## 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 the [plugins guide](https://orenlab.github.io/pytmbot/plugins/) 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](https://orenlab.github.io/pytmbot/webhook/).

---

## Documentation

Full docs: [orenlab.github.io/pytmbot](https://orenlab.github.io/pytmbot/)

| Guide                                        | Description                           |
|----------------------------------------------|---------------------------------------|
| [Installation](https://orenlab.github.io/pytmbot/installation/)         | Step-by-step setup                    |
| [Docker](https://orenlab.github.io/pytmbot/docker/)                     | Docker-specific deployment            |
| [Settings](https://orenlab.github.io/pytmbot/settings/)                 | `pytmbot.yaml` reference              |
| [Commands](https://orenlab.github.io/pytmbot/commands/)                 | All bot commands                      |
| [Webhook mode](https://orenlab.github.io/pytmbot/webhook/)              | Webhook setup and proxy config        |
| [Security](https://orenlab.github.io/pytmbot/security/)                 | Hardening and threat model            |
| [Access control & 2FA](https://orenlab.github.io/pytmbot/auth_control/) | Allowlists and TOTP                   |
| [Health system](https://orenlab.github.io/pytmbot/health/)              | Startup and runtime checks            |
| [Plugins](https://orenlab.github.io/pytmbot/plugins/)                   | Plugin API and bundled plugins        |
| [CLI arguments](https://orenlab.github.io/pytmbot/bot_cli_args/)        | `--log-level`, `--health_check`, etc. |
| [Architecture](https://orenlab.github.io/pytmbot/architecture/)         | Internal design overview              |
| [Development](https://orenlab.github.io/pytmbot/development/)           | Contributing and local setup          |
| [Roadmap](https://orenlab.github.io/pytmbot/roadmap/)                   | Planned features                      |
| [Debugging](https://orenlab.github.io/pytmbot/debug/)                   | Logging and troubleshooting           |

---

## Contributing

Bug reports, feature requests, and pull requests are welcome. Please read the [development guide](https://orenlab.github.io/pytmbot/development/)
before submitting a PR.

---

## License

Licensed under the [MIT License](LICENSE).

pytmbot

pytmbot Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

pytmbot

pytmbot Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

Download README