Provision a cheap Ubuntu box, install Hermes Agent, wire it into a Telegram bot, and put a restart policy in front of the gateway so it survives reboots — not just your next coffee run.
Hermes Agent is Nous Research's open-source, self-improving AI agent — and on paper it sounds like something that should just run itself. In practice, it only behaves like an agent if it's running somewhere that never sleeps, never closes its lid, and never drops wifi when you walk into the next room. That somewhere is a $5/month VPS, not the laptop you're reading this on.
Hermes Agent needs an always-on host to actually act like an agent — a laptop isn't one. Provision a small Ubuntu VPS, run Hermes's one-line installer, create a bot through Telegram's @BotFather, wire the token into hermes gateway setup, then wrap the gateway in a systemd service or Docker restart policy so a reboot doesn't quietly kill it. Budget 30 minutes and about $5/month. If you already pay for ChatGPT, you can skip API billing entirely via OAuth.
Every Hermes Agent tutorial starts the same way — install it, get it talking, feel like a wizard. The part that goes unsaid is what happens the moment you close the lid to grab coffee. Here's the failure mode nobody mentions upfront, and why a VPS sidesteps all three versions of it.
The instant your laptop sleeps, the process running Hermes's Telegram gateway pauses with it. No crash log, no error in Telegram — your bot just stops answering, and you won't know until you message it from the train and get nothing back.
Switching wifi, reconnecting a VPN, even a flaky router — all of it renegotiates your laptop's outbound connection. A VPS sits on one static IP with a wired uplink, so the gateway's connection to Telegram's servers just stays open.
Update your OS, restart for a driver fix, anything — Hermes doesn't come back on its own unless something is watching for it. Section 06 covers the restart policy that makes a VPS recover automatically. A laptop never will.
Hermes itself is light. What it actually needs depends almost entirely on whether the model runs on your provider's API or on the box itself.
| Resource | API-only (cloud LLM) | Local models / heavy tool use |
|---|---|---|
| vCPU | 1 | 2+ |
| RAM | 1 GB | 2–4 GB |
| Storage | 10 GB SSD | 20 GB+ SSD |
| OS | Ubuntu 24.04 LTS | Ubuntu 24.04 LTS |
| Typical cost | ~$4–6/month | ~$8–12/month |
Any KVM-based provider works — Hostinger, Contabo, DigitalOcean, Hetzner. The only hard requirement is a public IPv4 address and outbound HTTPS, since the gateway needs to reach both api.telegram.org and whichever LLM provider you point Hermes at. Pick the smallest plan in the left column unless you already know you want local models.
ssh root@your-vps-ip apt update && apt upgrade -y apt install -y git
Git is the only manual prerequisite — the Hermes installer handles everything else.
One command bootstraps the entire runtime — no manually wrangling Python versions or Node installs first.
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash
That single command bootstraps Python 3.11, Node.js v22, ripgrep, and ffmpeg, clones the repository, and puts the hermes command on your PATH. It's the same path Linux, macOS, and WSL2 all use — there's no separate manual route worth taking unless you specifically want control over the dependency graph.
source ~/.bashrc hermes setup hermes doctor hermes status hermes chat -q "Hello! What tools do you have available?"
hermes setup walks through your model provider. hermes doctor flags missing dependencies or PATH issues. hermes status confirms the config actually initialized. The last line is the only check that proves the agent can respond — not just that files exist on disk.
Already paying for ChatGPT? hermes setup supports OpenAI Codex OAuth as an alternative to API key billing. It opens a URL, you sign in and grant access, then paste a nine-digit code back into the terminal. No new API account, no separate bill — Hermes runs against the subscription you already have.
Telegram bots authenticate with a token from BotFather, Telegram's own bot-management bot. Five messages and you're done.
@BotFather./newbot.bot, e.g. my_hermes_agent_bot.7123456789:AAFq3xampletoken — copy it somewhere temporary.Treat that token like a production secret. Anyone holding it can read every message your bot receives and send replies as it. Don't paste it into a group chat, a GitHub issue, or a commit — ever.
Message @userinfobot on Telegram and it replies instantly with a number, e.g. 123456789. That number — not your @username — is what controls access in the next step. It never changes even if you rename your account.
The gateway is the service layer that points Hermes at Telegram. Configuration takes about thirty seconds once you have the token and user ID in hand.
hermes gateway setup
The wizard lists available platforms. Choose Telegram, then paste the bot token followed by your numeric user ID. Both get written to ~/.hermes/.env on the host, in plain unquoted form — Telegram tokens contain a colon that some shell parsers mishandle when quoted.
# written by the setup wizard — no quotes around either value
TELEGRAM_BOT_TOKEN=7123456789:AAFq3xampletoken
TELEGRAM_ALLOWED_USER_IDS=123456789
hermes gateway start
Open Telegram, message your bot by username, and expect a reply in 2–10 seconds depending on your LLM provider's latency. Nothing back? Jump to the troubleshooting table near the end of this guide.
hermes gateway start works perfectly — right up until you close the SSH session running it. The moment that terminal disconnects, the process dies with it, and the bot goes quiet the exact same way it would on a laptop. A VPS only solves the always-on problem if something restarts the gateway for you.
The simpler choice if you installed Hermes straight onto the host.
[Unit] Description=Hermes Agent Telegram Gateway After=network-online.target [Service] Type=simple User=youruser ExecStart=/home/youruser/.local/bin/hermes gateway start Restart=on-failure RestartSec=5 [Install] WantedBy=multi-user.target
sudo systemctl daemon-reload sudo systemctl enable --now hermes-gateway sudo systemctl status hermes-gateway
Worth the extra step once Hermes runs unsupervised tasks — it boxes in filesystem access.
services:
hermes:
image: nousresearch/hermes-agent:latest
restart: unless-stopped
env_file: .env
volumes:
- ~/.hermes:/root/.hermes
docker compose up -d
Pick one path, not both. systemd is simplest if Hermes lives directly on the host. Docker is the better default once you let it run unattended — an autonomous agent with the run of your whole VPS is a bigger blast radius than one container.
Five things worth knowing before you forget the bot is running and stop thinking about it.
User ID allowlist. Only numeric IDs listed in TELEGRAM_ALLOWED_USER_IDS get a reply. Everyone else who finds the bot's username is silently ignored.
Group chats are off by default. Enable them via BotFather → /mybots → your bot → Bot Settings → Group Privacy → OFF. Hermes then only responds when explicitly @mentioned.
Rate limits exist. Telegram caps bots around 30 messages/second globally and 1/second per chat — irrelevant for personal use, worth knowing if you fan a cron report out to a busy group.
No end-to-end encryption. Telegram bot traffic transits Telegram's servers like any Bot API call. Don't route credentials or anything sensitive through it.
Audit the agent's self-writes. Hermes writes and updates its own skills over time at ~/.hermes/skills/, with memory and session history at ~/.hermes/memories/ and ~/.hermes/sessions/. After the first complex unsupervised task, it's worth an ls.
| Task | Command |
|---|---|
| Install Hermes | curl -fsSL .../install.sh | bash |
| Run diagnostics | hermes doctor |
| Configure Telegram | hermes gateway setup |
| Start gateway (foreground) | hermes gateway start |
| View gateway logs | hermes gateway logs |
| Check model provider | hermes model |
| Enable group chat | BotFather → Group Privacy → OFF |
| Persist across reboot (systemd) | systemctl enable --now hermes-gateway |
| Persist across reboot (Docker) | restart: unless-stopped in compose |
| Symptom | Likely cause | Fix |
|---|---|---|
| Bot never replies | Wrong numeric user ID | Re-check the ID from @userinfobot — not your @username |
| "401 Unauthorized" on start | Truncated or wrong token | Re-copy the full token from BotFather; the half after the colon is easy to cut off |
| Gateway dies after you disconnect SSH | No restart policy in place | Wrap it in the systemd unit or Docker restart: unless-stopped from Section 06 |
| Bot ignores everything in a group | Privacy mode still on | BotFather → Group Privacy → OFF, then @mention the bot |
| Replies take 10+ seconds | Cloud LLM latency, or a local model on too small a VPS | 2–10s is normal for cloud APIs; bump vCPU/RAM if running locally |
No. If Hermes is calling a cloud LLM provider via API key or OAuth, the model runs remotely — the VPS just needs to stay online. A GPU only matters if you point Hermes at a local model.
Yes, if you already pay for ChatGPT. hermes setup can authenticate against that subscription through OAuth instead of a separate API key, so there's no new billing relationship to manage.
With the systemd unit or Docker restart policy from Section 06, the gateway comes back on its own. Without it, you'll need to SSH in and run hermes gateway start manually every time.
Yes. Re-run hermes gateway setup and choose another platform. Multiple gateways can run from one Hermes instance, sharing the same memory and skills.