Guide to Hermes Agent: VPS Installation, OpenRouter Setup, Codex CLI, Telegram, and Skills

Getting to know Hermes Agent: what kind of tool it is, what tasks it can perform, how to install it on a VPS, connect an LLM via OpenRouter, set up a Telegram bot, and use skills in practice.

Official website: https://hermes-agent.nousresearch.com/
Github: https://github.com/nousresearch/hermes-agent

Hermes Agent is an open-source “self-learning” AI agent by Nous Research that can be run locally or on a VPS. Unlike a regular chatbot, it can work with tools: a browser, files, terminal, external APIs, messengers, MCP servers, and skills. Hermes stores context, can create and improve skills based on repeated tasks, and continue working through Telegram, CLI, and other channels.

Essentially, it is an environment for launching and orchestrating AI agents. Hermes can use tools, perform chains of actions, and create subtasks through sub-agents. For example, you can ask it to collect ads from Facebook Ad Library, analyze creatives, save the results to a spreadsheet, and send a summary to Telegram without manual involvement.

What can be connected and used

Hermes Agent works not only with LLM models but also with a set of tools for completing tasks. Depending on the configuration, the agent can use:

browser automation via Playwright: open websites, navigate pages, click buttons, fill out forms, and collect data;
terminal and shell commands: run commands on the server, work with files, install dependencies, and execute scripts;
file system: read, create, edit, and save files, including spreadsheets, documents, images, and parsing results;
web search and page analysis: search for information online, open websites, and extract the required data;
messengers: receive tasks and send results through Telegram and other supported channels;
LLM providers: connect models through OpenRouter or other supported options, including OpenAI, Anthropic Claude, Google Gemini, DeepSeek, and other models;
MCP servers: extend the agent’s capabilities with external tools and services via Model Context Protocol;
sandbox environments: run tasks locally, in Docker, over SSH, or in other supported environments;
skills: use ready-made skills for typical tasks and create new skills for repeatable scenarios.

Because of this, Hermes can be used as a universal environment for AI automation: from simple website parsing and exporting data to a spreadsheet to browser scenarios, Telegram bots, API work, document analysis, and multi-step automations.

Hermes + Meta Ads MCP and CLI

Hermes can also be used together with Meta Ads MCP Server and Ads CLI. These are separate Meta Ads AI Connectors tools. In this case, the agent will be able to access an ad account not only through the browser but also through official Meta tools: get lists of accounts, campaigns, and ads, request statistics, export data, and prepare reports.

MCP connects Meta Ads to Hermes as a set of agent tools, while CLI allows tasks to be executed through terminal commands. In both cases, Meta authorization, access to the ad account, and permissions to work with the required data are needed.

Examples of using Hermes Agent

A couple of simple examples of using the Hermes AI agent. The speed and quality of the completed work depend heavily on which LLM is connected.

Collecting creatives

For this example, we connected the paid LLM model google/gemini-3-flash-preview and asked it to collect creatives from Facebook Ad Library for a given keyword:

Work result:

Here are 5 ads for the query "slots" from Meta Ad Library, launched in May 2026:

1. Revo Wheel — Promotion for new players
- Text: 🎰 𝐑𝐞𝐯𝐨𝐥𝐮𝐭 𝐒𝐥𝐨𝐭𝐬 𝐢𝐬 𝐡𝐞𝐫𝐞 🎁 𝐍𝐞𝐰 𝐩𝐥𝐚𝐲𝐞𝐫𝐬 𝐫𝐞𝐜𝐞𝐢𝐯𝐞 𝟐𝟓𝟎 𝐟𝐫𝐞𝐞 𝐬𝐩𝐢𝐧𝐬 𝐨𝐧 𝐭𝐡𝐞 𝐦𝐨𝐬𝐭 𝐩𝐨𝐩𝐮𝐥𝐚𝐫 𝐬𝐥𝐨𝐭𝐬 📲 𝐓𝐡𝐞 𝐨𝐟𝐟𝐢𝐜𝐢𝐚𝐥 𝐚𝐩𝐩 𝐢𝐬 𝐧𝐨𝐰 𝐚𝐯𝐚𝐢𝐥𝐚𝐛𝐥𝐞 𝐚𝐧𝐝 𝐫𝐞𝐚𝐝𝐲 𝐭𝐨 𝐮𝐬𝐞
- Creative: Video (19 seconds) demonstrating gameplay and the app interface.
- Library ID: 26986697264304701
- Launch date: May 13, 2026.
- Platforms: Facebook, Instagram, Messenger, Audience Network.

