Hermes Agent: an agent on your machine, not a chat in the browser

Who it is for

Hermes Agent fits if you administer the machine, and if you accept that a program will read files and run commands. Linux, Mac, Windows, WSL2 or a Docker container are the documented first-tier cases. It also fits if that agent should stay reachable, through Telegram, Discord, Slack or another messaging app, without shrinking into a bot that only talks.

It fits poorly if you want to paste a question into a web page and install nothing. It also fits poorly if nobody can supervise the actions, or if several people must share the same configuration folder. Two processes on the same profile write over each other. The documentation says so explicitly.

What it is

Hermes Agent is an autonomous agent published by Nous Research, as open source. It is not tied to one model. The documentation describes it as working with Nous Portal, OpenRouter, OpenAI, Anthropic, Google, or an OpenAI-compatible endpoint, including a model you host.

The difference from a chat is the tooling. The agent can call a terminal, write files, open a browser, run a scheduled task, and reuse procedures it has saved as skills. A memory can keep preferences and environment facts from one session to the next. That is not proof that what it retains is accurate, or that the question stays on the machine.

The word agent, here, does not mean a second product. A profile is the folder that keeps the configuration. The agent is the process that uses it. A subagent is a child conversation, spawned for a task, with a fresh history. It is not a second profile. Mixing the three means believing a delegated task is isolated when it still runs in the same home.

Where you meet it

The same core opens in several ways. On the command line, with hermes. In a richer terminal interface. In a desktop app for macOS, Linux and Windows. In a web dashboard, behind an access gate. In an editor, through a server for VS Code, Zed or JetBrains.

You do not have to connect all of that on day one. The documentation says to get one conversation that answers first. Messaging, voice, routing between models and scheduled tasks come after. A messaging bot needs a model provider, and often extra tools, such as speech synthesis or web search. A Nous Portal subscription is presented as one way to bundle those. It is not required.

How it is deployed

The path depends on the machine. The first-tier platforms, the ones the project says it tries not to break, are Apple Silicon Macs, Windows 10 and 11, 64-bit Linux and WSL2, and Docker on the same architectures.

On Linux, macOS or WSL2, the command-line installer is a script. On Windows, the equivalent is a PowerShell command. The desktop app is downloaded separately: a DMG on Mac, an MSIX package on Windows. The MSIX package requires Windows 11, version 22H2 or later. The graphical Hermes-Setup installer for Mac is advertised for Apple Silicon only. An Intel Mac uses another package, or the command line and then hermes desktop.

The script prepares a pinned Python, Node, npm, ripgrep and FFmpeg. It also installs, by default, a tooled browser and a computer-use driver, on macOS, Windows and glibc Linux. You can leave them out with a script option. Hermes remembers that choice: an update does not put them back by itself.

Scroll the table sideways to read every column.

1. Pick the path for the machine: script, PowerShell, desktop package, or Docker image.
2. Run hermes setup, or hermes setup --portal if you want to open Nous Portal and its tool gateway in one step.
3. Choose the provider with hermes model, then hold a conversation that answers.
4. Create a separate profile if this agent has a distinct role, for example a bot and a coding assistant.
5. Decide who may write to it, and what dangerous commands do when you are not at the screen.
6. Run hermes gateway setup only after the first conversation.

The first conversation

After installation, the step that matters is not adding features. It is a conversation that answers. hermes model chooses the provider. hermes setup opens the wizard. If you already know the provider, the documentation says to save that choice, then talk.

A local model or an endpoint you host is also set with hermes model. You then have to check the address, the model name and the context length. A second provider, as a fallback, comes after. Not before the first exchange works.

A one-shot session, hermes chat -q, has nobody waiting to approve an action. By default, a command judged dangerous is refused there. That is not the mode for learning the tool. Open it only once you understand the behavior.

One role, one folder

A profile is a separate folder, under ~/.hermes/profiles/. It has its own configuration, keys, memory, sessions, skills and gateway state. Creating a profile named coder immediately adds the coder command. coder setup and coder chat do not touch the default profile.

The documentation forbids pointing two processes at the same profile. Both write memory. At the next start, each reloads what the other wrote. The state stops being the one you configured. If two agents must share memories, the project points to an external memory provider, not to a shared folder.

A messaging bot is not a profile. It is a Telegram, Discord or Slack account, identified by a token, connected to the gateway. Desktop Bot Mode is something else again: a profile shown in a list, with an avatar. The same profile remains usable from the command line. Every desktop bot is a profile. The reverse is not true.

Leaving it reachable

The gateway is a single background process. It connects the messaging apps you configured, holds sessions, runs scheduled tasks and can deliver voice messages. It also runs a scheduler, which wakes every 60 seconds.

Not every messaging app does the same thing. Telegram, Discord, Slack, Matrix, Mattermost and Feishu are documented for voice, images, files and threads. Signal receives images and files, not a thread. SMS is text. Home Assistant, in the project’s table, sends neither voice, nor image, nor file. Connecting a platform without reading that line means discovering too late that an attachment does not leave.

Docker has two distinct uses. The agent can run inside the container. Or the agent runs on the machine, and each command goes into a Docker sandbox that survives calls, a new conversation and subagents, for the life of the process. In the first case, keys, sessions, skills and memory live in a host folder mounted at /opt/data. The image does not keep them. You replace it by pulling a new version. The container does not include the desktop app.

Who talks, and who approves

The documentation describes eight layers. The ones that change the deployment are the first. Who may write to the agent: allowlists, and pairing of private messages. What may run: a command that matches a pattern judged dangerous asks for an explicit approval, unless you have turned that control off.

The default mode is called smart. The wait for a reply is 300 seconds. Three contexts with nobody at the screen refuse, by default, the dangerous command instead of approving it: scheduled tasks, the one-shot hermes chat -q, and unattended sessions, webhooks included. Setting those three to approve means letting the agent pass the control when you are not there.

Other layers exist, and they should not be taken as a fence already built. A denylist and an optional sandbox limit file writes. Container isolation is configured. Sessions do not read each other’s state. A project file is scanned for injected instructions. None of that replaces the previous question: who can write to the bot, and does the bot have a terminal.

What leaves, and what stays

API keys go in a .env file, not in the settings file. The usual folder is ~/.hermes, or the profile folder. A profile isolates configuration, sessions, skills and memory. That separation does not replace a separate Unix account if several people share the same login session.

Each question sent to a model leaves the machine for the provider you chose, unless that provider is a local model. Nous, OpenAI, Anthropic or another host do not share one privacy policy. Hermes does not become private because it is open source. It is private to the extent that you choose the model, the network, and what you let it read.

An agent with a terminal is not a chatbot. A messaging app connected to it is not one either. Someone who writes to the bot can trigger actions, within the tools you enabled and the approvals. If the allowlist is empty, or pairing is not done, that limit does not exist yet. That setting is part of the first deployment.

What not to ask of it

The project itself ranks some platforms as second tier, or unsupported. Termux is documented only for aarch64 Android, and a phone can kill the process. AUR installs are not supported. 32-bit macOS is not supported. A Linux distribution without glibc or without systemd may work. The project does not promise it.

Docker does not update with hermes update. Neither does Nix, in its own way: Nix owns the runtime. Mixing those paths means looking for a command that does not exist on that installation.

The guardrails are not proof the agent cannot break something. They ask for approval, or they refuse in some contexts with no operator. A command that does not match the dangerous pattern goes through. A file the agent is allowed to read goes into the context sent to the model. This reading describes the paths the project publishes. It does not replace installing it on your machine, or checking what your provider keeps.

The decision

Choose Hermes Agent if you want an agent installed at home, a model you can change, and, later, a messaging app that talks to the same agent. Start with a conversation that answers. Create a profile if the role is distinct. Decide who may write, and leave dangerous commands refused when you are not there, until you have a reason to do otherwise.

Look elsewhere if you want a chat with no installation, or if you cannot take responsibility for a program that reads and executes. The linked guide is about what a generative system does with what you give it. It is not the Hermes manual. It is the frame.

• Use generative AI↗