Linux Server Admin Bot

Python Version License Docker

Telegram bot for monitoring Ubuntu servers. Monitor system resources and receive automated alerts - all from Telegram.

• CPU: Real-time usage, per-core breakdown, frequency, load average
• Memory: RAM and swap usage with detailed breakdown
• Disk: Root partition space usage
• Network: Interface statistics, traffic monitoring
• Processes: Top CPU-consuming processes

• Paginated container list (10 per page)
• Container detail view with CPU, memory, IP, ports
• Start, Stop, Restart containers directly from Telegram
• Container status with health indicators
• Graceful detection when Docker is not available

• Beautiful matplotlib charts for all metrics
• CPU usage per core
• Memory distribution pie charts
• Disk usage visualization
• Process resource graphs

• Configurable thresholds for CPU, RAM, and disk
• Automatic notifications when limits exceeded
• Smart cooldown to prevent spam
• Alert severity levels (info, warning, critical)

• User whitelist authentication
• Rate limiting per user
• Comprehensive logging
• Host PID namespace with restricted capabilities (read-only process access)

• Ubuntu server (18.04+)
• Docker and Docker Compose
• Telegram Bot Token (create one)
• Your Telegram User ID (get it)

1. Clone the repository

git clone https://github.com/artcc/linux-server-admin-bot.git
cd linux-server-admin-bot

2. Configure environment

cp .env.example .env
nano .env

Edit .env with your values:

TELEGRAM_BOT_TOKEN=your_bot_token_here
TELEGRAM_ALLOWED_USER_IDS=123456789,987654321
CPU_ALERT_THRESHOLD=80
MEMORY_ALERT_THRESHOLD=80
DISK_ALERT_THRESHOLD=90

3. Create logs directory with correct permissions

mkdir -p logs
sudo chown -R 1000:1000 logs
sudo chmod -R 775 logs

4. Build and run with Docker Compose

docker-compose up -d

5. Check logs

docker-compose logs -f

6. Start chatting with your bot on Telegram!

The bot features a beautiful interactive menu with inline keyboard buttons for easy navigation:

• Main Menu: Access all features with a single tap
• System Monitoring: CPU, Memory, Disk, Network, Processes
• Quick Navigation: Back buttons and menu shortcuts

Just type /start to see the interactive menu!

• /start - Welcome message with interactive menu
• /help - Show all available commands
• /status - Overall system status summary

• /cpu - Detailed CPU information with chart
• /memory - Memory usage with visualization
• /disk - Disk space usage
• /top - Top processes by CPU usage
• /network - Network interface statistics
• /temp - System temperature sensors
• /uptime - System uptime and logged users
• /services - Systemd services status

• /docker - Docker container management menu

• /alerts - View alert configuration and active alerts

• /author - Bot author information

linux-server-admin-bot/
├── bot/
│ ├── handlers/ # Command handlers
│ │ ├── basic.py # Start, help, alerts
│ │ ├── system.py # System monitoring commands
│ │ ├── docker.py # Docker management commands
│ │ └── callbacks.py # Inline keyboard callbacks
│ ├── services/ # Business logic
│ │ ├── system_monitor.py # psutil wrapper
│ │ ├── alert_manager.py # Alert system
│ │ └── docker_manager.py # Docker container management
│ ├── monitors/ # Background tasks
│ │ └── health_monitor.py # Periodic health checks
│ ├── models/ # Data models
│ │ └── metrics.py # Dataclasses for metrics
│ └── utils/ # Utilities
│ ├── decorators.py # Auth, rate limiting, logging
│ ├── formatters.py # Message formatting
│ ├── keyboards.py # Inline keyboard layouts
│ └── charts.py # Chart generation
├── config/ # Configuration
│ ├── settings.py # Pydantic settings
│ ├── constants.py # Constants and enums
│ └── logger.py # Logging setup
├── tests/ # Unit tests
├── docs/ # Documentation
├── main.py # Application entry point
├── Dockerfile # Multi-stage Docker build
├── docker-compose.yml # Docker Compose config
└── requirements.txt # Python dependencies

• Separation of Concerns: Clear separation between handlers, services, and utilities
• Type Safety: Full type hints and Pydantic validation
• Testability: Dependency injection and comprehensive tests
• Security: Authorization, rate limiting, and audit logging
• Observability: Structured logging and error handling
• Scalability: Async/await patterns for concurrent operations

The bot requires access to host system resources:

volumes:
 - /proc:/host/proc:ro # System metrics
 - /sys:/host/sys:ro # System information
 - /var/run/docker.sock:/var/run/docker.sock:ro # Docker management (optional)

Note: The Docker socket mount is optional. If not mounted, the Docker menu will show that Docker is not available.

You can use the official bot avatar for your own instance:

Bot Avatar

Download: linux-server-admin-bot.png

To set this image as your bot's profile picture:

1. Download the image from the link above
2. Open @BotFather on Telegram
3. Send /setuserpic
4. Select your bot
5. Upload the downloaded image

1. Create virtual environment

python -m venv venv
source venv/bin/activate # Linux/Mac
# or
venv\Scripts\activate # Windows

2. Install dependencies

pip install -r requirements.txt

3. Run locally

python main.py

# Run all tests
pytest
# Run with coverage
pytest --cov=bot --cov-report=html
# Run specific test file
pytest tests/test_system_monitor.py

# Format code
black .
# Lint code
ruff check .
# Type checking
mypy bot/ config/

• Check logs: docker-compose logs -f
• Verify bot token is correct
• Ensure your user ID is in TELEGRAM_ALLOWED_USER_IDS

• Adjust resource limits in docker-compose.yml
• Increase alert check interval
• Reduce chart DPI in settings

• Install lm-sensors: sudo apt install lm-sensors
• Run sensor detection: sudo sensors-detect

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

• python-telegram-bot - Telegram Bot framework
• psutil - System monitoring
• docker-py - Docker SDK for Python
• matplotlib - Visualization library

For support, open an issue on GitHub.

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.

Made with ❤️ for system administrators

_{100% built with GitHub Copilot (Claude Opus 4.5)
Arturo Carretero Calvo — 2026}