Hermes Agent

• 1: Getting Started with Hermes Agent
• 2: Hermes Agent Architecture
• 3: Skills, Memory, and Context in Hermes
• 4: Hermes as a GitOps SRE Assistant

1 - Getting Started with Hermes Agent

Hermes Agent is an AI agent runtime for doing real work from the terminal, Discord, and other messaging platforms. It can call tools, read and write files, run commands, search the web, use MCP servers, remember durable preferences, and load reusable skills when a task needs a known workflow.

That makes it more than a chatbot. It is closer to an operator shell with an LLM attached. Useful, sharp, and worth treating with the same respect you give kubectl, talosctl, or a production database prompt.

Where Hermes Fits

Hermes is the day-to-day operational assistant in my agent stack.

OpenClaw is still useful as an orchestration and experimentation lineage. Hermes is where I put the repeatable operator workflow: investigate, plan, edit the source of truth, validate, and document the result.

Install Hermes

For macOS and Windows, start with the official Hermes Agent Desktop installer. The Desktop installer is the recommended path when you want both the local app and the command-line runtime.

The full Hermes Agent installation guide also covers command-line-only installs for Linux, macOS, WSL2, and Android/Termux.

curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash

After installation:

hermes setup
hermes doctor
hermes

hermes setup configures providers, tools, terminal behavior, memory, and messaging integrations. hermes doctor checks whether the runtime is healthy.

First Safe Tasks

Start with low-risk, read-only work:

Summarize this repository's README and identify the build command.

Check the current git status and tell me whether the working tree is clean.

Search my notes for prior decisions about Hermes profiles.

Then move to bounded edits:

Create a draft Markdown outline for a Hermes runbook. Do not modify existing files.

Patch this one documentation file to add the new validation step, then show the diff.

Avoid starting with broad mutation requests like “fix my cluster” or “clean up this repo.” That is how Old World server folklore gets automated at machine speed. Give Hermes scope, constraints, and an acceptance test.

Basic Commands

# Start an interactive session
hermes

# Ask one question and exit
hermes chat -q "What changed in this git diff?"

# Pick or change the model/provider
hermes model

# Check runtime health
hermes doctor

# List configured tools
hermes tools list

# Resume recent work
hermes --continue

Hermes also supports named profiles, skill preloading, cron jobs, webhooks, MCP servers, and gateway platforms. Treat those as power tools, not first-day requirements.

Safety Model

Hermes is most valuable when it can use real tools. That also means the safety model matters.

• Prefer read-only discovery before mutation.
• Keep secrets in environment variables, 1Password, or SOPS-encrypted files.
• Do not paste API keys into chat.
• Use source control as the change boundary.
• Ask for diffs before applying risky edits.
• Validate with real commands, not vibes.

In my homelab, the rule is simple: Forgejo is the source of truth. Hermes can help edit and validate it, but runtime state is not the truth just because a container happens to be running.

Next Steps

• Read Hermes Agent Architecture to understand the moving parts.
• Read Skills, Memory, and Context in Hermes before storing knowledge in the wrong layer.
• Read Hermes as a GitOps SRE Assistant for the operational workflow I use in the homelab.

2 - Hermes Agent Architecture

Hermes Agent is easiest to understand as a runtime made of layers. The model is important, but it is only one layer. The useful behavior comes from the way the model is wrapped with tools, skills, memory, profiles, and gateway adapters.

graph TD
    User[User] --> CLI[CLI]
    User --> Desktop[Desktop App]
    User --> Gateway[Discord / Telegram / Slack Gateway]
    CLI --> Agent[Hermes Agent Loop]
    Desktop --> Agent
    Gateway --> Agent
    Agent --> Model[LLM Provider]
    Agent --> Tools[Toolsets]
    Agent --> Skills[Skills]
    Agent --> Memory[Memory]
    Agent --> MCP[MCP Servers]
    Agent --> Sessions[Session Store]
    Tools --> System[Filesystem / Terminal / Browser / APIs]
    MCP --> Services[External and Local Services]

