Run Hermes on a VPS and talk to it from Telegram

Most agent demos run in a terminal on the same machine as the person watching. That is a toy. The version that changes your week is the one that keeps working after you close the laptop: it watches things, runs scheduled jobs, and answers on your phone. That needs three pieces — a machine that stays on, a messaging channel, and a process supervisor. Nothing else.

What you need before you start

• A VPS running Ubuntu 22.04 or 24.04, with SSH access and a non-root user you can log in as.
• A model provider: either a Nous Portal subscription (one OAuth covers models and the tool gateway) or your own API key.
• A Telegram account. The bot is created from inside Telegram, in two minutes, by @BotFather.
• No domain, no reverse proxy, no open ports. The gateway reaches out to Telegram; you never expose anything.

1. Install Hermes

On the VPS, as your normal user — not as root:

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

The installer clones the source, bootstraps Python and Node through its own package manager, and pulls a pinned Chromium for browsing. It does not need root and it does not touch system Python. When it finishes, open a new shell (or source your profile) so hermes is on PATH, then check:

hermes --version
hermes doctor

hermes doctor is the one command worth learning first. It reports what is missing — provider key, browser driver, ffmpeg — instead of letting you discover it in the middle of a task.

2. Pick a model provider

The shortest path, which also turns on web search, image generation and TTS in one step:

hermes setup --portal

That opens an OAuth flow in your browser and writes the credentials into the profile. If you would rather bring your own key, run hermes model and pick a provider — the wizard writes ~/.hermes/config.yaml for you.

Do not skip this to save a minute. An unconfigured model is the number one reason a gateway starts fine and then answers nothing.

3. Create the Telegram bot

1. In Telegram, open @BotFather (the one with the blue check) and send /newbot.
2. Give it a name (display) and a username ending in bot.
3. BotFather replies with a token that looks like 8123456789:AAF…. Treat it as a password: anyone holding it controls your bot.
4. Send /setprivacy → your bot → Disable if you want it to read all messages in groups. Leave it enabled for private use.

4. Wire the gateway

hermes gateway setup

The wizard asks which platform to enable, takes the bot token, and writes it into ~/.hermes/config.yaml under the Telegram platform block. Then install it as a managed service so it survives SSH disconnects and reboots:

hermes gateway install
hermes gateway status

hermes gateway install registers a systemd user unit and enables lingering for your account, which is what makes the service come back after a reboot without you logging in. If you prefer to watch it live while debugging, hermes gateway run stays in the foreground with the logs on screen.

5. Prove the loop works

Open your bot in Telegram and send anything. A correct setup answers in a few seconds. Then confirm from the server side:

hermes gateway status
hermes status --full

You should see the platform connected and the service active. If the bot stays silent, the order of checks is: token valid (getMe via curl), gateway running, model configured. Nine times out of ten it is the third one.

6. Make it earn its keep

A bot that only chats is a chat window with extra steps. The two features that turn it into infrastructure:

• Scheduled jobs. hermes cron create "50 7 * * *" --deliver telegram — the agent runs on a schedule and pushes the result to your chat. Times are UTC in the cron expression; convert them yourself and write the local time in a comment, or you will be an hour off twice a year.
• Scripted sends. hermes send -t telegram "build finished" works from any shell script, without an LLM and without the gateway running for bot-token platforms. It is the cheapest way to get alerts out of a long job.

Beyond that: skills live in ~/.hermes/skills/<category>/<name>/SKILL.md, and a skill is just a markdown file with frontmatter that the agent loads when a task matches. Write one per recurring job you find yourself re-explaining.

7. The part everyone skips

• Do not run the agent as root. Give it its own user with access to what it genuinely needs. If a prompt injection ever lands, the blast radius is that user's home directory, not the machine.
• Keep approvals on for anything destructive. A remote agent that can delete files without asking is a coin flip you take once.
• Secrets stay in files, mode 600. ~/.hermes/.env and anything under ~/.hermes/secrets/. Not in the config file, not in a git repo, not in a chat message.
• Firewall in, nothing out. You need no inbound port for Telegram polling. If you also enable a webhook or an API server, bind it to loopback and put it behind a reverse proxy with TLS.
• Update deliberately. hermes update is safe to run, but read what changed: a vendored dependency can move under you.

Failure modes, in the order they happen

Cheat sheet

curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash
hermes setup --portal           # provider + tools
hermes gateway setup            # enable Telegram, paste token
hermes gateway install          # systemd user service
hermes gateway status           # is it alive
hermes send -t telegram "hi"    # scripted message, no LLM
hermes cron create "0 8 * * *" --deliver telegram