Hermes Agent is an open-source autonomous AI agent built by Nous Research — the lab behind the Hermes family of models. Unlike static chatbots, Hermes has a closed learning loop: it writes and refines its own skill files from experience, recalls past sessions via full-text search, and builds a persistent memory of your workflows. It crossed 100K GitHub stars faster than AutoGPT or LangChain.

Your Mac Mini M4 with 28 GB of unified RAM is an ideal host. The Neural Engine and high memory bandwidth can run capable local models (up to 14B+ parameters) while the machine stays quiet and energy-efficient around the clock.

Before You Begin

Make sure the following are in place on your Mac Mini:

1. macOS Sequoia (15.x) — fully updated via System Settings → General → Software Update.

2. Xcode Command Line Tools — needed for Git and build dependencies. Run xcode-select --install in Terminal if not already installed.

3. Homebrew — macOS package manager. Install from brew.sh or run the one-liner on their site.

4. Ollama (for local models) — download from ollama.com and open the app once to start the background service.

5. Docker Desktop (optional, for the web dashboard) — download from docker.com/products/docker-desktop.

Hermes ships a single installer script that handles everything automatically: Python 3.11, Node.js 22, ripgrep, ffmpeg, a virtualenv, and the global hermes command. You do not need to install Python or Node beforehand.

Step 1 — Run the installer

Open Terminal (or iTerm2) and run:

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

The installer will prompt you to configure an LLM provider (Anthropic API, OpenAI, OpenRouter, Ollama, or a custom endpoint). You can skip this and configure it later with hermes model.

Step 2 — Reload your shell

After installation completes, reload your shell profile so the hermes command is in your PATH:

# zsh is the default shell on macOS
source ~/.zshrc

# Verify the install
hermes --version

Step 3 — What was installed?

Here's where everything lives after a standard per-user install:

Step 4 — Run the health check

hermes doctor

This checks required paths, dependencies, shell integration, and (later) macOS permission status. Fix any red items before continuing.

Hermes works with any OpenAI-compatible endpoint. You can use local Ollama models, Anthropic's API, OpenRouter, or the Nous Portal. This guide covers both paths.

Option A — Local model via Ollama (recommended for privacy)

With 28 GB of RAM, your Mac Mini can comfortably run 14B parameter models. Pull a tool-capable model first:

# Great all-round agent model for 28 GB RAM
ollama pull qwen2.5-coder:14b

# Lighter option if you want faster responses
ollama pull qwen2.5-coder:7b

# Verify Ollama is running
curl http://127.0.0.1:11434/v1/models

Then configure Hermes to use it:

hermes model

# When prompted, enter:
# Endpoint URL : http://127.0.0.1:11434/v1
# API Key : ollama
# Model Name : qwen2.5-coder:14b

Option B — Cloud API (Anthropic)

hermes model

# When prompted, choose "Anthropic" and paste your API key
# Get a key at: console.anthropic.com

Test your setup

hermes
# Type: "What files are in my home directory?" to confirm tool-use works

macOS enforces strict privacy controls. For Hermes to automate your desktop, read/write files, and use the screen, you must explicitly grant permissions. You only do this once, but each permission unlocks a different category of tasks.

Opening Privacy & Security settings

Go to: Apple menu → System Settings → Privacy & Security

Grant each permission listed below by finding "Terminal" (or your terminal app) in the list and toggling it on:

Step-by-step for Accessibility

1. Open System Settings → Privacy & Security → Accessibility.

2. Click the + button at the bottom of the app list.

3. Navigate to Applications → Utilities → Terminal (or your terminal app) and click Open.

4. Toggle Terminal on in the list.

5. Enter your Mac password when prompted and click Unlock.

Repeat these steps for Screen Recording. When Hermes first attempts to use screen capture, macOS may pop up an additional system prompt — click "Allow" when it appears.

Verify permissions are working

hermes doctor

Look for green checkmarks next to Accessibility and Screen Recording in the output. If you see warnings, re-check System Settings — macOS sometimes silently resets permissions after major updates.

Configuring shell access limits (optional security hardening)

For production or shared machines, you can restrict which shell commands Hermes is allowed to run by editing your config:

terminal:
allowed_commands:
- ls
- cat
- grep
- git
- python3
- npm
deny_commands:
- rm -rf
- sudo

Hermes ships a Docker-based web UI called Hermes WebUI that lets you manage sessions, browse memory, review agent logs, and chat from a browser — useful if you want to access your Mac Mini from a laptop or phone on your local network.

Launch the dashboard with Docker

Make sure Docker Desktop is running, then:

docker run -d --name hermes-webui \
-e WANTED_UID="$(id -u)" \
-e WANTED_GID="$(id -g)" \
-e HERMES_WEBUI_STATE_DIR=/home/hermeswebui/.hermes/webui \
-v ~/.hermes:/home/hermeswebui/.hermes \
-v ~/workspace:/workspace \
-p 127.0.0.1:8787:8787 \
ghcr.io/nesquena/hermes-webui:latest

Open it in your browser:

http://127.0.0.1:8787

Enable LAN access (other devices on your network)

To access Hermes from your laptop or phone on the same Wi-Fi:

API_SERVER_ENABLED=true
API_SERVER_KEY=your-very-secure-password-here
API_SERVER_HOST=0.0.0.0
API_SERVER_PORT=8642

Then restart the gateway:

hermes gateway stop && hermes gateway

Auto-start on boot (launchd)

# Install Hermes as a macOS background service
hermes gateway install

# Verify it's running
hermes gateway status

The service restarts automatically if it crashes and starts at login.

Skills are Markdown files with YAML frontmatter that teach Hermes how to handle specific recurring tasks. No code required. The agent reads the skill automatically when the task matches, follows your documented procedure, and can update the skill file itself as it learns edge cases.

Skills live in ~/.hermes/skills/. You can organize them in subdirectories: ~/.hermes/skills/devops/, ~/.hermes/skills/research/, etc.

Let the agent create a skill automatically

After completing a complex task involving 5+ tool calls, Hermes will often offer to save the workflow as a skill. Always say yes — these agent-authored skills capture pitfalls it encountered in real time.

Creating a skill manually

Here's a worked example: a skill that generates a weekly Markdown summary of your git activity across projects.

Now test your skill:

hermes
# Prompt: "What did I work on this week across all my projects?"
# Hermes will detect the weekly-git-summary skill and follow the procedure

Installing community skill packs

# Browse available skills
hermes skills search

# Install a specific pack (example: productivity tools)
hermes skills install wondelai/skills

# List your installed skills
hermes skills list

Here are five practical, ready-to-run use cases that leverage your Mac Mini's always-on nature, Apple Silicon performance, and local privacy. Each includes example prompts you can paste directly into the Hermes CLI.