How to Install Hermes Agent on Ubuntu and Monitor Your Server via a Telegram Group Bot

So here’s the thing. Last Friday afternoon I was just chilling — coffee in hand, laptop on, killing time by opening htop on one of the servers I look after. Nothing serious, just a habit. And then it hit me. Why am I still doing this the manual way? SSH into a box, glance at the load, close the session, move on to the next one. That gets old fast when the server list keeps growing.

What I actually needed was simple: I wanted to know how my servers were doing without SSH-ing into each one. When a client asks “is the server okay?”, I wanted to answer without that awkward pause. That’s when I started looking for a way to push server notifications straight into a Telegram group. After trying a few options, I landed on the Hermes agent. Lightweight, no-nonsense, and the install on Ubuntu is refreshingly straightforward.

Here’s the thing about manual monitoring — it’s like watching your house without a CCTV. Everything’s fine while you’re sitting on the porch. But the moment you leave for groceries, who’s watching? Servers are exactly the same. If you only check when you get a hunch, there are long stretches where a box can quietly fall over and nobody notices. The impact hits your clients first: issues get noticed late, downtime drags on longer than it should, and trust starts to slip. Clients start asking “why did nobody catch this?” and that’s a rough conversation to have.

There’s also this assumption that you need an expensive monitoring platform or a paid SaaS with a monthly invoice to do this properly. But for the basics — “RAM is running low”, “disk is at 90%”, “nginx just died” — a Telegram bot plus a small agent running on the box is honestly enough. Telegram is free, notifications are real-time, and you don’t need to open a web dashboard that sometimes causes more headaches than the problem you’re fixing. That matters a lot when you’re juggling several servers at once.

Now here’s the part where most people get stuck and give up. They search around, collect snippets from all over, then fail halfway because they mix up the bot token, the chat_id, and the whole “make the bot a group member” step. The concept is actually simple: the bot is the bridge, the token is the key, and the chat_id is the destination address. Get those three right and your monitoring messages will land in the group, no drama. So in this article I’m writing it all out from zero so you don’t have to bang your head against the wall like I did. Take it easy, follow the steps in order, and it’ll just work.

What Is the Hermes Agent (and Why Telegram)?

Before we dive into the install, let me explain briefly what we’re actually setting up. The Hermes agent is a lightweight monitoring agent that runs on your server. Its only job is to collect system metrics — CPU, RAM, disk, uptime, service status — and push them to a Telegram group through a bot. It runs continuously in the background as a systemd service, so once it’s installed you don’t touch it again.

Why Telegram? Because there’s no simpler layer than this. No extra app to install on the server, no open ports facing the internet, no dashboard to maintain. All you need is a server with outbound internet access to api.telegram.org and a phone with Telegram on it. That’s it.

Step 1 — Create Your Telegram Bot with BotFather

The first thing to sort out is the bot itself. Open Telegram and look for the account @BotFather. That’s Telegram’s official bot-manager account. Send it the /newbot command and answer two questions: the bot’s display name (anything you want) and its username (must end in ‘bot’, like server_guard_bot).

Once that’s done, BotFather hands you an HTTP API token that looks roughly like this:

7234567891:AAHd8...keep-this-token-private...

That token is basically a password. Keep it safe, never share it, and definitely don’t paste it in a public post. If it leaks, someone can send messages using your bot — or worse, read the conversations coming into it. If it ever gets compromised, just send /revoke to BotFather and grab a fresh token.

Step 2 — Create a Group and Grab the chat_id

Now create a new Telegram group. Name it whatever you want, like “Server Monitoring”. Then add your bot to that group. Important: the bot has to be a group member, not just someone with restricted chat access. To make things easy, send one test message in the group — type the word “test” or anything. Why? Because that gives Telegram something to register, and it lets us pull the chat_id.

To get the chat_id, we use the getUpdates API. Open a terminal on any machine that has curl, and run:

curl -s "https://api.telegram.org/bot<TOKEN>/getUpdates"

Replace <TOKEN> with your BotFather token. The response is JSON. Look for the part that reads “chat”: { “id”: -100xxxxxxxxx }. That negative number is your group’s chat_id. Messages coming from a group always have a negative id, so don’t be surprised by the minus sign. Note that number down — you’ll need it in the next step.

Step 3 — Prepare the Ubuntu Server

Alright, back to the server. Log in via SSH. Let’s start from a clean state so nothing clashes with older packages:

sudo apt update
sudo apt upgrade -y
sudo apt install -y git python3 python3-venv python3-pip

The agent runs on Python, so we need python3 plus venv. Using a venv is a good habit — it keeps dependencies tidy and away from the system Python. And while we’re at it, if you’re not yet comfortable with SSH, now’s a great time to go through our SSH key setup guide for VPS and make your logins safer than a plain password.

Step 4 — Download and Install the Hermes Agent

Time to grab the agent’s code. I’d put it in /opt, following the convention for manually installed apps:

cd /opt
sudo git clone <hermes-repo-url> /opt/hermes-agent
cd /opt/hermes-agent
sudo python3 -m venv venv
sudo ./venv/bin/pip install -r requirements.txt

Replace <hermes-repo-url> with the address of the Hermes agent repository you’re using. Why /opt plus a dedicated venv? Cleanliness. If you ever want to uninstall, you just delete those two directories and you’re done — no leftover dependencies stuck in the system. And if virtual environments are new to you, don’t worry, you don’t need to understand them deeply. What matters is that all dependencies live inside /opt/hermes-agent/venv and never touch the system environment.

