Hermes Agent - Self-Improving AI Agent

Hermes Agent sits in the same practical category as local coding agents, chat bots, automation daemons, and model-provider routers, but it is built around a longer-lived idea: an agent that keeps state, skills, memories, scheduled work, and platform connections across sessions.

That makes it interesting for self-hosters. You can run it on a workstation, VPS, or container, connect it to a model provider, and expose it through a CLI, TUI, messaging gateway, dashboard, or OpenAI-compatible API.

Hermes Agent is the self-improving AI agent from Nous Research, with memory, skills, model routing, tools, cron, gateway integrations, and Docker deployment support.

Hermes Agent GitHub Source Code Hermes Agent Documentation License: MIT

What is Hermes Agent?

Hermes Agent is an open-source AI agent framework built by Nous Research. The current repository describes it as an agent with a built-in learning loop: it can create and refine skills, search previous sessions, use memory, schedule work, and run across different interfaces.

The repo is bigger than a terminal chat wrapper. It includes:

• a Python agent loop
• a classic CLI and newer TUI
• a messaging gateway
• a web dashboard
• an OpenAI-compatible API server
• ACP and MCP integration points
• Docker and Docker Compose support
• a skill system and plugin architecture
• cron-style scheduled agent jobs
• multiple terminal backends

The practical pitch is simple: run one agent runtime, then talk to it from the places you already use.

Repository Snapshot

I cloned the repository into:

tmp/hermes-agent

Source state:

Tech Overview of Hermes Agent

Hermes is primarily Python. The core agent loop lives around run_agent.py and agent/conversation_loop.py, while hermes_cli/ owns the command surface, setup, auth, model selection, profiles, dashboard launcher, plugin management, and update logic.

The Node side matters too. The repository includes web/ for dashboard assets and ui-tui/ for the terminal UI. The Dockerfile installs Python and Node dependencies, builds those browser/TUI assets, and runs the container under s6-overlay supervision.

The architecture docs map the main flow like this:

CLI / Gateway / ACP / API / Cron
  -> AIAgent
  -> prompt builder
  -> provider runtime
  -> model call
  -> tool dispatch
  -> session storage

Important repo areas:

What Makes Hermes Different?

The interesting part is not one single feature. It is the combination of long-running state, model routing, tools, and user-facing transports.

Hermes can run as:

• a local terminal agent
• a web dashboard backend
• a messaging bot
• a cron automation worker
• an OpenAI-compatible backend for other frontends
• an ACP-compatible editor agent

It also treats skills and memory as first-class pieces. In the checkout I inspected, there were 74 bundled SKILL.md files and 95 optional skill files.

That does not mean every deployment needs all of it. For a homelab, the useful starting point is usually smaller: pick one model provider, run one gateway, connect one interface, and add tools only after the base chat works.

Self-Hosting Hermes Agent with Docker

Hermes has two Docker-related modes:

• Run Hermes itself in Docker: persistent state lives in a mounted /opt/data directory.
• Use Docker as a terminal backend: Hermes runs on the host, but its shell tool executes commands inside a persistent Docker sandbox.

For self-hosting, the first mode is the natural fit.

Docker Compose Configuration

I added a minimal Home-Lab Compose snippet here:

The site can include the same snippet from the Home-Lab submodule:

services:
  hermes-agent:
    image: nousresearch/hermes-agent:v2026.6.5
    container_name: hermes-agent
    restart: unless-stopped
    volumes:
      - ${HERMES_DATA_DIR:-./data}:/opt/data
    ports:
      - "${HERMES_API_BIND:-127.0.0.1}:${HERMES_API_PORT:-8642}:8642"
    environment:
      HERMES_UID: ${HERMES_UID:-10000}
      HERMES_GID: ${HERMES_GID:-10000}
      API_SERVER_ENABLED: ${API_SERVER_ENABLED:-false}
      API_SERVER_KEY: ${API_SERVER_KEY:-}
      API_SERVER_HOST: ${API_SERVER_HOST:-127.0.0.1}
      API_SERVER_CORS_ORIGINS: ${API_SERVER_CORS_ORIGINS:-}
    command: ["gateway", "run"]

This compose file uses the published nousresearch/hermes-agent:v2026.6.5 image and keeps API exposure disabled by default. I pinned the public Home-Lab snippet to a versioned image tag instead of latest so the compose file is less likely to change behavior between reads.

First Run

Run the setup wizard first:

cp .env.sample .env
docker compose run --rm hermes-agent setup

Then start the gateway:

docker compose up -d

Hermes state is stored in ./data by default. That directory maps to /opt/data inside the container and contains config, secrets, sessions, skills, memory, logs, cron jobs, and profiles.

API Server Caveat

The OpenAI-compatible API server is useful, but it should not be casually exposed.

To enable it, set:

API_SERVER_ENABLED=true
API_SERVER_KEY=replace-with-a-random-secret
API_SERVER_HOST=0.0.0.0

Then put it behind an authenticated reverse proxy, VPN, SSH tunnel, or trusted network boundary.

Field Note: What I Validated Locally

This pass validated configuration and source structure, not a complete live model-backed conversation.

Local environment:

Repository compose validation succeeded:

HERMES_UID=$(id -u) HERMES_GID=$(id -g) docker compose -f tmp/hermes-agent/docker-compose.yml config

The generated Home-Lab compose also validated:

docker compose --env-file .env.sample config

The local CLI did not run cleanly in this workspace. A uv run --no-sync hermes --version attempt hit an existing ~/.local/bin/hermes shim pointing at a missing older venv. A direct PYTHONPATH=tmp/hermes-agent python3 -m hermes_cli.main --version attempt failed because the ambient Python did not have python-dotenv installed.

So the honest conclusion is: Docker Compose renders correctly, but I did not claim a successful live Hermes chat from this machine.

Building From Source

For contributors, the repo documents this path:

git clone https://github.com/NousResearch/hermes-agent.git
cd hermes-agent
./setup-hermes.sh
./hermes

Manual development setup:

curl -LsSf https://astral.sh/uv/install.sh | sh
uv venv .venv --python 3.11
source .venv/bin/activate
uv pip install -e ".[all,dev]"
scripts/run_tests.sh

This is a large project with a lot of optional integrations. If you only want to run it, start with the installer or Docker image. If you want to modify providers, tools, gateway adapters, dashboard code, or skills, use the source checkout.

When Hermes Agent Makes Sense

Hermes is a good fit when you want:

• a persistent AI agent on a VPS or workstation
• messaging access through Telegram, Discord, Slack, WhatsApp, Signal, or similar platforms
• a model-agnostic agent runtime
• memory and skill workflows
• scheduled AI tasks
• terminal/file/browser tools exposed through an agent
• an OpenAI-compatible API facade around a tool-using agent

It is probably too much if you only need a one-off local prompt runner. In that case, a smaller CLI agent or a direct model API script is easier to reason about.

Hermes belongs after NanoClaw and OpenClaw in the reading order. NanoClaw emphasizes small container-isolated assistant sessions. OpenClaw emphasizes the local-first Gateway. Hermes emphasizes a larger persistent agent runtime with memory, skills, cron, gateways, and API surfaces.

Conclusion

Hermes Agent is one of the more ambitious open-source agent runtimes I have inspected recently. It combines CLI, TUI, dashboard, gateway, API server, skills, memory, plugins, profiles, cron, and multiple execution backends into a single project.

For self-hosters, the cleanest first deployment is the Docker gateway with a persistent data directory and one configured model provider. Once that works, add a messaging platform, dashboard, API server, or Docker terminal backend one at a time.

FAQ