Hermes Agent

Hermes Agent is an open-source, terminal-first AI agent from Nous Research. It runs locally as a CLI, can be reached through messaging platforms (Telegram, Discord, Slack), and is unusual in how provider-agnostic it is: the documentation lists dozens of providers, including local endpoints such as Ollama, LM Studio, vLLM, and any OpenAI-compatible server.

Owners Club recommendation: run Hermes Agent in a container. The project ships a community devcontainer (https://github.com/wiki3-ai/hermes-devcontainer) that starts it inside a dev container with a persisted data volume and a dashboard.

At a glance

Why it is on our list

• MIT licensed and genuinely portable — one installer command on Linux/macOS/WSL2, PowerShell on Windows.
• It can be fully local. Point it at Unsloth Desktop, Jan, Ollama, or vLLM and nothing leaves your machine.
• Provider breadth without lock-in: hermes model switches providers at any time.
• It has a containment story. The devcontainer variant keeps the agent inside a container rather than loose on your host.

Install and first run

Desktop installer (macOS/Windows) or CLI:

# Linux / macOS / WSL2
curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash

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

Then reload your shell and run the setup wizard:

hermes setup

Recommended: run it in the container

Open https://github.com/wiki3-ai/hermes-devcontainer in a dev container (VS Code, Codespaces, Podman Desktop, or Docker Desktop). Per that repository's README:

• It builds from nousresearch/hermes-agent:latest and starts Hermes with gateway run.
• Persistent data lives in a named volume mounted at /opt/data.
• The dashboard is enabled on port 9119 (default basic auth hermes / hermes-devcontainer — change this).
• Port 8642 is the Hermes API. The root URL returns 404 by design; use /health or /v1/....
• Host services are reachable at host.docker.internal (Docker/Codespaces) or host.containers.internal (Podman Desktop).

Configuration worth knowing

• Secrets vs settings. ~/.hermes/.env holds secrets and tokens; ~/.hermes/config.yaml holds non-secret settings. They are deliberately separate files.
• Context is a hard requirement. Local models must be started with at least a 64K context (--ctx-size 65536 in llama.cpp, -c 65536 in Ollama) or Hermes refuses the model.
• Setup modes. Quick Setup uses Nous Portal OAuth; Full Setup lets you bring your own keys; Blank Slate starts with only the minimal toolset enabled.
• Gateway after chat. Get one clean conversation working before adding Telegram/Discord or cron; the docs say this explicitly and they are right.

Common pitfalls

• Undersized context window. The most common local-model failure: a model loads, then Hermes rejects it for having fewer than 64K tokens of context.
• Adding features before the base chat works. Messaging gateways and skills multiply the number of moving parts; debug the chat path first.
• Default devcontainer dashboard credentials. hermes / hermes-devcontainer is a known default and must be changed before the port is exposed anywhere.
• Port 8642 looks broken. Hitting / on the API port returns 404 by design. Use a real endpoint.
• Host networking confusion — the same host.docker.internal vs 127.0.0.1 trap described in Agent Zero.

Tips and tricks

• Start with hermes model against a local Unsloth/Ollama endpoint and a 64K context. Prove the loop with zero cloud keys, then add providers.
• Treat the container as the deployment unit: it makes "works on my machine" the same as "works on the demo machine".
• Keep ~/.hermes/.env or the container volume out of any repository you push.

Videos

Verified via YouTube oEmbed on 2026-10-28. Note these are third-party tutorials; several are sponsored VPS walkthroughs, so prefer the official quickstart for exact commands.

• The Ultimate Beginner's Guide to Hermes Agent — Metics Media.
• Hermes Agent FULLY LOCAL AI Setup Guide — Digital Spaceport.
• Hermes Agent Full Tutorial for Beginners | Setup Guide — Tech With Tim.
• Run Your AI Coding Agent in Dev Containers — Complete Beginner's Guide — Visual Studio Code.

Related

• Hermes devcontainer — the containment path we recommend.
• Agent Zero — the other agent we recommend, contained by default.
• Unsloth Desktop — a local endpoint Hermes can use.
• Agent containment — why containers for agents.

Verification note: install commands, provider list, the 64K context minimum, and the .env/config.yaml split were read from the official quickstart on 2026-10-28. Container ports, volumes, and default credentials were read from the community devcontainer README.