Introduction: why look at Hermes Agent
In this guide we’ll walk through installing Hermes Agent, or “Germes”, as you might call it in Russian.
Why Hermes Agent in particular? There are already agents built on Claude Code, Gemini and Codex. All of them can run on official subscriptions. That is, we don’t pay separately for API usage; we talk to the agents through a Telegram chat via a dedicated bridge. At first glance that’s enough: these agents really do work well, handle a large volume of tasks and are very powerful overall.
But lately people have been hitting limits more and more often. Some can’t pay for a subscription. Some hit regional restrictions. Some get their account blocked, especially with Claude Code. Many people have trouble with Gemini too: they can’t register properly because they get messages about temporary restrictions.
Against that background, Hermes Agent looks like one of the simplest ways to use an AI agent while avoiding some of these problems. In essence it’s a good option for beginners: you can install it fairly quickly, connect it to a model, set it up to work through Telegram and start using it for real tasks.
What Hermes Agent is and why it’s convenient
Before moving on to installation, it’s worth briefly covering what Hermes Agent is and where its advantage lies.
To my mind, the main advantage of Hermes Agent is that it’s considered one of the easiest agents for beginners. It also learns on its own: you do some work together, and the next time a similar task comes up, it can activate the right skill by itself.
So instead of telling it every time, “Remember, next time we’ll do it the same way”, the agent can create skills itself and apply them in similar situations. That makes it handy not just for one-off tasks but for regular work, where it pays to build up experience over time and repeat what worked.
Where you can install Hermes Agent
There are several options for installing Hermes Agent.
The first is to install it on your local computer. That could be a laptop, a MacBook or another system that can run the agent. In this case you can use a local LLM through Ollama or a similar service. The advantage of this approach is that you can work for free, without paying for an API. But you need a fairly powerful computer, because the agent’s response speed will depend on your hardware.
The second option is to install Hermes Agent on a VDS. Personally I prefer this one. You buy a VDS, preferably outside the regions where restrictions can apply, and install the agent there. That way the agent won’t come back telling you it has regional restrictions or that some services are unavailable.
The advantage of a VDS is that the agent doesn’t live on your main computer. It sits in a separate environment and can be available 24/7. It keeps working whether your laptop is open or closed. The downside is that you usually can’t run a local model properly on a cheap server. If you use the most basic server, say for a few dollars a month, there may not be enough resources for a local LLM.
In that case it’s better to connect Hermes to a paid model through an API. OpenRouter works well for this: it makes it easy to choose the model the agent will run on.
Choosing a model and API costs
You can pick different models for Hermes Agent. There are expensive ones like ChatGPT, Gemini Pro or Claude Sonnet, and there are cheaper options you can use for testing and small tasks.
DeepSeek models are one option. You can also look at Gemma/Gemini and other models available through OpenRouter. The point is that Hermes isn’t tied to one specific provider. You can choose a model that fits your tasks, budget and quality requirements.
If the agent runs through an API, you need to understand that every request costs money. That’s different from an official subscription, where you pay a fixed amount and don’t count every token. With OpenRouter it’s best to set a spending limit straight away, for example $10 for testing. That way you can try the agent calmly without running into an unexpectedly large bill.
On the one hand, working through an API can be cheap, especially if you pick a budget model. On the other hand, if the agent starts actively running long tasks, calling the model many times and generating long answers, costs can grow. So limits and cost control are a must, not an optional extra.
Preparing the server and installing Hermes Agent
First you need a server: a VDS or another environment where Hermes will be installed. The first thing to do is make sure Git is installed on the server. You can run the Git version check command for that. If Git isn’t installed, install it.
Then the installation is started with a single command from the instructions. Copy the command into the terminal on the server, and the Hermes Agent installation begins.
Before installing, check that the server has enough free space. If we’re going with the API and OpenRouter, you don’t need much space. If you install a local model, though, you’ll need far more resources, in both memory and performance. On a cheap server a local model can run very slowly and overload the system.
The installer sets up the required dependencies itself: Python, Node.js and other components, if they’re missing. Some of this could be done by hand, but for beginners it’s easier to follow ready-made instructions and use the automatic install.
During installation Hermes offers a choice: a quick install or a full one. For the first run you can choose the quick install. After that the installer walks through the main settings by itself.
Connecting OpenRouter and choosing a provider
At the next stage you choose which provider the model will run through.
The list can include various options: the official Claude API, LLM Studio, OpenRouter and other model providers. If we want to work through OpenRouter, we choose OpenRouter.
To do that, go to OpenRouter and create a new API key. You can name the key, for example, Hermes. It’s also a good idea to set a spending limit straight away. For example, you can cap the key at $10 while you’re testing.
Once created, the key needs to be added to the Hermes setup. It’s good if the system doesn’t show the key in plain text in the chat or the terminal. But remember all the same: an API key is sensitive information. Don’t publish it, send it to strangers or store it in the open.
After adding the key, choose a model. In the instructions you can check in advance which models are suitable, how much they cost and which tasks they’re best for. For a test you can pick one of the budget models, then switch to a more expensive, higher-quality one if needed.
Where the agent will run
After you choose the model, Hermes asks where it should run. In our case the agent is installed on the server and will work right there in the server environment.
Some settings can be done right away, others later. During initial setup you can choose the platform for talking to the agent. Hermes can work through different channels: email, WhatsApp, WeChat, Google Chat, Line, Microsoft Teams and others. But to start with, Telegram is the easiest to set up.
Telegram is good because you can quickly send tasks to the agent through it, get answers, check the state of the system and gradually turn the agent into a full-time assistant.
Checking the installation with Visual Studio Code
To see how Hermes was installed on the server, it’s handy to use Visual Studio Code. You can connect to the server through it and see the Hermes folder. Inside are documentation files, configuration and other internal files of the agent.
From the terminal you can launch Hermes and check its status. The instructions have commands for starting a Hermes chat, choosing a model, checking the configuration and running diagnostics. For example, you can run Hermes Doctor to check that everything is set up correctly.
If you need to change the model, run the model selection command again and choose OpenRouter or another provider.
The soul.md and agents.md files
Hermes has files like soul.md and agents.md. In them you can describe who the agent is, how it should behave, what tasks it’s used for and what context it has.
Ready-made guides may include templates for different scenarios: for a developer, a marketer, a content creator, an entrepreneur. But it’s better not to paste such templates in without thinking. First work out what exactly you’ll use the agent for, which tasks you want to delegate, what limits it has to respect and what style of communication you want.
You can ask the agent itself to help with the setup: let it ask you about your tasks, projects, working rules and the answer format you expect. Then, based on your answers, you can gradually shape its context.
Creating a Telegram bot
Now let’s connect Hermes to Telegram.
First you need to create a Telegram bot through BotFather. Open BotFather, create a new bot, give it a name and get a token. Copy this token and add it to the Hermes configuration.
Hermes has a .env file. It stores environment variables, including API keys and tokens. It’s very important not to show this file to anyone or send it to anyone, because your keys are inside. If someone gets access to .env, they’ll be able to use your API keys and control the connected services.
In the .env file, find the TELEGRAM_BOT_TOKEN line, or a similar line for the Telegram token, and paste in the token you got from BotFather.
Besides the bot token, you need to specify a Telegram User ID: the ID of the user who is allowed to talk to the bot. This is for security, so the bot doesn’t answer everyone. You can get your User ID through a dedicated Telegram bot, for example get ID Bot. Then add the ID to the list of allowed users.
There are two ways to set this up. The first is to open the .env file manually in Visual Studio Code and carefully enter the tokens. The second is to give the agent the token and User ID and ask it to connect Telegram. But the second way is less secure, because you’re sending the key straight to the agent. So it’s better to set everything up by hand.
First error: the OpenRouter API key wasn’t picked up
After the initial setup, check whether Hermes can write to Telegram.
Sometimes an error shows up at this stage: Hermes doesn’t see the OpenRouter API key. This can happen if the key wasn’t entered correctly in .env, if extra lines appeared in the file, or if the same key was added several times.
You can fix this by hand: open .env, delete the extra lines and add the correct API key. You can also use a dedicated command to update the key, if the Hermes setup provides one.
Then start Hermes again and check whether it sees OpenRouter. If everything is set up correctly, the agent should respond in the terminal and start working through the chosen model.
Checking the Telegram connection
Once the token and User ID are set, you can write to the agent and ask it to send a message to Telegram.
If the agent replies that Telegram isn’t set up yet, check the .env file. The Telegram token lines may be commented out. In that case uncomment them and save the file.
You may also need to restart the Telegram gateway. In the early stages with a new agent it’s better not to close the terminal, even if you plan to talk to the agent through Telegram. The terminal helps you see what’s happening under the hood: which commands run, which errors come up, which services are running.
Once it’s set up correctly, the bot should reply in Telegram. For example, if you write “Hi, are you there?”, it should confirm that it’s ready to work.
Next the bot may ask you to set a home channel for automatic notifications and cron messages. To do that, run the corresponding command in the chat with the bot, for example set home, if the setup provides such a command. After that the current chat becomes the main channel for automatic messages.
Checking voice messages
The next step is to check whether Hermes can accept voice messages.
You can send the agent a voice message and ask whether it can process it. If speech recognition isn’t set up, the agent will say it can’t listen to the voice message yet because no STT provider is configured.
In that case you need to set up speech recognition. Hermes can check the configuration and see whether Whisper or another STT provider is available. In some configurations the local fast-whisper provider may be switched on while the package itself isn’t installed yet.
Fast-whisper is a free option that runs right on the server and doesn’t need a separate API key. After installing the package, restart the gateway so it starts using speech recognition.
There’s one more catch here: if the process was started by hand, the restart command may stop the gateway but not start it again. So it’s better to install the Telegram gateway as a system service. Then it runs as a background service, and restarts work properly.
After that you can send a voice message again and check whether the bot now recognises it.
System messages and how the Telegram bot behaves
When Hermes works through Telegram, it can send not only the final answer but also system messages: what it’s doing, which skill it’s looking for, which process it’s starting, which command it’s running.
At the start this is actually useful: you see how the agent thinks at the level of actions, what it checks and where an error might come up. But for everyday use this behaviour can get in the way. In normal work it’s more convenient to get just a clean final answer without the technical noise.
You can set this up later, once the basic Hermes + model + Telegram setup is working reliably.
What’s inside Hermes Agent
In Visual Studio Code you can look at the structure of Hermes Agent. Inside are folders with skills. Quite a lot of skills are installed by default.
This is the moment to talk about security. When you install skills for your AI agent, ideally they shouldn’t come from dubious third-party sources. An agent with terminal access is an agent with access to everything on your server. Install a harmful or unvetted skill, and you can create serious problems for yourself.
Unofficial agents and open-source solutions need to be treated with care. Maybe lots of people use the project and it’s all safe. Maybe not. So install such tools deliberately: read the documentation, check the skills, restrict permissions and don’t give the agent more access than it needs.
When we work with official systems like Codex, Claude Code or Gemini, we at least know who’s behind those products. With third-party open-source agents the risks are higher, and you have to take them into account.
Limitations and downsides of Hermes Agent
Hermes Agent has limitations as well as advantages.
First, on Windows it only works properly through WSL. If you’re on Windows and don’t know what WSL is, you’ll have to figure it out. Or you can go straight for a VPS/VDS, as in this example.
Second, the agent’s memory isn’t unlimited. If you don’t clean it up and structure it, the agent will start forgetting older things. So it’s important to think through how exactly you’ll store context, make backups and manage memory.
Third, Hermes isn’t a SaaS service you switch on and forget. It’s more of a self-hosted server tool. Every so often you have to update and check it, make backups, keep an eye on costs and watch the background processes.
Fourth, if you connect an expensive model and schedule lots of tasks, the API bill can be an unpleasant surprise. Especially if the agent starts running long tasks, calling the model often and generating long answers.
The main risk: too much autonomy
The main risk with AI agents is giving them too much freedom in autonomous tasks.
For example, an agent was supposed to prepare a morning digest. It started gathering content and then began sending emails on its own. That’s a potentially dangerous scenario, because the agent went beyond simply preparing material and started taking actions on the user’s behalf.
So for automated tasks it’s better to follow the principle: show me first, then do it. Let the agent prepare a draft first, show it to you, and only carry out the action after you confirm.
Be especially careful with messages to clients, financial operations, documents, mailings and any actions that can have consequences.
Telegram bot security
If someone gets access to your Telegram bot, they can take control of the agent. And if the agent has terminal access, the server can potentially be controlled through it.
So there are a few basic rules.
First: don’t run the agent with root access unless you really need to.
Second: always specify the allowed users through an allow list. Only your User ID should be listed for Telegram.
Third: don’t install other people’s skills without checking them. Read what they do, where they’re downloaded from and which commands they run.
These rules seem simple, but they’re exactly what helps you avoid the nastiest scenarios.
Scheduler, Obsidian memory and extra features
In Hermes you can set up memory through Obsidian. You can also use a task scheduler: the built-in cron or separate settings inside the agent. You can use parallel subagents, system skills and MCP integrations. The agent can work 24/7 if it’s installed on a server.
In terms of features, Hermes is in many ways similar to other AI agent systems. The difference is rather that it’s open source, isn’t tied to one model provider and can teach itself through skills.
If you need to recommend an agent to someone starting from scratch, Hermes can be a good first choice. The reasons are simple: open-source code, independence from a single provider, self-learning and a relatively clear installation.
But if you need maximum reasoning depth, an official ecosystem, deep specialisation for a particular stack and work through a subscription, then Claude Code, Codex or Gemini may be preferable.
The best setup depends on the task. You can use Hermes as a standalone agent. You can use Claude Code. You can keep several agents and split different tasks between them.
Initial setup of the agent’s behaviour
After installation Hermes already works pretty well out of the box. It may answer in English at first, though. For a Russian speaker the fix is one message: “Only write to me in Russian in Telegram.” After that it should save this rule in its context.
From there you train the agent bit by bit. You explain which tasks you want to delegate, how it should answer, which actions it can take and which it has to clear with you first. Step by step you shape its working environment.
The main thing is to have a clear idea of the tasks you want to hand over to an AI agent. That’s probably the most important point. The agent won’t solve anything on its own if you don’t understand what you need it for. But if you have clear scenarios (working with files, code, a server, Telegram, a schedule, voice messages, preparing materials), then Hermes can gradually be turned into a useful assistant.
Final takeaway
We’ve covered installing Hermes Agent, connecting OpenRouter, choosing a model, setting up a Telegram bot, handling tokens, restricting access by User ID, checking the Telegram connection and the initial setup of voice messages.
Hermes Agent really does look like a convenient option for beginners, especially if you have problems with official subscriptions, payment, registration or regional restrictions. But remember: this isn’t just a chatbot. It’s an agent that can get access to a server, files, the terminal and external services. So set it up carefully, watch your API spending, restrict permissions and don’t give it more autonomy than it needs.
The idea of working with such agents is roughly the same everywhere, whether it’s Hermes, Codex, Gemini or Claude Code. Some agents are used through an API, some through a subscription. But what matters most isn’t the installation itself but understanding the tasks you want to hand over to the agent and the rules it should follow.