Agent Loop

At the center is the agent loop:

1. Build context from the system prompt, user request, active skills, memory, and available tools.
2. Ask the model what to do next.
3. If the model calls a tool, execute the tool and feed the result back in.
4. Repeat until the task is complete or the turn budget is exhausted.

This loop is what turns Hermes from a text generator into an operator. It can inspect the environment, make targeted edits, run validations, and report the actual result.

Model and Provider Layer

Hermes is provider-agnostic. It can use OpenRouter, Anthropic, OpenAI-compatible endpoints, local models, and other supported providers. That matters because agent workloads are not all the same.

• Fast routing models are useful for simple questions.
• Strong reasoning models are useful for planning and debugging.
• Local models are useful for privacy-sensitive or offline workflows.
• Auxiliary models can handle tasks like vision, summarization, or compression.

The practical rule: choose the cheapest model that can safely complete the task, but do not under-power infrastructure decisions just to save fractions of a cent.

Toolsets

Toolsets are the capability boundary. A Hermes session may have access to files, terminal commands, browser automation, web search, GitHub, Home Assistant, cron jobs, image generation, or other integrations.

Tool access should match the job. A writing assistant does not need terminal access. An SRE assistant probably does. A public gateway profile should be more constrained than a local CLI profile.

Skills

Skills are procedural memory. They are Markdown documents with instructions, commands, pitfalls, and validation steps for recurring tasks.

A good skill answers: “When this task appears again, what exact workflow should Hermes follow?”

Examples:

• Deploying a Komodo-managed Docker Compose stack.
• Publishing a guide to a Hugo/GitHub Pages site.
• Reindexing the Obsidian search service.
• Running a Kubernetes migration assessment.

Skills prevent rediscovering the same footguns every week, which is nice because there are only so many times a person should have to learn that a service is GitHub Pages-backed and not Netlify-backed.

Memory

Memory is for stable facts: preferences, environment conventions, durable lessons, and recurring constraints. It is not a task log and it is not where secrets belong.

Bad memory:

Fixed PR #123 today.

Good memory:

The guides site is hosted by GitHub Pages and mirrored into the Obsidian vault.

For project notes, runbooks, incident records, and plans, use Obsidian. For code and manifests, use Git. For procedures, use skills.

Profiles

Profiles let multiple Hermes instances have different configuration, tools, skills, and memory scopes. This is useful for separating roles:

• default operator profile
• coding-focused profile
• read-only reviewer profile
• WordPress/operator profile
• automation or cron-focused profile

Profiles are how you stop one all-powerful assistant from becoming a junk drawer with root-adjacent ambitions.

Desktop and Gateway

The Hermes Agent Desktop app gives Windows and macOS users a local chat-first interface. The gateway lets Hermes run through messaging platforms like Discord, Telegram, Slack, and others. In my setup, Discord is the conversational control plane for homelab operations.

Gateway mode is powerful because it puts operational workflows where the work is being discussed. It also increases the need for clear approval boundaries, careful tool exposure, and concise status updates.

MCP Servers

MCP servers expose external systems as typed tools. Instead of scraping dashboards or asking Hermes to invent API calls, MCP gives it structured access to known capabilities.

In a homelab, useful MCP integrations include:

• inventory and dependency data
• Git hosting
• note search
• infrastructure APIs
• monitoring systems

MCP is not magic. It is an integration boundary. Treat each server like an API client with permissions, credentials, and operational blast radius.

The Operating Boundary

The architecture is only useful if the boundary is clear:

• Documentation lives in Obsidian or the public guides repo.
• Infrastructure source lives in Forgejo or GitHub, depending on the repo.
• Runtime state is evidence, not source of truth.
• Secrets live in 1Password, environment files, or SOPS-encrypted manifests.
• Hermes investigates, edits, validates, and documents within those rules.