2. Ice Fishing — Gamified slot
- Text: Play Game (call-to-action button).
- Creative: Static image or short animation focused on the winter fishing theme.
- Library ID: 1010777471469312
- Launch date: May 12, 2026.
- Platforms: Facebook, Instagram.

3. Ice Fishing — Alternative version
- Text: Play Game.
- Creative: Creative variation focused on the winning mechanic.
- Library ID: 969343105882272
- Launch date: May 11, 2026.
- Features: Low reach (under 100 impressions at the time of collection), used for testing.

4. Lost Dutchman Leather Goods — Franklin 2 (Indirect query match)
This ad appeared in the results because of the mention of "card slots" in the product description.
- Text: Detailed description of the "Franklin 2" wallet made of American leather. Mentions "Quick-access back slot for your most-used cards". 20% discount with code DUTCHMAN20.
- Creative: High-quality product photos.
- Library ID: 1298610082381405
- Launch date: May 1, 2026.

5. Revo Wheel — Second variation
- Text: Duplicates the first item (250 free spins for new players).
- Creative: Video adapted for a different placement format.
- Library ID: 982807807495548
- Launch date: May 13, 2026.

Note: In the "slots" category, most active ads currently use video creatives with bright graphics and an emphasis on bonuses (free spins) for new users. Search also returns products (wallets, organizers) that use the word "slots" in a technical description.

Parsing information from a website

Using the free LLM model openai/gpt-oss-120b:free, we asked Hermes to collect information about conferences from the cpa.rip website. After several minutes of background work, we received the result:

Next, we asked it to collect more data. The work process can be tracked right there — Hermes displays a log of its actions by updating the message in real time.

Then we asked it to expand the information and output it as an Excel table. At the end of the log, we can see that Hermes installs the Python libraries needed to complete the task itself. For example, openpyxl is needed to work with Excel files.

As a result, the task was completed:

In addition, Hermes Agent saved the way it completed this task as a separate internal skill

and will use it for the next similar task:

Installing Hermes Agent

Hermes can be run locally on macOS, Windows, or Linux, but it is more often deployed on a VPS because the server works 24/7 regardless of the computer’s state, provides a permanent foreign IP for working with Claude/OpenAI and browser automation, allows Telegram bots, Playwright, and AI agents to stay constantly active, and also isolates the working environment and automations from the user’s main device.

Pros of local launch:

simpler installation and setup;
direct access to local files and browser;
lower latency and faster response;
no need to pay for a VPS.

Cons of local launch:

the computer must be constantly turned on;
home internet and IP may change;
more difficult to ensure stable 24/7 operation;
Hermes gets access to the user’s main system.

Pros of launching on a VPS:

constant 24/7 operation;
stable foreign IP;
more convenient for Telegram bots and browser automation;
isolated server environment;
you can run multiple AI agents and services at the same time.

Cons of launching on a VPS:

server setup is required;
monthly VPS payment;
higher latency compared to local launch;
more difficult work with local files and GUI applications.

Do not run Hermes as root unless necessary. Do not give the agent access to critical servers, private keys, payment accounts, and production infrastructure without a sandbox/restrictions. For testing, it is better to use a separate VPS, a separate Telegram bot, separate API keys with limits, and separate accounts.

Installation on Mac/Windows/Linux

On macOS and Linux, including a VPS, installation is performed through the terminal with the following command:

curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash

Hermes installation on Windows is performed through PowerShell with the command:

irm https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.ps1 | iex

Windows support is in early beta testing — we do not recommend this option.

We will look at further setup in more detail using a server installation as an example.

Installing Hermes Agent on a VPS (VDS)

To run Hermes Agent, you will need a Linux server with Git installed. The installer will install all other components automatically, including Python 3.11+, Node.js v22, ripgrep, and ffmpeg.

Recommended server parameters:

Parameter	Basic configuration	For comfortable work
RAM	2 GB RAM	from 4 GB RAM
Disk space	from 10 GB	from 20 GB
Processor	1 vCPU	2 vCPU and higher

The minimum configuration is enough for a basic Hermes launch, but when using Telegram integrations, the web interface, several active sessions, or browser automation, it is better to use a server with extra resources.

Preparing the VPS

For installing Hermes Agent, we will take a VDS server from friendhosting.

Register and log in on the https://friendhosting.net website
Go to the “Progressive SSD VDS” page
Choose a suitable plan by price and specifications
and click “Next”

Select the server installation country and payment period
In the “Pre-installed software” block, select “Without the control panel”
and proceed to payment by clicking “Order Now”

Depending on your account country, https://friendhosting.net will offer different payment options and instructions on how to pay. You can get a payment card from a card service in our selection: https://cpa.rip/en/finance/bank-cards/.

After payment and the end of installation, the server access details will be sent to your email.

Connecting to the server

Next, you need to connect to the server via SSH using the details from the email.

Open the Putty SSH client (for Windows) or Terminal (for macOS). In our case, we will use Terminal.
Connect to the server with the command: ssh LOGIN@SERVER-IP -p PORT (insert your own details)

Confirm by typing “yes”
Enter the password (for security reasons, it will not be displayed)
Press “Enter”

Update the system:

apt update && apt upgrade -y

and install Git

apt install git curl -y

You can check whether Git is installed successfully by running the command:

git --version

If the Git version is displayed, everything is OK.

Installing Hermes

Let’s move directly to installing the Hermes agent.

Run the command:

curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash

The installation process will start:

By selecting “Quick setup”, you can proceed to configuring Hermes Agent:

Next, we will prepare the API keys needed to configure the agent.

Connecting to the OpenRouter API

To connect the required LLM model to the Hermes agent, we will use OpenRouter. Through it, you can connect top models such as anthropic/claude-sonnet-4, but you can also choose one of the free options available on the platform, which will be enough for some basic tasks. For more serious work, however, it is better to connect paid models while taking their price/quality into account.

In the “Model” section, type “free” in the search field and choose the option that suits you. In our case, it will be the free OpenAI model: gpt-oss-120b:

Immediately copy the model name for yourself. You will need it later:

OpenRouter free models have strict limits. Without purchasing 10 credits, the limit is 50 requests per day. After purchasing 10 credits, it is up to 1000 requests per day. Free models are also limited to 20 requests per minute.

Go to the “API Keys” section
Click “+New Key”

Set a name and click “Create”

Copy and save the created API key for yourself

Creating a Telegram bot

You can communicate with the Hermes agent directly through the terminal, but for greater convenience, connection through various messengers is also supported. In our case, it will be a Telegram bot that we will create through @BotFather. For setup, you will need the bot token and the Telegram ID of the account.

Launch @BotFather
Click “Create a New Bot”

Set the bot name and address. The address must end with _bot.
Click “Create Bot”

At the next step, click “Copy” to copy and save the bot token for yourself

You can find out the Telegram ID of your account, for example, in this bot: @userinfobot

Configuring Hermes Agent

After preparing all the required APIs and IDs, return to configuring Hermes.

Using the keyboard arrows for navigation, select “Quick setup” and press “Enter”

Select “OpenRouter” and press “Enter”

Paste the OpenRouter API key (for security reasons, it will not be displayed) and press “Enter”

A list of models available in OpenRouter will open. If the required model is not in the list, it must be entered manually.

Select “Enter custom model name”
Press “Enter”

Paste the previously saved name of the free model. In our case, this is “openai/gpt-oss-120b:free”
Press “Enter”

At the next step, select “Local” or “Keep current (local)”

At the next step, select “Set up messaging now (recommended)”

We recommend using Telegram to interact with Hermes Agent.

To select the required item, use the keyboard arrows and be sure to press Space to select it. Otherwise, this setup step will be skipped.

After selecting Telegram, continue its setup.

Paste the Telegram bot token you prepared earlier and press “Enter”

Next, paste your Telegram account ID and press “Enter” again

At the next step, confirm by pressing “Y” and “Enter”

Confirm again by pressing “Y” and “Enter”

