How to Install Hermes Agent Locally: Step by Step Guide

AI Tool Guides Free AI & API Access How-To Guides Installation Guides
AI Tech Ledger

Hermes Agent is an open source AI agent from Nous Research that can run on your own Windows or Mac computer, connect to cloud or local language models, learn reusable skills, use tools, run scheduled tasks, and even let you control the agent from messaging apps such as Telegram. If you have seen Hermes Agent online but felt the installation guides were too technical, this walkthrough is designed to take you from a blank computer to a working agent without assuming that you already know command line tools.

In this How to install Hermes Agent locally guide, you will install Hermes Agent on Windows 10 or 11 or macOS, connect it to Nous Portal, select a model, learn how to use free models when they are available, set up a Telegram bot gateway, and learn how to remove or revoke your Telegram token later. The instructions were checked against the current official Hermes Agent documentation in August 2026.

Important security rule: never post your Nous Portal API key, Telegram bot token, OAuth credential, or the contents of your Hermes .env file in a screenshot, forum, Discord message, or public GitHub repository. Every token shown in this guide is a placeholder.

What you will set up in this Hermes Agent installation guide

By the end of the tutorial, your computer will have a local Hermes Agent installation and at least one model provider. You will also know how to start a normal terminal chat and, if you want remote access, how to send messages to the same agent through Telegram.

Component What it does Required?
Hermes Agent The local agent runtime and command line interface Yes
Nous Portal Recommended OAuth connection to Nous models and Portal services Recommended
LLM model The model Hermes uses to reason and respond Yes
Telegram bot Lets you talk to Hermes from Telegram on your phone or another device Optional
Gateway service Keeps Telegram and scheduled automations connected to Hermes Optional

Hermes Agent requirements for Windows and Mac

Hermes currently runs natively on Windows 10 and Windows 11. You do not need WSL, Docker, or Cygwin for the standard Windows installation. Nous Research also provides a macOS installation path and a desktop installer. This guide focuses on the terminal method because it makes every step visible and is easier to troubleshoot.

You need an internet connection during installation and model setup. You should also have permission to install software for your own user account. On native Windows, the Hermes installer places its files under your local application data directory and adds the hermes command to your user PATH. The official Windows guide says no administrator rights are required for the normal native installation.

Quick Hermes Agent commands you will use

