Hermes Agent tutorial for a self-hosted AI agent workflow with Hermes Desktop, terminal setup and security

Operations manager delegating tasks to Hermes Agent on a Microsoft Surface Pro

Hermes Agent is an open-source AI agent built by Nous Research. You install it on your computer or a server and connect it by API to the large language model (LLM) you prefer. Then you hand it tasks that it runs with tools, memory and reusable skills. The code is released under the MIT license.

What you’ll take from this

You will know what this agent does and whether to try it now. If you prefer a gentler start, the Certificate Program in Artificial Intelligence and Innovation teaches agents and automations with tools such as n8n and Copilot Studio.

  • Tell an AI agent from a chatbot and see what Hermes Agent is for
  • Estimate the real cost of running it, even though the software is free
  • Follow the steps to install it, pick a model and connect it to Telegram
  • Apply a security checklist before the agent touches your files

What is this open-source AI agent and who built it?

Hermes Agent is an autonomous, open-source AI agent created by Nous Research, an AI lab. It runs from the command-line interface (CLI), the Hermes Desktop app or messaging apps, keeps memory across sessions and reuses skills. The code is public on GitHub, so you can review it before you install it.

A chatbot answers in a window and forgets the context when you close it. Hermes acts. It runs commands, searches the web, writes files and remembers how it solved the task last time. The project’s GitHub repository carries the tagline “The agent that grows with you”, and Nous Research describes it as a self-improving AI agent with a built-in learning loop that creates skills from experience.

For memory, the project README says the agent searches its own past conversations and builds a deepening model of who you are across sessions. The documentation refers to FTS5 search over past sessions and Honcho dialectic user modeling for this profile. Confirm the details in the documentation of your version, because this pipeline evolves.

What can this agent do for your workflow?

This agent automates tasks that need several steps, such as researching, processing files, generating content and notifying you when it finishes. Its abilities come from built-in tools, skills you install or write, and Model Context Protocol (MCP) servers. Each MCP server you connect extends what the agent can reach, such as a database or a calendar.

Built-in tools change with every release, so check this list against the official documentation before you rely on it. For terminal backends, the repository mentions Modal, Daytona and Vercel Sandbox, plus backends such as Singularity/Apptainer. A built-in cron scheduler also lets you create, pause and resume scheduled tasks, which run in fresh sessions without the context of your current chat. Start with these capabilities.

  • Web search and browser automation through a browser the agent controls
  • Image generation
  • Terminal commands in different environments, from Docker to a remote server
  • Isolated subagents that split work in parallel
  • Persistent memory across sessions and user profiles

How do you create and manage skills?

A skill is a document with step-by-step instructions for one workflow, which the agent loads when it needs it. You write it as a SKILL.md file with a header and the steps. The open format is described at agentskills.io, which makes skills easier to share between compatible agents.

Here is an example from a real communications task. Send Hermes this prompt through the CLI or a messaging app.

Search the web for the five most relevant news items from the last week on AI regulation in the United States. Summarize each in two lines and include the original link. Save the procedure as a skill called weekly-ai-summary and send me the result on Telegram.

Check that every link exists and that each summary reflects its source. The first run usually needs tweaks to the relevance criteria, and the skill saves you from repeating those corrections every Monday.

Is Hermes Agent free and how much does it cost?

The software is open source and you can download it without paying a license, but running it has indirect costs. You pay for the AI model you connect by API. You also pay for the server if you keep it always on and for any cloud services you add. Rates change, so confirm them with each provider.

Before you leave it working alone, set a spending limit in your model provider’s dashboard. An agent that retries a task in a loop can burn through many tokens in a single night.

What is Nous Portal and do you need it?

Nous Portal is an optional model service, and you do not need it. Check its site for what it includes and what it costs before you subscribe. You can connect OpenRouter or your own OpenAI-compatible endpoint instead by running the hermes model command and choosing a provider or a custom endpoint.

How do you follow this Hermes Agent tutorial and install it step by step?

You install it with the official installer that Nous Research publishes in its GitHub repository and documentation. The Hermes Agent docs list instructions for Linux, macOS and Windows, plus Hermes Desktop, a desktop app with a graphical interface. Always use the current command on that page, because it changes between versions.

  1. Check the official documentation for your system requirements and free disk space.
  2. Run the official installer from the Nous Research page, never from a third-party tutorial.
  3. Choose a model provider and paste your API key, or sign in to Nous Portal.
  4. Launch the CLI or the desktop app and ask for a harmless task, such as summarizing a test file.
  5. Turn on the messaging gateway only after the CLI works well.

Should you run Hermes Agent in the terminal, on your desktop or on a VPS?

Run it locally for tests and on a virtual private server (VPS) only when it must be available around the clock. Hermes can execute commands in several environments, and that choice decides how much risk you take and how much you pay. The table shows when each option fits.

