proxmox-telegram-bot

KO | EN

gitlite — search

#javascript #hacktoberfest #typescript #golang #go #android #docker #nodejs #macos #windows #awesome #cli #vue #security

proxmox-telegram-bot

(★ 15)

🤖 Telegram-бот для управления Proxmox VE: мониторинг хоста, управление VM/LXC, консоль и автоматические алерты.

proxmox-telegram-bot Latest Version Download

Download Latest Version (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# 🤖 Proxmox VE Telegram Bot

[![Python 3.11+](https://img.shields.io/badge/Python-3.11%2B-3776AB.svg?logo=python&logoColor=white)](https://python.org)
[![python-telegram-bot](https://img.shields.io/badge/telegram--bot-v22.8-2CA5E0.svg?logo=telegram)](https://python-telegram-bot.org)
[![Proxmox VE](https://img.shields.io/badge/Proxmox-8.x%2B-EC6601.svg?logo=proxmox)](https://proxmox.com)
[![License MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT)
[![Version](https://img.shields.io/badge/Version-2.0-blue.svg)](https://github.com/sliva/proxmox-telegram-bot)

> **The most advanced and secure Telegram bot for managing Proxmox VE in 2025**  
> Everything a sysadmin needs: monitoring, alerts, VM/LXC management, and a secure shell – right from your chat.

---

## ✨ Features

---

## 🚀 Quick Start

### Prerequisites

- Proxmox VE 8.x or later
- Python 3.11+
- A Telegram bot token (from [@BotFather](https://t.me/BotFather))
- Your Telegram user ID (from [@userinfobot](https://t.me/userinfobot))

### Installation

```bash
cd /opt
git clone https://github.com/sliva/proxmox-telegram-bot.git
cd proxmox-telegram-bot

# Option 1: Automated install (recommended)
bash install.sh

# Option 2: Manual install
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
```

### Configuration

Create a `.env` file in the root directory:

```env
# Telegram
BOT_TOKEN=your_bot_token_from_BotFather
WHITELIST=your_telegram_id

# Proxmox (API Token recommended!)
HOST=your_proxmox_ip
PROXMOX_TOKEN_NAME=telegram-bot@pve!
PROXMOX_TOKEN_VALUE=your_token_value
PROXMOX_PORT=8006

# Language (en, ru, es)
LANGUAGE=en

# Alerts
CPU_TEMP_THRESHOLD=80
CPU_USAGE_THRESHOLD=70
RAM_USAGE_THRESHOLD=70
CHECK_INTERVAL=300

# Battery (optional, for laptops)
BATTERY_SHUTDOWN_THRESHOLD=50
```

> 💡 **How to create an API token in Proxmox VE:**  
> Go to `Datacenter → Permissions → API Tokens → Add`.  
> Disable *Privilege Separation* and assign the token the `Administrator` role on `/` with **Propagate** checked.

### Run

```bash
python3 main.py
```

---

## 🛠 System Services

### Install as systemd service

```bash
bash install.sh
```

This will:
- Install system dependencies (`upower`, `curl`)
- Create virtual environment and install packages
- Set up systemd services for the bot
- Configure cron jobs for battery and internet monitoring
- Create system event logging

### Service Management

| Command | Action |
| --- | --- |
| `systemctl start proxmox-telegram-bot` | Start the bot |
| `systemctl stop proxmox-telegram-bot` | Stop the bot |
| `systemctl restart proxmox-telegram-bot` | Restart the bot |
| `systemctl status proxmox-telegram-bot` | Check status |
| `journalctl -u proxmox-telegram-bot -f` | Follow logs |

### Manual systemd setup (alternative)

Create `/etc/systemd/system/proxmox-bot.service`:

```ini
[Unit]
Description=Proxmox VE Telegram Bot
After=network.target

[Service]
Type=simple
User=root
WorkingDirectory=/opt/proxmox-telegram-bot
ExecStart=/opt/proxmox-telegram-bot/venv/bin/python /opt/proxmox-telegram-bot/main.py
Restart=always
RestartSec=10
StandardOutput=journal
StandardError=journal

[Install]
WantedBy=multi-user.target
```

Then:

```bash
systemctl daemon-reload
systemctl enable --now proxmox-bot.service
```

### Uninstall

```bash
bash uninstall.sh
```

---

## 🎯 Bot Commands

| Command | Description |
| --- | --- |
| `/start` | Show help menu |
| `/status` | Host status (uptime, CPU, RAM, disks, temperature, battery) |
| `/vm` | List VMs with metrics and control |
| `/lxc` | List LXC containers with metrics and control |
| `/console <cmd>` | Execute shell command on host (with safety restrictions) |
| `/history` | View last 50 system events |

---

## 🛡️ Security

- **Whitelist Authorization** – Non‑whitelisted users are blocked, admins receive intrusion alerts.
- **Secured Console** – Blocks dangerous commands via regex:
  - `rm -rf /`, `mkfs`, `fdisk`, `dd of=/dev/`, `wipefs`
  - `shutdown`, `reboot`, `halt`, `poweroff`
  - Fork bombs and other dangerous constructs
- **Execution Timeouts** – 30s max per command.
- **Output Truncation** – 4000 character limit for Telegram API compatibility.

---

## 📁 Project Structure

```
proxmox-telegram-bot/
├── main.py                    # Bot entry point
├── config.py                  # Configuration from .env
├── requirements.txt           # Python dependencies
├── install.sh                 # Automated installer
├── uninstall.sh               # Uninstaller
├── README.md                  # Documentation
├── LICENSE                    # MIT License
│
├── core/                      # Core modules
│   ├── __init__.py
│   ├── auth.py                # Whitelist auth + alerts
│   └── logger.py              # Logging setup
│
├── handlers/                  # Bot command handlers
│   ├── __init__.py
│   ├── common.py              # /start, /status
│   ├── console.py             # /console
│   ├── resources.py           # /vm, /lxc with inline UI
│   ├── routers.py             # Command routing
│   ├── system.py              # /history
│   └── terminal.py            # Terminal input handler
│
├── language/                  # Localization
│   ├── __init__.py
│   ├── loader.py              # Translation loader
│   ├── en.json                # English
│   ├── es.json                # Spanish
│   └── ru.json                # Russian
│
├── proxmox/                   # Proxmox API (via proxmoxer)
│   ├── __init__.py
│   ├── client.py              # API client wrapper
│   ├── vms.py                 # VM operations
│   ├── lxcs.py                # LXC operations
│   └── utils.py               # Helpers
│
├── services/                  # Background services
│   ├── __init__.py
│   └── alerts.py              # Monitoring & alerts
│
└── system/                    # System utilities
    ├── __init__.py
    ├── checks.py              # Metric checks
    ├── sensors.py             # Hardware sensors
    ├── battery-monitor.sh     # Battery monitor script
    ├── internet-monitor.sh    # Internet monitor script
    ├── notify_startup.sh      # Startup notification
    ├── system-event-manager.sh # Event log manager
    ├── proxmox-telegram-bot.service  # Bot systemd service
    ├── notify-startup.service        # Startup service
    └── battery-monitor.service       # Battery service
```

---

## 🙏 Credits

Special thanks to **Wander J. ([@WJMD](https://github.com/WJMD))** for contributions including internationalization support and system telemetry improvements.

---

## 📄 License

**MIT License** – full freedom of use with responsibility.

---

## 🤝 Contributing

Pull requests are welcome. For major changes, please open an issue first.

---

### ⭐ If you like this project, give it a star!

### 🐛 Found a bug? – Open an Issue

### 💡 Want to help? – Pull Requests are welcome!

proxmox-telegram-bot

proxmox-telegram-bot Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

proxmox-telegram-bot

proxmox-telegram-bot Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

Download README