Hermes Agent on a VPS with Telegram: Your Own AI Agent on a Small Server

Hermes Agent is a free, open-source AI agent from Nous Research that you can run on a small VPS and talk to from Telegram. On the server it runs as a "gateway": a background service that fetches your Telegram messages, passes them to the AI model you pick and runs tools for you, such as shell commands. The gateway only makes outbound connections, so you open no port and need no domain. Setup takes five steps: prepare Debian, install Hermes as a normal user with one script, add a model provider key, add a Telegram bot token locked to your own user ID, and turn the gateway into a systemd service. In our lab the running gateway held about 220 MB of RAM, so even a 1 GB server can host it. The catch is the installer: on 1 GB without swap it stalled for 20 minutes.

Key facts, checked on 12 October 2026:

• The current release is Hermes Agent v0.21.7, published on 12 October 2026 under the MIT licence. The first tagged release, v0.2.0, came out on 12 March 2026, and the repository has about 253,000 stars (GitHub releases).
• The official installer brings its own Python 3.14, Node.js, ffmpeg and ripgrep. The server itself needs git and curl, plus tar and the SHA-256 tools that Debian already ships (installation docs).
• Hermes works with Nous Portal, OpenRouter, Anthropic, OpenAI, Google Gemini, DeepSeek and others, plus local servers such as Ollama. The model must offer at least 64,000 tokens of context (provider docs).
• Telegram runs in polling mode by default: the gateway asks Telegram for new messages, so no inbound port is needed (Telegram docs).
• In our lab the gateway used 218 to 225 MB of RAM idle and about 273 MB while handling a message. An install without the browser takes 2.5 GB of disk.

What runs on your server, and what doesn't

Four terms first, because guides tend to mix them up:

• The model is the AI that reads and writes. Unless you run a local one, it lives at your provider (OpenRouter, Anthropic and so on), and you pay it per token. A token is a piece of a word; 1,000 tokens is roughly 750 English words.
• The gateway is the Hermes process on your VPS. It talks to Telegram, keeps your chat sessions, runs scheduled jobs and calls the model.
• Tools are what the agent can do besides talking: run a shell command, read and write files, search the web, open a page in a headless browser (a browser without a screen).
• Memory and skills are files Hermes writes for itself in ~/.hermes: notes about you and your projects, and step-by-step "skills" it creates after a complex task so it does the job faster next time.

The server waits, remembers and runs tools; the thinking happens at the provider, which is why a small VPS is enough. The Hermes FAQ says it collects no telemetry, but your messages do travel to the model provider you choose.

Hermes Agent VPS requirements: our lab numbers

Instead of guessing the Hermes Agent VPS requirements, we measured them. The tests ran on Debian 13 in our Amsterdam lab: a 2 GB, 2 vCPU container for the full setup with Docker, and a 1 GB, 1 vCPU virtual machine that copies our smallest plan. We had no real bot or model account in the lab, so we sent test messages through the gateway's built-in local API and pointed it at a stub model, a small fake endpoint that always asks for one command.

Running Hermes is light; installing it is not. The installer builds a web interface with Node.js, and that step alone held about 540 MB on the 1 GB machine. A swap file fixes it. Swap is disk space the system borrows as slow extra memory, and here it is only busy for a few minutes.

Step 1: prepare Debian 13

Log in as root. Install four packages and create a normal user for the agent. Hermes should never run as root, and this user gets no sudo rights, so the agent can't change the system even if it misreads a request.

# as root
apt update
apt install -y curl git ca-certificates libatomic1
useradd -m -s /bin/bash hermes
loginctl enable-linger hermes

libatomic1 is a small library the bundled Node.js needs; without it the installer tries to get it through sudo, which our user doesn't have. The last line keeps a background systemd session for the hermes user even when nobody is logged in; the gateway install in step 5 checks for it. On a 1 GB server such as our VPS Nano, add the swap file now:

# as root, only on a 1 GB server
fallocate -l 2G /swapfile
chmod 600 /swapfile
mkswap /swapfile
swapon /swapfile
echo '/swapfile none swap sw 0 0' >> /etc/fstab
free -m

The last command should show a Swap: line with a total of 2047. Our Debian 13 security guide covers SSH keys and the firewall. Nothing in this tutorial needs an open port.

Step 2: install Hermes as the hermes user

# as root, switch to the new user
su - hermes

# as the hermes user
curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash -s -- --non-interactive --skip-browser --skip-computer-use

The flags matter on a server. --skip-computer-use leaves out the desktop-control driver, which is useless without a screen; on Debian 13 it also failed to install for us because the X11 library libXi.so.6 was missing. --skip-browser leaves out Chromium and saves about 375 MB of disk; drop it on a Micro or bigger if you want the agent to open web pages, and add the Chromium libraries from the Docker section below. --non-interactive skips the setup wizard, because we configure everything step by step below. A good run ends with:

✓ Hermes Agent install complete. Run: hermes
→ Reload your shell to use hermes: open a new terminal, or run: source ~/.bashrc