At this step, select “System service” so that Telegram Gateway starts together with the server and continues working in the background.

At this step, enter “root” and press “Enter”

The example uses root because the installation is performed under the root user on a test VPS. For permanent use, it is safer to create a separate user.

Enter “Y” and press “Enter” to start the service.

Connecting Codex CLI to Hermes

Hermes can be used together with Codex CLI, OpenAI’s terminal AI agent for working with code. This is useful if you need to assign development tasks to Hermes.

Codex does not replace the main Hermes LLM model. Hermes continues to run on the selected model, for example via OpenRouter, while Codex is used as a separate coding tool.

Codex CLI must be installed in the same environment where Hermes runs. If Hermes is installed on a VPS, Codex must also be installed and authorized on that VPS. Codex installed on a local computer will not automatically be available to the agent on the server.

Connect to your server via SSH through the terminal
Check whether Node.js and npm are available with the command:

node -v

npm -v

If Node.js is already installed, you can install Codex CLI:

npm i -g @openai/codex

In our case, npm installed Codex into the Hermes directory: /root/.hermes/node/bin/codex

To make the codex command launch from any location, add this folder to PATH:

echo 'export PATH="/root/.hermes/node/bin:$PATH"' >> ~/.bashrc

source ~/.bashrc

After that, launch Codex:

codex

On the first launch, you need to authorize through a ChatGPT account or an API key.

Codex CLI can be authorized through a ChatGPT account or through an API key. When signing in through ChatGPT, the access and limits of your ChatGPT subscription are used. When signing in through an API key, expenses are calculated separately in OpenAI Platform according to API pricing.

Select the first option to authorize through a ChatGPT account

At the next step, you will be prompted to open a link and enter a one-time code:

Before that, you need to enable “Device code authorization for Codex” in your ChatGPT account settings:

Open the link https://auth.openai.com/codex/device in your browser
Sign in to your account
Click “Continue”

Enter the code and click “Continue”

In the terminal, press “Enter” to finish the installation:

The warning at the top says that the bubblewrap package, which is used for sandbox isolation, is not installed in the system. Codex can temporarily use the built-in option, but it is better to install the system package by running the command:

apt update

apt install -y bubblewrap

Done. Now Hermes can use Codex.

Hermes can choose Codex for a code-related task by itself if CLI is available, but it is more reliable to specify directly: “Use Codex CLI”. This reduces the risk that the agent will complete the task through the main LLM without calling Codex.

Checking Hermes Agent through Telegram

Go to the Telegram bot that you connected to Hermes and send a message, for example, “Hi”. If everything is configured correctly, the agent will reply to you

Working through the console

Open the terminal and connect to your server via SSH
Run the command:

hermes

Now you can chat/work with the agent directly here in the console.

If you have any difficulties working in this mode, try the alternative mode with the following command:

hermes --tui

Hermes profiles

In Hermes, you can create separate profiles for different tasks and projects. A profile is a separate agent environment with its own settings, sessions, memory, and skills. For example, you can keep a work profile, test profile, and personal profile separate so that context and saved skills are not mixed.

Main commands:

hermes profile list — view the list of profiles.
hermes profile create work — create the work profile.
hermes profile switch work — switch to the work profile.
hermes profile current — view the current profile.

If Hermes is used through Telegram, the profile is not switched with a command inside the bot. The Telegram bot is linked to a specific profile through Gateway. Therefore, for different profiles, it is better to use different Telegram bots: for example, one bot for the work profile and another for the test profile.

Additional settings

Let’s look at some important settings and commands.

Changing the LLM model

To switch between connected LLM models in Hermes, use the /model and hermes model commands.

In Telegram:

Send /model
In the received message, click the “OpenRouter” button

Select the required model:

A message with information about the connected model will arrive:

In the Hermes console:

Send /model (you can also type it without /)
Select “OpenRouter”
Press “Enter”

Select the required model and press “Enter” again

In the terminal:

In the terminal after connecting via SSH, enter the command hermes model
then select the required model or add a new one

New session

The /new command starts a new conversation with a clean context of the current chat. Saved sessions, memory, and skills are not deleted. This is analogous to the “New chat” button in ChatGPT or Claude.

The command is useful when: