Getting started

cv4pve-botgram runs outside the cluster (on a management VM, a small server, a container) and talks only to the Proxmox VE REST API on port 8006. Nothing is installed on the nodes. The machine it runs on must reach the nodes and, on the Internet, Telegram: the bot connects out and waits for your messages, so no port is opened towards your network.

Installation

Platform	How
Linux	wget https://github.com/Corsinvest/cv4pve-botgram/releases/latest/download/cv4pve-botgram-linux-x64.zip && unzip cv4pve-botgram-linux-x64.zip && chmod +x cv4pve-botgram ARM: cv4pve-botgram-linux-arm64.zip, cv4pve-botgram-linux-arm.zip
Debian / Ubuntu	sudo dpkg -i cv4pve-botgram-VERSION-ARCH.deb (amd64, arm64, armhf)
RHEL / Fedora	sudo rpm -i cv4pve-botgram-VERSION-ARCH.rpm (x86_64, aarch64, armv7hl)
Arch Linux	yay -S cv4pve-botgram
Windows (WinGet)	winget install Corsinvest.cv4pve.botgram
Windows (manual)	cv4pve-botgram.exe-win-x64.zip, also x86 and arm64
macOS (Homebrew)	brew install corsinvest/tap/cv4pve-botgram
macOS (installer)	cv4pve-botgram-VERSION-arm64.pkg (Apple silicon) or -x86_64.pkg (Intel)
macOS (manual)	cv4pve-botgram-osx-arm64.zip or cv4pve-botgram-osx-x64.zip

Binaries are self-contained: no .NET runtime to install. All files are on thelatest release page.

Before the first run

You need two things:

1. A Telegram bot and its token, created in a minute from the Telegram app: see Telegram bot.
2. A Proxmox VE user and API token with the privileges for what the bot should do: see Permissions.

First run

cv4pve-botgram --host=pve1.local --api-token='bot@pve!bot=<uuid>' --token='<telegram-bot-token>' --chatsId=<chat-id>

The bot logs in to the cluster and to Telegram, then prints who it is:

Start listening
Telegram
  Bot User: @your_pve_bot
  Bot UserId: @123456789
Proxmox VE
  pve1.local:8006
Press Ctrl+C to stop.

It stays in the foreground until it is stopped. Open the chat with your bot in Telegram and send /help: the bot answers with the list of its commands, described in Commands.

Options

Option	What it does
--token	Token of the Telegram bot, from BotFather. Required.
--chatsId	Telegram chat IDs allowed to use the bot, separated by commas. See Restrict the bot to your chats.

The bot runs until it is stopped: Ctrl+C in a terminal, systemctl stop, or the Windows service manager. To keep it running after you close the terminal, see Run as a service.

Host, API token, username and password, certificates and keeping the options in a file: see Connection.

Always set –chatsId

Without --chatsId the bot answers every chat: anyone who finds the bot in Telegram can use it with the privileges of its API token. Set it on every run that is not a first test.

Next

• Commands: guests, nodes, and how a conversation with the bot works.
• API commands: any path of the Proxmox VE API from the chat.
• Run as a service: keep the bot running after you close the terminal.