Step 5 — Configure the Agent

This is the part that matters most. The config file usually lives in /etc/hermes/. Let’s create the folder and the file:

sudo mkdir -p /etc/hermes
sudo nano /etc/hermes/hermes.conf

Fill it in something like this:

[telegram]
token = "7234567891:AAHd8...your-token..."
chat_id = "-1001234567890"

[monitor]
hostname_alias = "server-prod-01"
interval = 60
cpu_threshold = 85
ram_threshold = 85
disk_threshold = 90

[services]
watch = nginx, mysql, docker

[alert]
timezone = "Asia/Jakarta"
cooldown = 300

Take a moment to understand the important bits:

• token: your bot token from BotFather.
• chat_id: the negative number we got from getUpdates.
• hostname_alias: the display name of the server in notifications. If you monitor several servers, this is what keeps the messages from getting mixed up.
• interval: how often to check, in seconds. 60 means once a minute.
• cpu_threshold, ram_threshold, disk_threshold: alert thresholds in percent. Notifications only fire when these are crossed — otherwise your bot would spam you every second.
• watch: the services whose status gets monitored, comma-separated.
• cooldown: the minimum gap between alerts, so if your disk sits at 95% for an hour, the bot won’t nag you every single minute.

Once it’s filled in, lock the file down so other users can’t read it:

sudo chmod 600 /etc/hermes/hermes.conf

And while we’re on the topic of keeping servers healthy — monitoring tells you when something’s wrong, but fixing it still takes practice. If you ever get hit with a slow, overloaded box and don’t know where to start, our guide to troubleshooting high load on VPS is a good place to begin.

Step 6 — Run It as a systemd Service

To make the agent run in the background and start automatically on reboot, we register it as a systemd service. Create the unit file:

sudo nano /etc/systemd/system/hermes-agent.service

Fill it with something like this:

[Unit]
Description=Hermes Monitoring Agent
After=network-online.target
Wants=network-online.target

[Service]
User=hermes
WorkingDirectory=/opt/hermes-agent
ExecStart=/opt/hermes-agent/venv/bin/python hermes.py --config /etc/hermes/hermes.conf
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target

Now set up a dedicated user so the agent doesn’t run as root. This is a best practice people skip all the time:

sudo useradd -r -s /usr/sbin/nologin hermes
sudo chown -R hermes:hermes /opt/hermes-agent /etc/hermes
sudo systemctl daemon-reload
sudo systemctl enable --now hermes-agent
sudo systemctl status hermes-agent

If the status shows active (running), the agent is up. If systemd still feels like a black box, we have a beginner-friendly systemd service guide you can read at your own pace.

Step 7 — Test the Notifications

This is the fun part. Once the service is running, wait a few seconds and open your Telegram group. You should see a message from the bot — usually a summary of the server’s status: CPU, RAM, disk, uptime, and the state of the watched services.

If nothing shows up, check the logs first:

journalctl -u hermes-agent -f

If you see errors like “Failed to send message” or “401 Unauthorized”, something’s off in the config. No panic — the troubleshooting table below has you covered. A typical message in the group looks something like this:

[server-prod-01] Server Status
CPU : 12% | RAM : 48% (1.9GB/4GB)
Disk / : 63% (45GB/72GB)
Uptime : 14 days 6 hours
Service: nginx OK, mysql OK, docker OK

Quick Troubleshooting Table — Save This One

Symptom	Likely Cause	Fix
Message never lands in the group	Wrong chat_id, or the bot isn’t a group member	Re-run getUpdates, confirm the id is negative, add the bot to the group
401 Unauthorized	Token is wrong or has been revoked	Double-check the token in BotFather, /revoke if needed
403 Forbidden	Bot is blocked, or it can’t access the private group	Make sure the bot is a member and check its privacy mode
Metrics missing from the message	Service runs but the user lacks read permissions	Check journalctl, make sure chown hermes:hermes was executed
Bot keeps spamming	Thresholds too low or no cooldown set	Raise thresholds, set a cooldown of at least 300 seconds
Service keeps restarting	Config error, like extra whitespace in the token	journalctl -u hermes-agent -e, inspect the config, remove stray spaces

Security Checklist Before Production

• Never commit the config file to git. The token inside is a real credential.
• chmod 600 the config file and don’t grant access to other users.
• Run the agent as a dedicated user (hermes), not root.
• Don’t add the bot to groups full of strangers or public groups. These are internal server alerts, not public content.
• If your agent supports commands from the bot (like remote execution), disable them unless you truly need them. Safer that way.
• Make sure the server can reach api.telegram.org over HTTPS (port 443). If there’s a firewall, whitelist it.
• Keep your server patched. An agent is just eyes and ears — it’s not a replacement for maintenance. Pair it with our Ubuntu server update and patch guide.

A Note for Multi-Server Setups

One thing I love about this approach: a single group can act as a dashboard for every server you own. Just install the same agent on each box, point them all at the same chat_id, and differentiate the hostname_alias in each config. When server A starts acting up, the notification clearly says who’s the troublemaker.

Oh, and if you want to go beyond quick alerts and add proper visual dashboards, combine this with monitoring your VPS with Netdata. Hermes handles the instant notifications, Netdata handles the deep graphs. They work great together.

FAQ — Questions That Come Up a Lot

Alright, that’s about it for this one. If you’ve tried the setup and hit an error that’s not in the troubleshooting table above, drop it in the comments — someone might save the next person the same headache. Thanks for reading, and may your servers stay boring and healthy. Take it easy.