That is the difference between an agent and an enthusiastic shell history generator.

3 - Skills, Memory, and Context in Hermes

Hermes has several ways to remember things. They are not interchangeable. Putting the right information in the right layer is what keeps an agent useful instead of turning it into a haunted clipboard.

The Layers

The mistake is treating all of these as “memory.” They are different systems with different jobs.

Current Context

Current context is what Hermes can see in the active turn. It includes the conversation, loaded skills, tool outputs, and selected memories. It is fast and useful, but not durable.

If a decision matters after the session ends, write it somewhere durable:

• Obsidian for operational notes.
• Git for code and manifests.
• Skills for reusable procedures.
• Memory for stable facts and preferences.

Session Search

Session search is for archaeology. It answers questions like:

What did we decide about Hermes profiles last week?

Find the session where we debugged the Obsidian search container.

It is useful evidence, not a source of truth. Once a decision is recovered, it should be written into the appropriate note or repo.

Durable Memory

Hermes memory should be compact and stable. Good memory saves you from repeating yourself.

Good examples:

• The guides site is GitHub Pages-backed.
• The Obsidian vault path is /home/derekleeds/obsidian/derekleedscloud.
• The user prefers concise, validation-backed answers.

Bad examples:

• A commit hash from a task that will be stale next week.
• A temporary bug status.
• A pasted API key.
• A full runbook.

Memory is a scalpel. If it becomes a junk drawer, every future answer gets a little worse.

Skills

Skills are reusable operating procedures. A skill should include:

1. When to use it.
2. Exact commands or tool sequence.
3. Safety checks.
4. Common pitfalls.
5. Verification steps.

Skills are ideal for repeated workflows:

• publishing a guide
• deploying a Komodo stack
• checking a Kubernetes incident
• evaluating a new homelab tool
• safely using a specific API

When Hermes solves a tricky workflow, the durable lesson should usually become a skill. That is how the agent gets better without stuffing every detail into the base prompt.

Obsidian

Obsidian is the written operational record. Use it for:

• project plans
• incident reports
• architecture decision records
• runbooks
• investigation notes
• guide mirrors

In my setup, guide posts are mirrored under:

2_Areas/AI_LLM_Work/Guides Posts/

That mirror is not a replacement for the published site. It is a local knowledge copy tied into the rest of the vault.

Git

Git is the source of truth for things that execute or publish:

• Hugo guide source
• infrastructure manifests
• Helm charts
• Docker Compose stacks
• config templates
• CI workflows

If a change affects runtime or publication, it belongs in Git. Obsidian can link to it, explain it, and preserve the rationale, but the executable artifact lives in the repository.

A Simple Decision Tree

Ask this before saving anything:

1. Is it a secret? Put it in 1Password, an env file, or SOPS. Not chat. Not memory. Not docs.
2. Is it code or config? Put it in Git.
3. Is it a project decision or runbook? Put it in Obsidian.
4. Is it a reusable procedure? Put it in a skill.
5. Is it a stable preference or environment fact? Put it in memory.
6. Is it temporary task progress? Leave it in the session or task note.

This keeps Hermes useful across long-running work without turning every session into a landfill of stale facts.

4 - Hermes as a GitOps SRE Assistant

Hermes is most useful when it acts like an SRE assistant, not a magic production button. The workflow is simple: investigate, plan, change the source of truth, validate the result, and document what happened.

That order matters.

Operating Principles

My homelab has a few rules for Hermes-driven work:

• Forgejo is the source of truth for private infrastructure state.
• GitHub is the source of truth for public guides like this site.
• Komodo manages Docker Compose infrastructure and management-plane stacks.
• ArgoCD manages Kubernetes application workloads.
• Talos nodes are immutable. No SSH archaeology, no hand-edited snowflakes.
• Secrets stay out of chat and docs. Use 1Password, environment references, or SOPS-encrypted files.
• Documentation is part of the task. If it is not documented, it did not happen.