Type exit, run su - hermes again so the new PATH applies, and check the install:

# as the hermes user, after switching in again
hermes --version
hermes doctor

We got Hermes Agent v0.21.7 with a few newer commits (the installer follows the main branch), Python 3.14.7 and "Up to date". hermes doctor prints a long checklist. On a fresh install it ends with "Run 'hermes setup' to configure missing API keys", which is expected, plus npm audit warnings that it says need an upstream fix.

Step 3: choose the model, and know what it costs

The interactive way to pick a provider is hermes model, which walks you through a login or an API key. The direct way, here with OpenRouter, a service that gives one key access to models from many companies:

# as the hermes user
hermes config set OPENROUTER_API_KEY sk-or-your-key
hermes config set model.provider openrouter
hermes config set model.default deepseek/deepseek-v4.1-flash
hermes config check
hermes chat -Q -q "hello"

Names in capital letters are saved to ~/.hermes/.env, the secrets file; the rest goes to ~/.hermes/config.yaml. The last line sends one test message and prints the answer, so you know the model works before Telegram is involved. With the placeholder key above we got "OpenRouter rejected your API key, so the model can't be reached." A real key from your OpenRouter account replaces it.

What a month of messages costs

Hermes is free; the tokens are not. Our stub model logged what Hermes sends on every call: about 12,800 characters of system prompt and 33,500 characters of tool descriptions, roughly 11,000 to 12,000 tokens before your own words. A message that makes the agent run one command takes two calls, one to ask for the command and one to answer. So the bill follows the number of messages more than their length. Our estimate for 30 such messages a day over a 30-day month, at about 12,000 input and 300 output tokens per call, before caching discounts:

Prices come from OpenRouter's model list and Anthropic's pricing page, checked on 12 October 2026. Token counts differ between models: Anthropic's pricing page says its newer models produce about 30% more tokens for the same text, so the two Claude rows can come out higher. Hermes also adds small side calls, for example to title a conversation. For Claude models Hermes turns on Anthropic's prompt caching, which bills a cache hit at 5 to 10% of the input price. The cache lasts five minutes by default, so it mainly helps the second call of each message and quick back-and-forth chats, not messages sent hours apart. A local model through Ollama costs no tokens, but a 64,000-token context window needs far more RAM than a Nano has; our Open WebUI and local LLM guide shows the sizes.

Step 4: create the Telegram bot and lock it to you

This part happens in the Telegram app, as the Hermes Telegram guide describes:

1. Open @BotFather, send /newbot, then choose a display name and a username ending in bot. BotFather replies with a token like 123456789:ABCdef.... Anyone who has it controls the bot; /revoke in BotFather replaces it.
2. Message @userinfobot to get your numeric user ID. It is a number, not your @username.

Store both on the server and make the secrets file private:

# as the hermes user
hermes config set TELEGRAM_BOT_TOKEN 123456789:your-token
hermes config set TELEGRAM_ALLOWED_USERS 123456789
chmod 600 ~/.hermes/.env

The allowlist is what lets you in. Without it the gateway "denies all users by default", in the words of the docs, which is the safe default for a bot that can run commands on your server. Separate several IDs with commas. Our Telegram bot hosting guide explains polling and webhooks if you want the background.

Step 5: run the gateway as a systemd service

A systemd service starts the gateway at boot and restarts it after a crash. Hermes writes the service file itself. Run the install as root, so the hermes user never needs sudo:

# as root
HERMES_HOME=/home/hermes/.hermes /home/hermes/.local/bin/hermes gateway install --system --run-as-user hermes --start-now
systemctl list-units 'hermes-gateway*'

The output ends with ✓ System service installed and enabled!, Configured to run as: hermes and ✓ System service started. Because root installs it for another user's folder, the unit name gets a short code: hermes-gateway-7944f2ae.service on both of our test machines. Use the name the second command shows:

# as root
systemctl status hermes-gateway-7944f2ae --no-pager
journalctl -u hermes-gateway-7944f2ae -n 30 --no-pager

Now message your bot. If it stays silent, read the log. With a wrong token we got the lines below, and the service stopped with status 78 instead of restarting in a loop:

ERROR ... [Telegram] Failed to connect to Telegram: The token `123456789:***` was rejected by the server.
ERROR gateway.run: Gateway exiting cleanly: telegram: Telegram bot token rejected ... generate a new one with @BotFather and update TELEGRAM_BOT_TOKEN.

Those lines also prove the outbound path works: the gateway reached Telegram, and Telegram answered. Fix the token with hermes config set as the hermes user, then run systemctl restart hermes-gateway-7944f2ae as root, as after every config change. The first start with Telegram peaked at 595 MB while Hermes installed its Telegram libraries, one more reason to keep the swap file on a Nano; later starts peaked at 274 MB.

Optional: run the agent's commands in a Docker sandbox