OptionWhen it fitsWhat to watch
LocalTests on your laptop with the CLI or the appIt can reach your files unless you restrict it
DockerIsolating the agent from the rest of your systemMount only the folders it needs
VPS over Secure Shell (SSH)Keeping it available 24 hours a dayMonthly cost and security maintenance
Modal, Daytona or SingularityCloud environments or shared clustersConfirm pricing and requirements in their documentation

A VPS turns Hermes into a self-hosted AI assistant that stays available, but you are responsible for updating and protecting it. Use SSH keys and do not open ports you do not need.

Which AI model can you connect through the API?

The agent ships without a model of its own, so you connect an API provider and can switch whenever you want. Its README lists Nous Portal, OpenRouter, OpenAI and your own endpoint, and the Docker guide shows ANTHROPIC_API_KEY and OPENAI_API_KEY variables for direct provider access. Pick a model that supports tool calling, because without it the agent cannot act.

To switch, reopen the configuration from the CLI, choose another provider and repeat the same test task. Compare answer quality and cost per task. A spreadsheet is enough to decide.

How do you message the agent from the terminal, Hermes Desktop or Telegram?

You talk to it in the CLI, in the app or through the messaging gateway, a process that keeps Hermes listening on platforms such as Telegram. Check the documentation to see whether your version also supports Discord, Slack or WhatsApp.

First you create the bot or account on the platform, then paste its token into the Hermes configuration and limit which users can message it.

That limit is mandatory. A Telegram bot without an allowed-user list lets anyone who finds its name give orders to an agent with access to your terminal. Test it first with your own account.

Is Hermes Agent better than OpenClaw?

Both are open-source agents built around the same idea, a persistent assistant that acts on your machine. The official sources offer no neutral comparison that names a winner. Keep your current setup untouched while you test, and run both agents against the same tasks in separate folders.

Decide with a test. Define three real tasks, run them in both agents and measure the time and manual corrections you need.

Is it worth learning to use agents like Hermes Agent?

Yes, if your work includes repetitive multi-step tasks, because most organizations already use AI. According to the Stanford AI Index (2025), global private investment in generative AI reached $33.9 billion in 2024, up 18.7% from 2023.

The AI Index 2025 report adds that 78% of organizations reported using AI in 2024, up from 55% the year before.

If you would rather understand the concept before opening a terminal, start with our guide on how to create an AI agent.

What are the risks of Hermes Agent and how do you reduce them?

The main risks are that the agent acts with more permissions than it needs, sends data to a model provider and repeats mistakes without supervision. You reduce them by restricting its access and reviewing every result before you use it.

  • Run it in Docker or on a machine without personal data while you test.
  • Give it access only to the working folder for each task.
  • Set a spending limit with your model provider.
  • Keep keys outside any files the agent can read.
  • Revoke API keys and bot tokens when you uninstall it, because deleting the program does not cancel them.

If you use it with personal data of customers or employees in the EU, the GDPR and Regulation (EU) 2024/1689 on artificial intelligence apply. That regulation was amended by Regulation (EU) 2026/1744. Ask your data protection officer before you connect email or a CRM.

Frequently asked questions

These are the questions that come up most when you start.

Does Hermes Agent run on Windows, Linux and macOS?

Yes, the official documentation includes instructions for Linux, macOS and Windows, and the Nous Research site also offers a desktop app with a graphical interface. Requirements and the recommended method change between versions, so read the official page on the day you install and do not copy commands from old tutorials.

Do you need to code to use Hermes Agent?

You do not need to code, but you do need to be comfortable with a terminal. Installation, model setup and the gateway use commands and configuration files. If you want to avoid the console, start with visual automation tools and come back to Hermes once you master the basic workflows.

Can you use Hermes Agent with ChatGPT or Claude?

You can use OpenAI or Anthropic models if you reach them by API, directly or through OpenRouter. A paid chat subscription is not the same as an API key and is billed separately. Check each provider’s documentation to see how API access is purchased and what it costs.

What should you automate first with Hermes Agent?

Pick low-risk tasks that have clear inputs, such as a weekly news summary, sorting test emails or a report built from a spreadsheet. Avoid irreversible actions at first, like emailing clients or making payments, and review every result before you use it.

Further reading

These sources cover business adoption of AI, the European framework and risk management.

If you want to learn to design agents and automations that work in your job, take a look at the Certificate Program in Artificial Intelligence and Innovation. It runs 3-4 months, is online and includes the Microsoft + Founderz certification with official Microsoft badges.

Module 6 covers automations, workflows and agents with n8n, Microsoft Copilot and Copilot Studio. You can request information or view the syllabus.

Paul Delaney

Paul Delaney has been engineering AI prompts since the GPT-2 era, long before ChatGPT made prompting mainstream. Paul leads SEO, AEO, and GEO strategy at Founderz, improving how the school and its programs are discovered through traditional and AI-powered search. With more than 25 years of experience in education and digital growth, he has used AI daily since 2021 to support his commercial work.