Task Command
Install on Windows PowerShell iex (irm https://hermes-agent.nousresearch.com/install.ps1)
Install on macOS Terminal curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash
Connect Nous Portal hermes setup --portal
Start a local chat hermes chat
Change model or provider hermes model
Configure Telegram or another messaging platform hermes gateway setup
Run gateway in the foreground hermes gateway
Install gateway as a user service hermes gateway install
Check gateway hermes gateway status
Stop gateway hermes gateway stop

How to install Hermes Agent on Windows

Step 1: Open Command Prompt or PowerShell

If you simply want to open Command Prompt, press the Windows key, type cmd, and press Enter. You can use Command Prompt for many Hermes commands after installation. However, the official native Windows installer is a PowerShell command, so use PowerShell for the actual installation.

To open PowerShell, press the Windows key and type PowerShell. You can also open Windows Terminal and choose a PowerShell tab. A normal user PowerShell window is sufficient for the standard Hermes installer.

Step 2: Paste the Windows Hermes Agent install command

Copy the following command exactly, click inside the PowerShell window, paste it, and press Enter:

iex (irm https://hermes-agent.nousresearch.com/install.ps1)

Let the installer finish. According to the current Windows native documentation, Hermes installs inside your user profile, so a normal install does not require WSL. When the script says installation is complete, close the terminal and open a new PowerShell, Windows Terminal, or Command Prompt window. Opening a fresh terminal is important because Windows may need to refresh the PATH before the hermes command becomes available.

Step 3: Check that Hermes is available

In the new terminal, type:

hermes

If Hermes opens or displays its command interface, the installation is ready. If Windows says that hermes is not recognized, first close every terminal window and reopen one. If it still fails, revisit the official Windows Native Guide and check the PATH troubleshooting section.

How to install Hermes Agent on Mac

Step 1: Open Terminal on macOS

Press Command + Space to open Spotlight Search. Type Terminal and press Return. You can also open Finder, choose Applications, open Utilities, and then open Terminal.

Step 2: Paste the macOS installation command

Copy the official Hermes installation command below and paste it into Terminal:

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

Press Return and wait for the installer to complete. Then close and reopen Terminal before running Hermes for the first time. The official Hermes Agent Installation documentation also offers the Hermes Desktop installer if you prefer a graphical installation.

How to set up the Hermes Agent model with Nous Portal

Installing Hermes gives you the agent software, but Hermes still needs a language model to think with. Nous Research recommends Nous Portal because it can connect Hermes through a single OAuth login instead of forcing beginners to manually maintain several separate API keys.

Open PowerShell, Command Prompt, Windows Terminal, or macOS Terminal and run:

hermes setup --portal

This command launches the Nous Portal authentication flow, lets you choose a Nous model, sets Nous as the inference provider, and enables the Portal Tool Gateway configuration supported by your account. Follow the browser login page that appears and approve the connection. When you return to the terminal, select the model you want to use.

How to change the Hermes Agent model later

You are not locked to the first model you choose. Exit the current Hermes chat if one is running, then use:

hermes model

The current Hermes provider documentation identifies hermes model as the interactive command for switching providers and models. This is useful when a free model becomes available, when you want a faster model for simple automations, or when you want a stronger model for coding and research.

How to use Nous Portal free models without paying

Nous Portal currently describes itself as free to start. Its model catalog and promotions can include models that can be used at zero token cost. The exact free models change over time, so a tutorial that permanently promises one named model would become inaccurate. Instead, sign in at portal.nousresearch.com and check the current Models or Active Promos area for models that are explicitly marked free or currently priced at zero.

The easiest zero friction route for Hermes is still the Portal OAuth command:

hermes setup --portal

If your selected Portal model is currently free, you can use that model through Hermes without paying token charges for that free offering. Free access and promotions can change, so always read the live price shown in Portal before running large jobs.

Do you actually need a Nous Portal API key?

For the normal Hermes setup, no copied API key is required when you use Nous Portal OAuth. That is safer for beginners because there is no secret string to paste into screenshots or accidentally commit to GitHub.

If you specifically need a key for direct API development, sign in to Nous Portal and open the API key management area. Create a new key, copy it once, and store it in a password manager or other secure secret store. The Portal API documentation is available at Nous Portal API Docs. If you later configure Hermes through an API key based provider rather than OAuth, follow the current prompt shown by hermes model instead of pasting the key into random configuration files.

Never put a real Nous API key in your blog post, screenshot, prompt example, or public code. If a key is exposed, revoke it in Portal and create a replacement.

Test Hermes Agent locally before adding Telegram

Before introducing Telegram, confirm that the local model works. Run:

hermes chat

Send a simple prompt such as:

Explain in one sentence what you can do.

If Hermes responds, your installation and model connection are working. This is an important checkpoint. If Telegram fails later, you will know the problem is in the gateway configuration rather than the model itself.

Hermes Agent Telegram setup step by step

The Hermes messaging gateway lets you use the same agent from Telegram. This is useful for remote tasks, scheduled reports, quick research requests, and automations that return their results to your phone. Hermes can receive text and other supported Telegram content through the bot integration.

Step 1: Create a Telegram bot with BotFather

Open Telegram and search for @BotFather, Telegram’s official bot management account. Start the chat and send:

/newbot

BotFather asks you for a display name. You can use a name such as My Hermes Agent. It then asks for a unique username. Telegram bot usernames must end in bot, for example my_private_hermes_bot.

When creation is complete, BotFather sends a bot token. It looks similar to this fictional example:

123456789:ABCDEF_EXAMPLE_TOKEN_REDACTED

Copy your real token privately. Do not send it to anyone.

Step 2: Find your Telegram numeric user ID

Hermes can restrict the bot so only approved Telegram users can trigger your agent. The official Hermes team tutorial suggests messaging @userinfobot to obtain your numeric Telegram user ID. Copy that numeric value. You can also use Hermes’s newer pairing flow when available, where an unknown user receives a one time pairing code that the owner approves.

Step 3: Run Hermes gateway setup

Back on your computer, open the terminal and run:

hermes gateway setup

Select Telegram when the wizard displays the messaging platforms. Paste the BotFather token only when the Hermes setup wizard asks for it. If the wizard asks for allowed users, enter your numeric Telegram user ID. Keeping an allowlist is safer than allowing anyone on Telegram to send commands to an agent running on your computer.

Step 4: Start the Hermes Telegram gateway

For a first test, run the gateway in the foreground:

hermes gateway

Keep the terminal open. Go to Telegram, open the bot you created, and send a simple message. If the access controls and model are configured correctly, Hermes should process the request and reply through Telegram.

Step 5: Keep the Telegram gateway running for automations

If you want Telegram and scheduled Hermes automations to continue working without leaving a terminal window open, install the gateway as a user service:

hermes gateway install

Then check it with:

hermes gateway status

On native Windows, the current Hermes documentation says the gateway installer uses Windows Scheduled Tasks with a Startup folder fallback and does not normally require administrator access. On macOS it uses the operating system’s user service mechanism. This makes the gateway suitable for recurring tasks because Hermes can remain available after you close the terminal.

How to use Hermes Agent automations from Telegram

Once the gateway is running, Telegram becomes a convenient remote interface rather than a separate AI. You are talking to your Hermes Agent instance and its configured model, memory, tools, skills, and scheduled jobs.

For example, you can ask the agent to research a subject, work with files it is allowed to access, or create a scheduled task supported by Hermes. Scheduled gateway tasks can return results through the messaging integration. Start with low risk automations and review the agent’s permissions before allowing it to perform actions that modify files, accounts, or external systems.

If you are exploring more no cost AI workflows, see AI Tech Ledger’s Free AI and API Access section. For other installation tutorials, visit Installation Guides.

How to remove your Telegram API token from Hermes Agent

There are two different reasons to remove a Telegram token. You may simply want to disconnect Telegram from Hermes, or you may believe the token has been exposed. If it has been exposed, deleting the local copy is not enough. You must revoke the token with BotFather as well.

Step 1: Stop the gateway

hermes gateway stop

Confirm the service state if needed:

hermes gateway status

Step 2: Remove the local Telegram credential

Hermes keeps user managed secrets in its Hermes home directory. On macOS and Linux style installations this is normally ~/.hermes/. Native Windows stores Hermes data under %LOCALAPPDATA%\hermes. Look for the Hermes .env secret file and remove the line containing:

TELEGRAM_BOT_TOKEN=YOUR_TOKEN_HERE

Do not delete unrelated provider keys. If you prefer not to manually edit secret files, rerun hermes gateway setup and reconfigure the Telegram integration using the current wizard.

Step 3: Revoke the Telegram token if it was leaked

Open BotFather in Telegram and send:

/revoke

Select the affected bot. BotFather invalidates the old credential and gives you a new token when appropriate. An old token that has been revoked can no longer be used to authenticate the bot.

If you want Telegram connected again, run hermes gateway setup, enter the new token, and then restart or reinstall the gateway service as required.

Hermes Agent troubleshooting for Windows, Mac, Nous Portal and Telegram

Problem What to try
hermes is not recognized on Windows Close every terminal and open a fresh one so the user PATH reloads. Confirm the Windows installer completed successfully.
PowerShell install command fails Copy the current command from the official Hermes installation page and confirm your internet connection can reach the Hermes and GitHub installation resources.
Mac says command not found after install Close Terminal and reopen it. If necessary, review the shell PATH notes in the official installation documentation.
Portal login does not finish Run hermes setup --portal again and complete the browser OAuth flow using the same account.
You want a different model Exit the active chat and run hermes model.
Hermes works locally but Telegram does not Run hermes gateway status, confirm the bot token is valid, and rerun hermes gateway setup.
Telegram bot ignores your account Check the allowed numeric Telegram user ID or complete the Hermes pairing flow if your version uses pairing codes.
Telegram token was exposed Stop the gateway, remove the local token, then use BotFather /revoke immediately.
Free model disappeared Free models and promotions change. Open Nous Portal’s current model list and choose another model explicitly marked free, then run hermes model if you need to switch.

Security tips before you automate your computer with Hermes

Hermes is more capable than a normal chatbot because agents can use tools and interact with systems. Treat its credentials and permissions like you would treat access to an automation server.

  • Restrict Telegram access to your own user ID or explicitly paired users.
  • Never publish TELEGRAM_BOT_TOKEN, API keys, OAuth credentials, or your full .env file.
  • Revoke credentials immediately if they appear in a screenshot or public repository.
  • Use a separate bot token for separate Hermes profiles if you run multiple agents.
  • Start with reversible, low risk automations before allowing file deletion, account changes, or external publishing.
  • Review prompts and tool permissions before leaving a gateway running unattended.

Frequently asked questions about installing Hermes Agent locally

Is Hermes Agent free?

Hermes Agent itself is free and open source under the MIT license. What you pay for depends on the model and external services you connect. Local models can be run without an API bill, and Nous Portal can offer models or promotions that are free to use.

Does Hermes Agent need WSL on Windows?

No. Current Hermes documentation supports native Windows 10 and Windows 11. WSL remains an optional alternative for users who specifically want a Linux environment, but it is not required for the standard native Windows installation.

Can I install Hermes Agent from Command Prompt?

You can run many Hermes commands from Command Prompt after installation, but the official native Windows one line installer uses PowerShell syntax. Open PowerShell or a PowerShell tab inside Windows Terminal to run the installer.

What command installs Hermes Agent on Windows?

The current official native Windows command is iex (irm https://hermes-agent.nousresearch.com/install.ps1).

What command installs Hermes Agent on Mac?

The current terminal command is curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash.

Can I use Hermes Agent with a free model?

Yes, when you connect a local model or select a model that Nous Portal currently marks as free. Portal promotions and free model availability can change, so check the live model catalog before assuming a particular model will remain free permanently.

Do I need a Nous API key to use Hermes?

Not when you use the recommended Nous Portal OAuth flow. Running hermes setup --portal authenticates through the browser without requiring you to manually copy a Portal API key into Hermes. API keys are still available for users who need direct API access.

Can Hermes Agent run from Telegram?

Telegram acts as a remote messaging interface to your Hermes Agent. Create a bot through BotFather, run hermes gateway setup, select Telegram, enter the private token and allowed user details, then start the gateway.

How do I keep Hermes Telegram automations running?

After testing the foreground gateway with hermes gateway, use hermes gateway install to install the gateway as a user service. Use hermes gateway status to check it.

How do I delete a Telegram API token from Hermes?

Stop the gateway with hermes gateway stop, remove the TELEGRAM_BOT_TOKEN entry from the Hermes secret environment file or reconfigure the gateway, and use BotFather /revoke if you need the old Telegram token invalidated.

Final thoughts: the simplest way to install Hermes Agent locally

For most beginners, the shortest reliable workflow is simple: install Hermes with the official Windows PowerShell or macOS Terminal command, run hermes setup --portal, choose a model, confirm it works with hermes chat, and only then add Telegram with hermes gateway setup. Separating the installation, model test, and messaging setup makes troubleshooting much easier.

The most useful change in the current Hermes setup is that native Windows users no longer need to treat WSL as mandatory, and Nous Portal OAuth removes much of the API key handling that previously made local agent setup intimidating. If you want a completely zero cost route, use a local model or choose a Nous Portal model that is explicitly free at the time you use it.

Related AI Tech Ledger guides

Official references

Related Posts