Hermes Agent is an open-source autonomous AI agent built by Nous Research — the lab behind the Hermes family of models. Unlike static chatbots, 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 always-on host.

Why run it locally on Apple Silicon?

  • 100% private — data never leaves your machine unless you explicitly connect external services
  • No token costs — run local models via Ollama with no per-call API fees for everyday tasks
  • Self-improving — the agent writes skill files from real sessions and refines them over time
  • Always on — Mac Mini runs silently and efficiently as a 24/7 local AI server
  • Platform-agnostic — chat via CLI, Telegram, Discord, Slack, WhatsApp, or a web dashboard

// 00 — Prerequisites

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

  • macOS Tahoe (26.x) — fully updated via System Settings → General → Software Update
  • Xcode Command Line Tools — run xcode-select --install in Terminal if not already present
  • Homebrew — macOS package manager from brew.sh
  • Ollama (for local models) — download from ollama.com and open the app once to start the background service
  • Docker Desktop (optional, for the web dashboard) — from docker.com
You can skip Ollama entirely and use an API key from Anthropic, OpenAI, or OpenRouter instead. Local models keep everything offline; cloud models give more capability at the cost of privacy and per-token fees.

// 01 — Installing Hermes Agent

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 one-line installer

Open Terminal and run:

curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash
⚠ Do not use sudo. Hermes installs per-user under ~/.hermes/ and doesn't need root. Running it as root will misplace your config files.

The installer will prompt you to configure an LLM provider. You can skip this step 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:

source ~/.zshrc

Then verify the install:

hermes --version

Step 3 — Where everything lives

  • ~/.hermes/hermes-agent/ — the cloned repository, source code, and bundled skills
  • ~/.hermes/ — your personal data: config, memory, sessions, custom skills, and credentials
  • ~/.local/bin/hermes — symlink to the hermes CLI binary

Step 4 — Run the health check

hermes doctor

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

// 02 — Connecting a Model

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

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:

ollama pull qwen2.5-coder:14b

Then configure Hermes to use it:

hermes model

When prompted, enter the following values:

  • Endpoint URL: http://127.0.0.1:11434/v1
  • API Key: ollama
  • Model Name: qwen2.5-coder:14b

Model sizing guide for your 28 GB machine:

  • 7B model — fast responses, ~5 GB RAM. Good for quick tasks and lightweight automation
  • 14B model — best balance on 28 GB. Reliable tool-use, coding, and multi-step agent workflows
  • Cloud model — most capable. Use claude-sonnet-4 or gpt-4o for complex reasoning tasks

Option B — Cloud API (Anthropic)

hermes model

Choose "Anthropic" when prompted 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 is working

// 03 — macOS Permissions Setup

macOS enforces strict privacy controls. For Hermes to automate your desktop, read and 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.

🛡 Create a restore point first. Before granting Accessibility or Screen Recording access to any AI agent, use Time Machine or a backup tool to snapshot your system. Desktop automation has broad access to your machine.

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

Required permissions and what they unlock:

  • Accessibility (required) — allows Hermes to click buttons, type text, and control UI elements in other apps. Core for all desktop automation tasks
  • Screen Recording (required) — allows Hermes to read the screen layout, identify windows, and verify UI state during automation
  • Full Disk Access (optional) — allows Hermes to read and write files anywhere on your drive. Needed for broad file management skills
  • Automation (optional) — allows Hermes to control other apps via AppleScript APIs such as Finder, Mail, and Calendar

Step-by-step for Accessibility

  • Open System Settings → Privacy & Security → Accessibility
  • Click the + button at the bottom of the app list
  • Navigate to Applications → Utilities → Terminal and click Open
  • Toggle Terminal on in the list
  • 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. macOS occasionally resets permissions after major updates, so run this check again if desktop automation stops working.

Optional: restrict which shell commands Hermes can run

For shared machines, add an allowlist to ~/.hermes/config.yaml:

terminal:
  allowed_commands: [ls, cat, grep, git, python3, npm]
  deny_commands: ["rm -rf", sudo]
