Hermes Agent on a VPS with Telegram: verified setup guide

Installing Hermes Agent is the easy part. The useful milestone is different: you send a message from your phone, the right model answers, and the bot still works after you close SSH and reboot the server.

This is a failure-aware runbook for that complete path:

VPS → Hermes → model provider → Telegram → background service → phone.

I use Hermes as an always-on assistant in Telegram. For this guide, I also repeated the installer flow in an isolated directory on Debian 13. On August 11, 2026, the official installer produced Hermes Agent v0.20.0. I separately checked the gateway commands against a live server.

Save this page for later: the final readiness checklist and troubleshooting table are designed for both the first install and future upgrades.

The result

By the end, you will have:

• Hermes Agent installed on a regular Linux VPS;
• a working model through OAuth or an API provider;
• a private Telegram bot restricted to approved numeric user IDs;
• a systemd gateway that survives logout and reboot;
• a layer-by-layer test sequence for silent-bot failures.

You do not need Docker, Kubernetes, a public port, or a domain for the basic setup. The default Telegram gateway uses outbound long polling.

What you need

1. A Linux VPS. Ubuntu 22.04/24.04 or Debian 12/13 are sensible choices. The official Nous Research team guide says a roughly $5/month VPS is enough for the gateway because model inference happens remotely.
2. A non-root user with sudo. Do not run a personal agent permanently as root.
3. A Telegram account. You need it to create the bot and get your numeric user ID.
4. A model route. The fastest option is Nous Portal. Hermes also supports OpenAI Codex through ChatGPT authentication and API providers such as OpenRouter.

If your VPS provider drops you into a root shell, create a dedicated user first:

adduser hermes
usermod -aG sudo hermes
su - hermes

Run the remaining commands as that user.

1. Install Hermes Agent

Install the small set of base packages:

sudo apt update
sudo apt install -y curl git ca-certificates

The official one-line installer is:

curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash

If piping a remote script directly into a shell makes you uncomfortable, download and inspect it first:

curl -fsSL https://hermes-agent.nousresearch.com/install.sh \
  -o /tmp/hermes-install.sh
less /tmp/hermes-install.sh
bash /tmp/hermes-install.sh

The installer selects Python 3.11, creates an isolated virtual environment, installs Hermes and its dependencies, and places the CLI launcher in ~/.local/bin.

Reload your shell and confirm the executable:

exec "$SHELL" -l
hermes --version

If the shell says hermes: command not found, do not reinstall immediately. Test the expected binary path first:

export PATH="$HOME/.local/bin:$PATH"
hermes --version

Persist that export in ~/.bashrc if the installer did not add it.

2. Prove the model works before adding Telegram

This is the most important sequencing decision in the guide. If the CLI cannot complete one normal request, a Telegram gateway only adds another place to look for the same failure.

For the shortest path through Nous Portal:

hermes setup --portal

This opens an OAuth flow, lets you select a model, and enables the Nous Tool Gateway without copying an API key.

For ChatGPT/Codex or another provider, run the full setup wizard:

hermes setup

Or open the provider and model picker directly:

hermes model

The current Quickstart specifies a minimum 64K-token context window. That requirement can change between releases, so verify it when selecting a provider and model.

Now run a real non-interactive request:

hermes chat -q "Reply with one line: the model works"

The pass condition is a meaningful text response with no authentication error. Then inspect the local configuration:

hermes config check
hermes doctor

Warnings about optional tools you have not configured are normal. A missing working model is not.

3. Create the Telegram bot

Open Telegram's official @BotFather bot:

1. send /newbot;
2. choose a display name;
3. choose a username ending in bot;
4. save the token BotFather returns.

A bot token looks like 123456789:AA.... Treat it as a password. Do not paste it into a chat, commit it to Git, or leave it visible in screenshots.

If the token leaks, revoke it immediately with /revoke in @BotFather, then repeat the gateway setup with the replacement token.

Next, get the numeric ID of your human Telegram account. Messaging @userinfobot is the simplest route. Do not use your @username, and do not use the numeric prefix from the bot token.

4. Connect Telegram to Hermes

Run the messaging setup wizard:

hermes gateway setup

The current wizard offers two Telegram paths:

• Automatic — create the bot through a QR-code flow;
• Manual — create it with BotFather and paste the token yourself.