By default Hermes runs shell commands directly as the hermes user. In our test such a command ran as uid 1000 on the server, so it could read anything that user can, including ~/.hermes/.env with your keys. The Hermes security page lists a container backend such as Docker in its checklist for gateway servers, and on a Micro or bigger it is worth the extra 120 MB of RAM. If Docker is new to you, our Docker on a VPS guide explains the basics.

# as root
apt install -y docker.io
usermod -aG docker hermes

# as the hermes user, after switching in again
hermes config set terminal.backend docker
hermes config set terminal.docker_image python:3.13-slim
hermes config set terminal.container_memory 1024
hermes config set terminal.container_cpu 1

Restart the service as root afterwards. We chose python:3.13-slim (118 MB) over the default desktop image (3.05 GB), and 1024 MB because the default limit is 5,120 MB, more than a small server has. With the sandbox running, the agent's command ran as root inside a container named hermes-5215a975, with the 1 GiB limit, all Linux capabilities dropped except a few for file ownership, and no-new-privileges. Inside it, /root/.hermes/.env and the Docker socket didn't exist, so a confused agent can't read your keys or control Docker. It could still add what it needs: apt-get install git curl took 22 seconds.

There are two trade-offs. Membership in the docker group gives the hermes account root-level power over Docker; the agent's commands stay in the container, but the gateway itself is trusted, so keep the Telegram allowlist tight. And the browser: with the slim image the browser tool refused to start and asked for the desktop image. Our workaround was to run Hermes's own Chromium on the server, outside the sandbox. That needs an install without --skip-browser and these system libraries:

# as root
apt install -y --no-install-recommends libnss3 libnspr4 libatk1.0-0t64 libatk-bridge2.0-0t64 libcups2t64 libxkbcommon0 libatspi2.0-0t64 libxcomposite1 libxdamage1 libxfixes3 libxrandr2 libgbm1 libcairo2 libpango-1.0-0 libasound2t64

# as the hermes user
hermes config set bot_desktop.placement gateway

After a restart the agent opened a test page and read its title; the server peaked at 605 MB used while Chromium ran.

Hermes Agent or OpenClaw?

OpenClaw is the other popular self-hosted agent you talk to through chat apps. Both are MIT-licensed and run on a server you control; our OpenClaw VPS guide covers it in depth.

Details come from the Hermes and OpenClaw GitHub pages. If you mainly want an agent that writes code in your repositories, also read Claude Code and Codex running 24/7 on a VPS.

Which plan to pick

VPS plans use shared vCPUs, which suits an agent that waits most of the day. For a local model instead of a cloud one, look at the VDS plans with dedicated vCPUs. Every plan runs on KVM with NVMe storage, unmetered traffic and its own IPv4 and IPv6 addresses, in Amsterdam, Dublin and Prishtina, and you can move up a plan later from the client area with a short reboot. Availability by city is on the plans page.

Frequently asked questions

Can Hermes Agent run on a 1 GB VPS?

Yes, once it is installed. In our lab the gateway held about 218 MB of RAM idle on a 1 GB virtual machine and left 414 MB available. The installer is the problem: without swap it stalled while building the web interface. Create a 2 GB swap file first and skip the browser tools.

Does Hermes Agent need an open port for Telegram?

No. By default the gateway polls Telegram: it opens outbound connections and asks for new messages. You only need a public HTTPS address if you switch to webhook mode, which the docs describe as mainly useful for cloud hosts that sleep when idle.

How much does Hermes Agent cost to run?

The software is free under the MIT licence. You pay for the server and for the model's tokens. Each call carries roughly 11,000 to 12,000 tokens of instructions and tool descriptions, so by our estimate 30 messages a day cost about $2 to $4 a month on a budget model and $49 or more on Claude Sonnet 5.5, before caching discounts.

Can I use my ChatGPT or Claude subscription with Hermes?

The Hermes docs list a ChatGPT login through the OpenAI Codex provider, but they don't say which ChatGPT plans qualify. For Claude, a Pro login can't be used and a Max login only spends purchased extra usage. An Anthropic API key, billed per token, works either way.

Is it safe to let an AI agent run commands on my server?

It is as safe as the limits you set. Run it as a user without sudo, allow only your own Telegram ID, keep ~/.hermes/.env at mode 600, and use the Docker backend so commands run in a container that can't see your keys. On the default local backend, Hermes also screens each command: per its security docs it lets low-risk ones run, blocks clearly dangerous ones and asks you about the rest.

How do I update Hermes Agent?

Run hermes update as the hermes user. It pulls the new code, rebuilds what changed and checks whether the running gateway needs a restart; in our lab it answered "Already up to date!". Run hermes doctor afterwards to confirm the install is healthy.

Start small, add room when it earns it

Hermes Agent is one of the few AI tools where the server really can be small: the model works elsewhere, and the gateway sits at around 220 MB until you message it. Start on a Nano with swap, or on a Micro if you want the Docker sandbox from day one, and move up when the agent takes on heavier work. Pick a server on the plans page, or message us on Telegram if you'd like us to quote the setup for you.

← All articles