Installing Hermes Agent and Understanding Its Architecture

Hermes is more than a chatbot in the terminal

Hermes Agent is an agent that can use tools, retain context across sessions, receive messages from several platforms, and run scheduled work.

The important distinction is the word agent. Hermes does not only generate text. It can read files, execute commands, search the web, call MCP servers, delegate work, and continue tasks based on persisted state.

This article covers a fresh installation, then explains the parts worth understanding before making Hermes part of a daily workflow.

1. Install the command line application

The official project provides installers for Linux, macOS, WSL2, and Termux. The fastest path is:

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

The installer prepares the Python environment, launcher, and required dependencies. When it finishes, check the version and run the health check:

hermes --version
hermes doctor

For native Windows, use the PowerShell installer provided by the project:

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

The Python package is another option:

pip install hermes-agent

On systems using PEP 668, use a virtual environment or uv so the system Python remains untouched:

uv venv
source .venv/bin/activate
uv pip install hermes-agent

Hermes also has a desktop app for Windows and macOS. Desktop is useful for a visual interface, while the command line is easier to use on servers, over SSH, and inside automation.

2. Configure a model and provider

After the binary is available, run the setup wizard:

hermes setup

The wizard can help choose a model, provider, terminal backend, tools, and agent settings.

For the Nous Portal OAuth path:

hermes setup --portal

To select a provider or model interactively:

hermes model

To inspect the active configuration:

hermes config
hermes config path
hermes config check

Hermes separates configuration from credentials. Settings live in config.yaml, while API keys and OAuth credentials belong in environment files or the credential store. Do not put secrets in a project repository.

Common settings can be changed with commands such as:

hermes config set agent.max_turns 90
hermes config set terminal.cwd /home/user/projects
hermes config set security.redact_secrets true
hermes config set approvals.mode smart

Providers can use API keys, OAuth, or an OpenAI-compatible endpoint. Credential pools can hold several credentials for one provider and rotate when one credential is exhausted.

3. Understand profiles

A profile is an independent Hermes instance with its own configuration, sessions, memory, skills, and state. Profiles are useful when one machine hosts several roles that should not share context.

Create a profile:

hermes profile create personal
hermes profile list
hermes profile show personal

Run Hermes with that profile:

hermes --profile personal

You can also create a profile shortcut:

hermes profile alias personal

Conceptually, a profile layout looks like this:

$HERMES_HOME/
├── config.yaml
├── .env
├── auth.json
├── state.db
├── sessions/
├── logs/
├── skills/
└── profiles/
    └── personal/
        ├── config.yaml
        ├── .env
        ├── state.db
        ├── sessions/
        ├── logs/
        └── skills/

A profile is not another name for a session. A session is one conversation. A profile is a larger operational boundary.

I use a personal profile for my personal workflow. It has a separate identity, preferences, Telegram gateway, skill routers, and scheduler from any other profile.

4. CLI and conversation interface

Without a subcommand, Hermes opens an interactive chat:

hermes

For a one-shot query:

hermes chat -q "Check this repository and explain its blockers"

Useful flags include:

hermes --continue
hermes --resume SESSION_ID
hermes --profile personal
hermes --skills project-coding-workflow
hermes --worktree

Inside an interactive session, commands start with /:

/help             list commands
/new              start a fresh session
/title name       name the session
/model            inspect or change the model
/skills           search or install a skill
/tools            manage toolsets
/cron             manage schedules
/agents           inspect background work
/stop             stop background processes
/resume           resume a session

Tool and skill changes normally apply to a new session. In the gateway, configuration changes usually require /restart.

5. Tools, toolsets, and skills

A tool is a concrete ability, such as reading files, executing a terminal command, browsing the web, or sending a message. A toolset is a group of tools that can be enabled or disabled together.

Inspect available tools:

hermes tools list
hermes tools

Common toolsets include:

terminal for shell and process management.
file for reading, writing, searching, and patching.
web for search and content extraction.
browser for browser automation.
code_execution for a Python sandbox.
memory for cross-session memory.
delegation for subagents.
cronjob for schedules.
kanban for multi-agent work queues.