Best practice: Start with no restrictions and observe what commands Hermes uses for your workflows. Then lock down to only what you actually need. Over-restricting upfront will break legitimate agent tasks.

// 04 — Web Dashboard (Optional)

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 for accessing your Mac Mini from a laptop or phone on your local network.

Launch the dashboard with Docker

Make sure Docker Desktop is running, then paste this into Terminal:

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 at http://127.0.0.1:8787

Enable LAN access from other devices on your network

Edit ~/.hermes/.env and add:

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
🔒 Never forward port 8642 to the public internet. An agent that controls your desktop should only be reachable on your private network. For access outside your home, use Tailscale — a free, encrypted private network that takes about 5 minutes to set up.

Auto-start Hermes on boot (macOS launchd)

hermes gateway install

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

// 05 — Creating a Custom Skill

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 a task matches, follows your documented procedure, and can update the skill file itself as it learns new edge cases.

Skills live in ~/.hermes/skills/. Organise them in subdirectories: ~/.hermes/skills/devops/, ~/.hermes/skills/research/, etc.

Let the agent create a skill automatically

After completing a complex task involving 5 or more tool calls, Hermes will often offer to save the workflow as a skill. Always accept — these agent-authored skills capture pitfalls it encountered in real time and evolve with continued use.

Creating a skill manually

Create the file at ~/.hermes/skills/devops/weekly-git-summary/SKILL.md with this structure:

---
name: weekly-git-summary
description: Generate a Markdown summary of git commits across all projects for the past 7 days
version: 1.0.0
tags: [git, devops, reporting, weekly]
---

# Weekly Git Summary Skill

## When to Use
Trigger when asked to summarise or report on git activity, commits, or code changes. Also triggers on "what did I work on this week?"

## Quick Reference
- Scans all git repos under ~/projects/
- Covers the past 7 calendar days
- Groups commits by repository and date
- Outputs a Markdown file to ~/Documents/weekly-summaries/

## Procedure
1. Find all git repositories: find ~/projects -name ".git" -type d -maxdepth 3
2. For each repo, run: git log --oneline --since="7 days ago" --author="$(git config user.name)"
3. Group results by repo name, then by date (YYYY-MM-DD)
4. Write output to ~/Documents/weekly-summaries/YYYY-WNN.md
5. Confirm file was written and display the path

## Pitfalls
- Repos with detached HEADs will error on git log — skip them silently
- Create the output directory if it doesn't exist before writing

## Verification
- Confirm the output file exists: ls -la ~/Documents/weekly-summaries/
- Show the first 30 lines to the user for a quick sanity check

Test it by opening Hermes and asking: "What did I work on this week across all my projects?"

Installing community skill packs

hermes skills install wondelai/skills
Skill organisation tip: Use subdirectories — devops/, research/, writing/ — to keep your library manageable. The agent searches recursively and finds skills regardless of directory depth.

// 06 — 5 Real Use Cases on Mac Mini M4

These five use cases 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 or chat interface.

Use Case 1 — Local File Intelligence & Cleanup

Your Mac Mini stays on all day. Use Hermes as an always-available file assistant that can scan directories, identify duplicates, rename files by content, generate summaries of documents, and reorganise folder structures. Because everything is local, no file ever leaves your machine.

  • "Find all PDF files in ~/Downloads older than 30 days, group them by topic based on their filename, and move them to ~/Documents/Archive/[year]/"
  • "Scan ~/Desktop and rename any screenshot files using the pattern YYYY-MM-DD-description.png, where the description comes from what's visible in the image"
  • "Find duplicate files across ~/Documents and ~/Downloads and show me a list of what's safe to delete"

Create a file-organizer skill to encode your preferred folder structure, naming conventions, and archive rules — Hermes will follow them automatically every time.

Use Case 2 — Coding Assistant & Code Review

With Full Disk Access and terminal permissions, Hermes can act as a tireless junior developer. It reads your codebase, writes and edits files, runs tests, reads error output, and fixes bugs in a loop — without you having to copy-paste between windows. With a 14B local model, it handles real codebases competently.

  • "Read all TypeScript files in ./src, find any functions longer than 40 lines, and refactor them into smaller named functions with JSDoc comments"
  • "Run our test suite, find the failing tests, read the relevant source files, fix the failures, and re-run to confirm they pass"
  • "Generate a CHANGELOG.md from our git history between v1.2 and v1.3, grouped by feature, fix, and breaking change"

This use case pairs well with the obra/superpowers community skill, which adds a subagent-driven review loop before the agent marks any task complete.

Use Case 3 — Scheduled Background Workflows

The Mac Mini's always-on nature is ideal for scheduled agent tasks. Hermes has a built-in cron scheduler — set it once and your agent runs research, generates reports, monitors logs, or sends digest messages automatically.

  • "Set up a daily task at 8am: check the top 5 Hacker News stories, summarise them in 2 sentences each, and send to my Telegram bot"
  • "Every Monday at 9am, generate a weekly git commit summary across all projects in ~/code and save it to ~/Documents/weekly-report.md"
  • "Monitor ~/Downloads every hour and automatically move any .zip or .dmg files older than 48 hours to the Trash"

Set up a cron job from the CLI:

hermes cron add "0 8 * * *" "summarise Hacker News and send to Telegram"

Use Case 4 — Research & Document Synthesis

Hermes can browse the web, read local PDFs and text files, synthesise across sources, and write structured Markdown reports — all in one uninterrupted workflow. Pair it with a cloud model when accuracy matters most, or run it locally for sensitive research you want to keep private.

  • "Read all PDFs in ~/Documents/Research, identify the 3 most common themes across them, and write a 500-word synthesis to ~/Documents/synthesis.md"
  • "Research the current state of open-source LLM fine-tuning tools, compare the top 5 by ease of use and Apple Silicon support, and save a comparison table to comparison.md"
  • "Read my notes in ~/Obsidian/Projects/Q3 and write an executive summary I can paste into Notion"

Create a research-report skill with your preferred citation style, output format, and section headers — Hermes will apply them consistently every time.

Use Case 5 — Desktop & App Automation

With Accessibility and Screen Recording permissions granted, Hermes can control any macOS application — clicking buttons, filling forms, copying content, navigating menus — using the same APIs as assistive technology. Start with low-risk automations and expand carefully.

  • "Open Mail, find all unread newsletters from the past week, summarise each one in a bullet point, and save the list to ~/summaries/newsletters-[date].md"
  • "Take a screenshot of each open browser tab, name them by page title, and save to ~/Screenshots/tabs/"
  • "Open Finder, navigate to ~/Downloads, select all images older than 7 days, and move them to ~/Photos/Unsorted"
Desktop automation tasks should always be reviewed the first few times they run. Use hermes doctor to verify Accessibility permissions are current — macOS occasionally resets them after system updates.

// 07 — Quick Troubleshooting Reference

Run these diagnostic commands when something isn't working:

hermes doctor
ollama list
curl http://127.0.0.1:11434/v1/models
docker ps
lsof -i :8787
lsof -i :8642

Common failure scenarios and fixes:

  • hermes: command not found — shell profile wasn't reloaded. Run source ~/.zshrc and try again
  • Ollama endpoint error — Ollama isn't running. Open the Ollama app from /Applications or run ollama serve
  • Desktop automation fails silently — Accessibility or Screen Recording permission is missing or was reset after a system update. Re-check System Settings → Privacy & Security
  • Dashboard won't load at port 8787 — Docker Desktop isn't running, or the port is already in use. Run docker ps to confirm container status
  • Remote client can't connect to port 8642 — check API_SERVER_HOST is set to 0.0.0.0 in ~/.hermes/.env, and verify no firewall is blocking the port

Guide based on Hermes Agent v0.13 by Nous Research. Always verify commands against the official documentation before running — agent frameworks update quickly. Mac Mini M4 · 28 GB RAM · macOS Sequoia · May 2026.