A lightweight Linux monitoring and operations agent built for personal servers, remote systems, and home lab environments.
Monitor delivers alerts through Telegram and provides an interactive bot interface for querying server health from anywhere.
After setting up a remotely accessible Linux machine using SSH and Tailscale, I realized I had a new problem:
How would I know if something went wrong?
Questions I wanted answered included:
- Is the machine still online?
- Are important services running?
- Is disk usage becoming a problem?
- Is memory usage becoming excessive?
- Has the machine restarted?
Rather than relying on manually checking the system, I decided to build a lightweight monitoring agent.
Monitor is the result.
Monitor checks the health of configured services.
Examples:
- ssh
- tailscaled
- custom services
Monitor checks disk utilization and generates alerts when configured thresholds are exceeded.
Monitor checks memory usage and reports when usage exceeds configured limits.
Alerts can be delivered directly to Telegram.
Examples:
- Service failures
- Daily health reports
- Boot notifications
A scheduled summary can be sent containing:
- Disk usage
- Memory usage
- Service status
- System health information
Receive a Telegram message whenever the monitored machine starts.
Useful for:
- Power outages
- Unexpected reboots
- Remote servers
- Home lab environments
Monitor includes a Telegram bot that allows remote interaction with the monitored server.
Current commands:
- /help
- /memory
- /disk
- /services
The bot runs as a persistent systemd service and allows administrators to query server status without opening an SSH session.
Monitor is designed to run using:
- systemd services
- systemd timers
allowing it to operate automatically without requiring additional infrastructure.
📊 Daily Server Report
Disk Usage: 34%
Memory Usage: 41%
ssh: Running
tailscaled: Running
/help
Response:
Available Commands
/help
/memory
/disk
/services
Telegram
▲
│
┌──────────────┴──────────────┐
│ │
│ │
▼ ▼
monitor-bot.service monitor.service
│ │
│ │
▼ ▼
Telegram Commands Scheduled Checks
(/memory, /disk, (disk, memory,
/services, etc.) services)
│ │
└──────────────┬────────────┘
│
▼
Monitor Core
│
┌────────────┼────────────┐
│ │ │
▼ ▼ ▼
Disk Memory Services
Checks Checks Checks
- Python
- uv
- systemd
- Telegram Bot API
- Linux
- Tailscale
git clone https://github.com/richardayikwei/monitor.git
cd monitorInstall runtime and development dependencies:
uv sync --all-groupsuv pip install -e .Monitor uses an editable installation during development.
This allows source code changes to take effect immediately without requiring reinstallation.
Application settings are stored separately from secrets.
cp config.example.toml config.toml
cp .env.example .envExample:
disk_threshold = 90
memory_threshold = 90
services = [
"ssh",
"tailscaled"
]TELEGRAM_BOT_TOKEN=YOUR_TELEGRAM_BOT_TOKEN
TELEGRAM_CHAT_ID=YOUR_TELEGRAM_CHAT_ID
- Open Telegram.
- Search for BotFather.
- Run:
/newbot
- Follow the prompts.
- Copy the bot token.
Send a message to your bot.
Visit:
https://api.telegram.org/bot<YOUR_BOT_TOKEN>/getUpdates
Locate:
chat.id
and place it in:
TELEGRAM_CHAT_ID
uv run monitoruv run monitor-daily-reportuv run monitor-boot-notificationuv run monitor-botRuns scheduled health checks.
Example:
[Unit]
Description=Monitor Health Check
[Service]
Type=oneshot
WorkingDirectory=/path/to/monitor
ExecStart=/path/to/.venv/bin/monitorExample:
[Unit]
Description=Run Monitor Every 15 Minutes
[Timer]
OnBootSec=5min
OnUnitActiveSec=15min
[Install]
WantedBy=timers.targetEnable:
sudo systemctl daemon-reload
sudo systemctl enable --now monitor.timerRuns a scheduled report.
Example schedule:
08:00 every day
Typically implemented using:
daily-report.service
daily-report.timer
Runs once whenever the machine starts.
Typically implemented using:
boot-notification.service
No timer is required.
Runs continuously and listens for Telegram commands.
Example:
[Unit]
Description=Monitor Telegram Bot
After=network-online.target
[Service]
Type=simple
WorkingDirectory=/path/to/monitor
ExecStart=/path/to/.venv/bin/monitor-bot
Restart=always
RestartSec=5
[Install]
WantedBy=multi-user.targetEnable:
sudo systemctl daemon-reload
sudo systemctl enable --now monitor-bot.service| Command | Description |
|---|---|
| /help | Show available commands |
| /memory | Display current memory usage |
| /disk | Display current disk usage |
| /services | Display monitored service status |
Planned commands:
- /status
- /uptime
- /report
This project uses Commitizen for conventional commits and automated version management.
Create commits using:
uv run cz commitGenerate a version bump:
uv run cz bumpView available commands:
uv run cz --helpThis project uses docstrings to document modules, functions, and classes.
Preview changes:
uv run pyment src/monitor/checks/memory.pyGenerate and write docstrings:
uv run pyment -w -o google src/monitor/checks/memory.pyGenerate docstrings for an entire directory:
uv run pyment -w -o google src/Pyment generates the structure, but meaningful descriptions should be written by the developer.
uv run pydocstyle src/This reports:
- Missing module docstrings
- Missing function docstrings
- Missing class docstrings
The goal of documentation is not only to describe what the code does, but also to explain why it exists.
Contributors are encouraged to document:
- Module purpose
- Public functions
- Function arguments
- Return values
- Important side effects
- Non-obvious design decisions
Install all development dependencies:
uv sync --all-groupsPlanned improvements include:
- Service recovery notifications
- State-based alerts
- Historical reporting
- Enhanced Telegram bot commands
- Multi-node monitoring
- Integration with Community Compute experiments
This project began as part of a larger learning journey involving:
- Linux administration
- Remote server management
- SSH
- Tailscale
- systemd
- Infrastructure monitoring
The goal was not only to solve a practical problem but also to gain a deeper understanding of operating and maintaining real systems.
See:
CHANGELOG.md
for release history.
Contributions, bug reports, feature requests, and suggestions are welcome.
If you find an issue or have an idea for improvement, please open an issue or submit a pull request.
Released under the MIT License.