A skill is different from a tool. A tool provides an ability. A skill provides procedure, rules, and context for when that ability should be used.

hermes skills list
hermes skills search python
hermes skills install SKILL_ID
hermes skills inspect SKILL_ID
hermes skills check

I use two kinds of skills:

General skills that work across projects.
Repository-owned skills that explain how to use a particular project or workflow.

For repository-owned skills, Hermes can load an external directory through configuration:

skills:
  external_dirs:
    - /home/user/project/agent/skills

The skill can then be reviewed and versioned with the code. Business logic stays in the application repository instead of hiding inside a prompt.

6. Project context and repository rules

Hermes reads context files based on the working directory. These files enter the system prompt so the agent understands project rules before editing code.

The important discovery order is:

.hermes.md / HERMES.md
AGENTS.md / agents.md
CLAUDE.md / claude.md
.cursorrules / .cursor/rules/*.mdc

.hermes.md can be inherited from a parent directory up to the git root. AGENTS.md is read from the current working directory only, making it suitable for explicit and portable rules.

A small .hermes.md might look like this:

# Project rules

- Use uv for Python dependencies.
- Run tests before declaring work complete.
- Do not touch credential files.
- Implement changes as vertical slices.

A context file is not a replacement for tests. It reduces assumptions, while the project still has to validate the result.

7. Gateway and messaging platforms

The gateway runs Hermes as a service that receives messages from platforms such as Telegram, Discord, Slack, WhatsApp, email, and other supported adapters.

The main commands are:

hermes gateway setup
hermes gateway run
hermes gateway install
hermes gateway start
hermes gateway status
hermes gateway restart
hermes gateway stop

On a Linux server, a user service may need to survive an SSH logout. If the deployment requires it, enable user lingering:

loginctl enable-linger "$USER"

The gateway is not a separate agent. It is an ingress and delivery surface for the same profile. Telegram sessions, CLI sessions, and other platform sessions still have their own routing and state.

Before allowing a bot to receive private messages, configure pairing or authorization. A user who can send a message to a bot should not automatically be allowed to run every tool.

8. Schedules and cron jobs

Hermes has a durable scheduler for work that should run without a manual prompt.

Create a schedule:

hermes cron create "0 9 * * *"

Duration syntax is also supported:

hermes cron create "30m"
hermes cron create "every 2h"

Operational commands include:

hermes cron list
hermes cron status
hermes cron edit JOB_ID
hermes cron run JOB_ID
hermes cron pause JOB_ID
hermes cron resume JOB_ID
hermes cron remove JOB_ID

A job can have its own prompt, model, provider, skills, delivery route, pre-run data collection script, and working directory.

For production workflows, Hermes cron entries can stay thin and call an application command with its own contract:

Hermes scheduler
      → scheduled prompt or script
      → application command
      → persisted result
      → optional delivery

Business logic therefore does not need to be rewritten inside cron prompts. It stays in an application script or repository that can be tested and reviewed.

A job can use a pre-run script to collect data. Another job can consume the latest output through chaining. Script-only work can run without an agent loop.

9. Kanban as a multi-agent work queue

Hermes Kanban is a durable SQLite board for assigning work to different profiles or workers.

Initialize a board:

hermes kanban init

Create and inspect tasks:

hermes kanban create "Add a health check endpoint"
hermes kanban list
hermes kanban show TASK_ID

Common operations include:

hermes kanban assign TASK_ID PROFILE
hermes kanban comment TASK_ID "Additional context"
hermes kanban link TASK_ID OTHER_TASK_ID
hermes kanban block TASK_ID "Waiting for schema"
hermes kanban unblock TASK_ID
hermes kanban complete TASK_ID
hermes kanban tail

A dispatcher can promote ready tasks, claim them atomically, start the assigned profile, and reclaim stale claims.

The board is the hard boundary for workers. A tenant can separate project paths and memory keys within the same board.

Kanban is useful for long-running work that needs state across processes. For a small task that should finish in a few minutes, delegation is usually simpler.

10. Delegation and worktrees

There are two ways to run additional agents.

delegate_task fits short subtasks with isolated context. An independent Hermes process fits interactive or long-running work.

One-shot process:

hermes chat -q "Inspect the test suite and write a summary to /tmp/test-report.md"

For an interactive session, use tmux so prompt input has a real PTY:

tmux new-session -d -s hermes-agent 'hermes'
tmux send-keys -t hermes-agent 'Inspect this repository' Enter
tmux capture-pane -t hermes-agent -p

When several agents edit code in parallel, use a worktree:

hermes --worktree

A worktree keeps each agent's changes separate from the main branch. Review, test, and clean up after the agent finishes.

11. Memory, sessions, and curator

Memory stores facts that are useful across sessions, such as user preferences, environment details, or stable procedures.

Memory commands include:

hermes memory setup
hermes memory status
hermes memory off

Sessions can be listed and exported:

hermes sessions list
hermes sessions browse
hermes sessions export output.jsonl
hermes sessions stats

Hermes also has a curator for the lifecycle of skills created by agents. It can mark idle skills, create backups, archive old skills, and consolidate skills when that option is enabled.

hermes curator status
hermes curator run
hermes curator pin SKILL_NAME
hermes curator archive SKILL_NAME
hermes curator backup

I keep memory separate from code repositories. Memory holds personal and operational context, while repositories hold implementation and rules that need review.

12. MCP and plugins

MCP servers add tools from another process or service to Hermes.

hermes mcp add NAME --command "python server.py"
hermes mcp list
hermes mcp test NAME
hermes mcp configure NAME
hermes mcp remove NAME

Plugins can add platforms, commands, or integrations without changing the core directly:

hermes plugins list
hermes plugins install NAME
hermes plugins remove NAME

Use MCP and plugins for clear integration boundaries. Do not put credentials in command arguments or commit configuration files containing secrets.

13. Hermes internal architecture

At a high level, the Hermes loop looks like this:

Merender diagram...

The important components are:

The profile provides configuration and state boundaries.
A session stores one conversation.
The prompt builder combines identity, rules, memory, skills, tools, and environment.
The model router calls the selected provider.
The tool registry exposes available schemas and handlers.
The approval layer evaluates risky commands.
The session store keeps transcripts and metadata.
Compression keeps the conversation within the context window.
The gateway translates platform messages into Hermes input and output.
The scheduler and webhook layer start runs without manual conversation.

Hermes should not rebuild the prompt and tool schema casually in the middle of a session. Tool or configuration changes generally require a new session so prompt caching and the message contract remain stable.

14. Important security boundaries

An agent with a terminal is not only a text generator. It can affect files and systems. These settings are worth checking:

hermes config set security.redact_secrets true
hermes config set approvals.mode smart

Secret redaction keeps values that resemble keys or tokens out of tool output and transcripts. Approval mode helps assess destructive or suspicious commands.

--yolo exists for controlled experiments, but should not be the default:

hermes --yolo

Keep these categories separate:

Hermes credentials, such as API keys and OAuth tokens.
Project credentials, such as database passwords and deployment secrets.
Runtime data, such as sessions, logs, state databases, and private routes.

Each category needs an appropriate location, strict permissions, and protection from Git.

15. My setup checklist

After installation, I check these in order:

hermes doctor
hermes config check
hermes tools list
hermes skills list
hermes profile list
hermes gateway status
hermes cron status
hermes sessions stats

Then I run one read-only conversation, one local tool test, and one schedule test that does not send sensitive data.

Before enabling a production gateway:

use a dedicated profile;
restrict users through pairing or authorization;
enable secret redaction;
use a safe approval mode;
separate credentials from repositories;
inspect gateway logs;
confirm that delivery routes point to the intended private chat;
prepare restart and rollback procedures.

Closing thoughts

Hermes is easier to understand as several layers rather than one large chatbot. There is a profile for boundaries, a session for conversation, a skill for procedure, a toolset for abilities, a gateway for platforms, cron for schedules, Kanban for coordination, and memory for cross-session context.

Installation is only the first step. The value appears when each layer has a clear responsibility.

For me, the healthiest architecture is:

Hermes understands the goal.
A skill translates the procedure.
The CLI provides a contract.
A tool executes the operation.
State and verification prove the result.

Official documentation:

Find something