For an auditable setup, choose Telegram → Manual, then enter:

• the BotFather token;
• your human numeric Telegram ID in the allowed-users list.

The equivalent manual environment file looks like this:

# ~/.hermes/.env
TELEGRAM_BOT_TOKEN=[REDACTED]
TELEGRAM_ALLOWED_USERS=123456789

Do not enable global access just to get through the first test. Starting with one explicit ID proves that the token, allowlist, and active Hermes home all match.

TELEGRAM_ALLOWED_USERS restricts who can talk to the bot; it does not reduce the tools available to an approved user. A Telegram Hermes profile may include terminal and file access. If anyone else will use the bot, isolate it in a separate profile and restrict its tools through hermes tools first.

5. Test the gateway in the foreground

Run:

hermes gateway run

Open your bot in Telegram and send:

Reply with one line: Telegram works

A meaningful response proves the whole round trip:

Telegram → gateway → Hermes → model → gateway → Telegram.

Stop the foreground process with Ctrl+C before installing a service. Telegram rejects concurrent polling when two gateway processes reuse the same bot token.

6. Keep the gateway running after SSH logout

A user-level systemd service plus lingering is the least surprising setup for a dedicated non-root account:

hermes gateway install --start-now
sudo loginctl enable-linger "$USER"
hermes gateway status --deep

Lingering lets the user's service continue after logout and start during boot.

Verify both parts explicitly:

systemctl --user is-enabled hermes-gateway
loginctl show-user "$USER" -p Linger

You want enabled and Linger=yes.

For a headless VPS, the CLI also supports a system-level service:

sudo hermes gateway install --system --run-as-user "$USER" --start-now
sudo hermes gateway status --deep --system

Choose one service mode. Do not run both modes with the same Telegram token.

7. Reboot and test from the phone again

A process that worked in an SSH terminal has not yet passed the deployment test.

sudo reboot

After the server returns:

hermes gateway status --deep

Then send another real Telegram message. A green process status without an end-to-end reply is only half a verification.

Copyable readiness checklist

Run this after the first setup and after every upgrade:

# 1. CLI exists
hermes --version

# 2. Configuration is readable
hermes config check

# 3. The model works without Telegram
hermes chat -q "Reply with one word: ready"

# 4. The gateway is healthy
hermes gateway status --deep

# 5. The user service survives logout and reboot
systemctl --user is-enabled hermes-gateway
loginctl show-user "$USER" -p Linger

# 6. Final check
# Send the bot a private message and receive a meaningful answer

Troubleshooting a silent bot

Change one layer at a time. Find the first failed check instead of resetting the whole installation.

User-service logs:

journalctl --user -u hermes-gateway -n 100 --no-pager
journalctl --user -u hermes-gateway -f

For a system service:

sudo journalctl -u hermes-gateway -n 100 --no-pager

The minimum safe shape

For a personal Telegram agent, I would keep these boundaries:

• one dedicated Linux user;
• one bot token per gateway;
• an explicit TELEGRAM_ALLOWED_USERS list;
• private messages first, groups later;
• secrets only in the local environment file or a secret manager;
• SSH key access to the VPS;
• a real Telegram test after every update.

Do not add the bot to a work group until the private DM path is stable. Groups add privacy mode, allowed chats, mention rules, topics, and a much larger permission surface.

Updating without guessing

hermes update
hermes config check
hermes doctor
hermes gateway restart
hermes gateway status --deep

Finish by sending a private message to the bot. An exit code of zero from the update command is not an end-to-end deployment check.

Cost

Hermes itself is open source. The recurring cost has two parts:

• the VPS: the official guide uses roughly $5/month as a reasonable gateway baseline;
• the model: a subscription or API usage from your chosen provider.

You do not need to buy a Mac mini for this first deployment. You also are not creating “free ChatGPT in Telegram”: model quality, limits, and cost still come from the provider route you choose.

Where to go next

Once the DM bot survives a reboot, the useful next question is architecture rather than installation. My always-on AI agent server setup explains that wider choice.

Sources

• Hermes Agent Quickstart
• Hermes Agent Installation
• Official Telegram gateway documentation
• Messaging Gateway and systemd
• Team Telegram Assistant tutorial
• My original Hermes Agent article on Habr