Skip to content
NLEN
← Apps overview

Hermes Agent: technical tutorial

By Ivo Donker · — created with AI assistance (writer: DeepSeek V4.1 Flash; critic: Gemini 3.8 Flash)

Hermes Agent: ReviewInstall & set upNews

Status September 2026, compiled from our own notes and news archive; text machine-generated and editorially checked. Check versions and commands in the official documentation.

This tutorial sets up Hermes Agent as a serious, long-running agent: models and a cheap auxiliary model, a sandboxed terminal backend, MCP servers, skills, scheduled tasks and the messaging gateway, along with the security that goes with it. Keys and commands have been checked against the official documentation from Nous Research (as of September 2026).

Configuration: config.yaml and .env

Everything is in ~/.hermes/. The starting point: secrets in .env, everything else in config.yaml. In config.yaml you refer to a secret with ${NAAM}.

Useful commands:

hermes config set KEY VAL    # waarde zetten (HOOFDLETTERS gaan automatisch naar .env)
hermes config get KEY        # de uiteindelijke waarde bekijken
hermes config edit           # config.yaml openen in je editor
hermes config check          # configuratie controleren, vooral na een update

Models: main model and auxiliary model

Hermes uses a main model for the real work and can use a separate, cheaper model for side tasks, such as summarising long contexts (compression):

model: anthropic/<model-id>
providers:
  anthropic:
    api_key: ${ANTHROPIC_API_KEY}

auxiliary:
  compression:
    model: <goedkoop-model>
    provider: openrouter

Do you want all traffic to run through your own OpenAI-compatible endpoint, such as a local server or your own LLM router? Then specify a base_url, as the documentation for the auxiliary models shows:

auxiliary:
  compression:
    model: <alias-bij-je-router>
    base_url: https://router.example.com/v1

hermes model lets you interactively choose a provider and model and writes the configuration for you. That is less error-prone than doing it by hand.

The terminal backend: where commands run

By default, Hermes runs shell commands on your own machine (local). For an agent that does a lot independently, a sandboxed environment is wiser. The available backends:

A Docker setup in which only your project directory is visible:

terminal:
  backend: docker
  docker_image: nousresearch/hermes-sandbox:desktop
  docker_volumes:
    - "/home/jij/projects:/workspace/projects"
  container_memory: 5120        # MB
  container_persistent: true    # container blijft bestaan tussen sessies

Mount only the directories that the agent really needs. A volume on your home directory makes the sandbox pointless.

Security and approval

agent:
  dangerous_command_approval: true   # risicovolle shellcommando's eerst voorleggen
  disabled_toolsets:                 # hele groepen tools uitschakelen
    - web
skills:
  write_approval: true               # wijzigingen aan skills eerst goedkeuren
  guard_agent_created: true          # zelfgemaakte skills scannen op gevaarlijke patronen
memory:
  write_approval: false              # op true: elke geheugenupdate eerst goedkeuren

With disabled_toolsets you remove entire categories. An agent that only needs to read and write code, for example, does not need web access.

MCP servers

In config.yaml under mcp_servers. A local server (stdio):

mcp_servers:
  github:
    command: "npx"
    args: ["-y", "@modelcontextprotocol/server-github"]
    env:
      GITHUB_PERSONAL_ACCESS_TOKEN: "${GITHUB_TOKEN}"

A remote server (HTTP):

mcp_servers:
  docs:
    url: "https://mcp.example.com/mcp"
    headers:
      Authorization: "Bearer ${DOCS_TOKEN}"

Stdio is suitable for servers running locally; HTTP for servers hosted elsewhere.

Skills: procedural memory

Skills are in ~/.hermes/skills/, each in its own directory with a SKILL.md. They follow the open standard from agentskills.io, so you can also use them in other agents. A minimal skill:

---
name: release-notes
description: Schrijf release notes uit git-log
version: 1.0.0
platforms: [macos, linux]
---
## When to Use
Als er om release notes voor een nieuwe versie wordt gevraagd.

## Procedure
1. Lees `git log` sinds de laatste tag.
2. Groepeer per type: features, fixes, overig.
3. Schrijf beknopte Nederlandse zinnen per wijziging.

## Pitfalls
- Merge-commits niet dubbel opnemen.

## Verification
- Elke genoemde wijziging staat in de git-log.

Scheduled tasks

Hermes has a built-in planner. You create tasks in three ways:

The definitions are in ~/.hermes/cron/jobs.json, the output per run in ~/.hermes/cron/output/<job_id>/. With deliver: you determine where the result goes: back to where the task was created, only to local files, or to a chat channel.

The messaging gateway

The gateway makes your agent reachable via Telegram, Discord, Slack, WhatsApp, Signal, Matrix, Teams and more.

hermes gateway setup     # interactief platforms instellen
hermes gateway install   # als dienst installeren (systemd op Linux, launchd op macOS)
hermes gateway start

By default, the gateway refuses everyone except:

Never set GATEWAY_ALLOW_ALL_USERS=true on a bot with access to a terminal: then anyone who finds the bot can execute commands.

Maintenance

Troubleshooting

Documentation: hermes-agent.nousresearch.com/docs.