Hermes can help with every part of that flow, but it does not get to invent a new source of truth because it found a convenient command.

The Standard Workflow

flowchart TD
    A[User request] --> B[Read-only discovery]
    B --> C[Plan of Action]
    C --> D[Edit source of truth]
    D --> E[Run targeted validation]
    E --> F[Deploy or publish]
    F --> G[Verify live behavior]
    G --> H[Document outcome]

1. Read-Only Discovery

Start by inspecting what exists:

• current Git status
• relevant repo files
• prior Obsidian notes
• existing skills
• live state from safe read-only APIs
• recent logs, if needed

This prevents solving a different problem than the one actually present. Infrastructure has enough legacy debt without adding agent-generated fan fiction.

2. Plan of Action

For migrations, incidents, and risky changes, Hermes should draft a plan before editing anything. The plan should include:

• scope
• assumptions
• risks
• rollback path
• acceptance criteria
• validation commands

For simple documentation edits, this can be lightweight. For cluster work, it is the difference between engineering and poking the bear with YAML.

3. Edit the Source of Truth

Hermes should prefer declarative changes:

Live commands are for discovery, validation, and controlled operations. They are not a substitute for tracked state.

4. Validate

Validation should match the risk:

• format check for Markdown
• Hugo build for guide changes
• helm template or chart lint for Kubernetes changes
• targeted tests for code changes
• API read-back for external systems
• live endpoint checks after deployment

Hermes should report what actually ran and what it returned. “Looks good” is not a validation strategy; it is a sentence people write before opening an incident.

5. Document

For public guides, mirror the content into Obsidian. For infrastructure changes, update the relevant project plan, runbook, or architecture decision record.

The written record should include:

• what changed
• why it changed
• where the source artifact lives
• how it was validated
• what risk remains

Example: Publishing a Guide

A safe Hermes publishing request looks like this:

Create a Hermes Agent guide section in the guides repo. Mirror the posts into Obsidian, run the Hugo production build, and report the changed files. Do not push until validation passes.

Hermes should then:

1. Check the existing guide style.
2. Create or edit Markdown in content/en/docs/....
3. Mirror the article into the vault.
4. Update indexes.
5. Run formatting/build checks.
6. Show the diff and validation result.

That is an agent workflow with a paper trail.

Example: Kubernetes Application Change

For Kubernetes, Hermes should prefer a Helm/ArgoCD path:

1. Inspect the existing chart and ArgoCD application layout.
2. Update chart values or templates.
3. Render with helm template.
4. Run static checks where available.
5. Commit the change.
6. Let ArgoCD reconcile.
7. Verify the application health and endpoint behavior.

It should not SSH into a node and hand-edit files. Talos would not allow that anyway, because Talos has self-respect.

Example: Komodo Stack Change

For a Docker Compose stack managed by Komodo:

1. Find the repo-backed stack definition.
2. Update docker-compose.yml, .env.example, or stack.toml as needed.
3. Avoid plaintext secrets.
4. Validate the Compose file.
5. Commit the change.
6. Trigger or observe Komodo reconciliation.
7. Verify the service from the outside.

Runtime fixes without Git changes are treated as temporary incident response, not as completion.

The Human Approval Boundary

Hermes can do a lot, but approval still matters. I want explicit confirmation before:

• destructive file operations
• network topology changes
• DNS or exposure changes
• credential rotation
• deleting data
• modifying production cluster state

The goal is not to slow everything down. The goal is to keep the agent on the right side of the blast-radius line.

The Practical Benefit

The benefit is not that Hermes makes infrastructure effortless. It makes the boring discipline easier to repeat:

• read before writing
• write the source of truth
• validate the result
• document the outcome
• preserve the lesson as a skill when useful

That is the useful version of AI operations: less ritual, more reproducibility.