Skip to Content

Telegram Bot

TL;DR

The Telegram channel (pip install "cmdop-bot[telegram]") uses aiogram to control CMDOP machines from Telegram. Create a bot via @BotFather, set allowed users, and run with TelegramBot(...).run(). Supports /shell, /agent, /files, /skills, and chat mode where plain messages are sent to the AI agent. Includes PermissionManager integration.

Control your CMDOP machines directly from Telegram. Built on aiogram .

How do I set up a Telegram bot?

  1. Create a bot via @BotFather 
  2. Get your bot token
  3. Get your Telegram user ID (use @userinfobot )

How do I install?

# Install cmdop-bot with Telegram channel support (includes aiogram)
pip install "cmdop-bot[telegram]"

How do I use the Telegram bot?

# Import Model for AI tier selection and TelegramBot channel
from cmdop_bot import Model
from cmdop_bot.channels.telegram import TelegramBot
 
# Create a Telegram bot with user allowlist and target machine
bot = TelegramBot(
    token="YOUR_TELEGRAM_BOT_TOKEN",       # Bot token from @BotFather
    cmdop_api_key="cmdop_xxx",             # Your CMDOP API key
    allowed_users=[123456789],             # Only these Telegram user IDs can use the bot
    machine="my-server",                   # Default machine to execute commands on
    model=Model.balanced(),                # AI model tier for /agent commands
)
 
# Start the bot (blocking — runs the aiogram polling loop)
bot.run()

What parameters are available?

ParameterTypeRequiredDescription
tokenstrYesTelegram bot token from @BotFather
cmdop_api_keystrYesCMDOP API key
allowed_userslist[int]NoAllowed Telegram user IDs. None = allow all
permissionsPermissionManagerNoFine-grained permission control
machinestrNoDefault target machine hostname
modelstrNoAI model tier (use Model.balanced() etc.)
serverstrNogRPC server address (e.g. 127.0.0.1:50051)
insecureboolNoDisable TLS (for local dev)
timeoutfloatNoCommand timeout in seconds (default: 30.0)

What commands are supported?

CommandDescription
/startWelcome message
/helpShow available commands
/shell <cmd>Execute shell command
/exec <cmd>Alias for /shell
/agent <task>Run AI agent task
/machine <hostname>Set target machine
/files ls|cat|info [path]File operations
/ls [path]List directory (shortcut)
/cat <path>Read file (shortcut)
/skills listList available skills
/skills show <name>Show skill details
/skills run <name> <prompt>Run a skill
/skill <name> <prompt>Run a skill (shorthand)

What features does the Telegram bot have?

  • Chat mode: Just type messages — no /agent prefix needed
  • MarkdownV2 formatting with syntax highlighting
  • Typing indicators during long operations
  • User allowlist for security
  • Permission manager integration

What environment variables are used?

# Telegram bot token from @BotFather
export TELEGRAM_BOT_TOKEN="your-bot-token"
# CMDOP API key for authenticating with the backend
export CMDOP_API_KEY="cmdop_xxx"
# Default target machine hostname
export CMDOP_MACHINE="my-server"
# Comma-separated list of allowed Telegram user IDs
export ALLOWED_USERS="123456789,987654321"

How do I add permissions?

from cmdop_bot.channels.telegram import TelegramBot
from cmdop_bot import PermissionManager, PermissionLevel
 
# Create a permission manager for fine-grained access control
pm = PermissionManager()
# Grant full admin access to a specific Telegram user
pm.add_admin("telegram:123456789")
# Grant execute-only permission on a specific machine to another user
pm.grant("telegram:555555555", machine="dev-server", level=PermissionLevel.EXECUTE)
 
# Pass the permission manager instead of allowed_users for granular control
bot = TelegramBot(
    token="YOUR_BOT_TOKEN",
    cmdop_api_key="cmdop_xxx",
    permissions=pm,             # Replaces simple allowed_users allowlist
)
 
bot.run()

What does a full example look like?

from cmdop_bot import Model
from cmdop_bot.channels.telegram import TelegramBot
import os
 
# Production-ready setup: load all config from environment variables
bot = TelegramBot(
    token=os.environ["TELEGRAM_BOT_TOKEN"],            # Required: bot token
    cmdop_api_key=os.environ["CMDOP_API_KEY"],         # Required: CMDOP API key
    # Parse comma-separated user IDs from env var into a list of ints
    allowed_users=[int(x) for x in os.environ.get("ALLOWED_USERS", "").split(",") if x],
    machine=os.environ.get("CMDOP_MACHINE"),           # Optional: default machine
    model=Model.balanced(),                            # AI model tier
    timeout=60.0,                                      # 60s timeout per command
)
 
# Entry point — start the bot when script is run directly
if __name__ == "__main__":
    bot.run()
Last updated on
Overview