Self-Hosting Hermes AI Agent on a Mac Mini

hermes-agentollamaself-hostingmac-minilocal-aiai-agentdashboardtailscale

A Mac Mini can be used as a small, always-on local AI server for running an autonomous agent stack. This guide covers a Hermes Agent setup with local Ollama models, a web dashboard, macOS automation permissions, and safer remote access through a private network.

Before running any installer or container command, verify the current official repository, image name, and documentation. Agent frameworks and web dashboard images can change quickly, and a local automation agent may receive broad access to your machine.

Current Reference Points

Check these sources before copying any command:

Why Run Hermes Agent Locally

Running an AI agent locally has a few practical advantages:

  • Data stays on the Mac Mini unless you explicitly connect external services.
  • Local models avoid per-token API costs.
  • The machine can be used for desktop automation, file handling, and background workflows.
  • Apple Silicon Mac Minis are quiet, power-efficient, and suitable for long-running local services.

The tradeoff is that local models may be slower or less capable than hosted frontier models. You also become responsible for security, updates, backups, and access control.

Prerequisites

Prepare the following before installation:

  1. A Mac Mini, preferably Apple Silicon.
  2. Ollama installed and running.
  3. Docker Desktop installed if you plan to run a web dashboard.
  4. Basic familiarity with Terminal and macOS privacy permissions.
  5. A clean backup or restore point before granting desktop automation permissions.

Step 1: Install Hermes Agent

The setup uses a one-line installer from the Hermes Agent repository. Verify the source before executing remote scripts.

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

After installation, refresh your shell profile so the hermes command is available.

source ~/.zshrc

Check that the CLI is installed.

hermes --version

If the command is not found, confirm that the installer added Hermes to your shell path and that you are using the expected shell profile.

Step 2: Connect Hermes to a Local Ollama Model

To keep inference local, run Hermes through Ollama. For coding and agent workflows, start with a smaller tool-capable model before moving to larger models.

Pull a model:

ollama pull qwen2.5-coder:7b

Model sizing guidance:

  • 8GB to 16GB RAM: start with 7B or 8B models.
  • 24GB+ RAM: try larger models if response speed is acceptable.
  • Agent workflows: prioritize reliability, instruction following, and tool-use behavior over raw model size.

Quick Method

If the Hermes CLI supports automated Ollama setup in your installed version, use:

ollama launch hermes

This flow is expected to detect Ollama and prompt you to select a pulled model.

Manual CLI Method

Use the model configuration wizard if you prefer manual configuration.

hermes model

When prompted, choose a custom OpenAI-compatible endpoint and use:

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

The Ollama OpenAI-compatible endpoint is typically available at http://127.0.0.1:11434/v1, but verify the endpoint in your current Ollama version. If your installed Hermes version uses an older setup wizard, hermes setup may expose the same configuration prompts.

Step 3: Grant macOS Security Permissions

Desktop automation requires macOS permissions. When Hermes first tries to control the desktop or inspect the screen, macOS may block the action until permissions are granted.

Open System Settings > Privacy & Security and review permissions for the terminal or Hermes application under:

  1. Accessibility: allows the agent to interact with UI elements and type.
  2. Screen Recording: allows the agent to inspect the desktop layout.

Then run:

hermes doctor

Use this to check whether required paths, dependencies, and permissions are correctly configured.

Step 4: Set Up a Web Dashboard

A web dashboard makes it easier to review tasks, manage sessions, and inspect agent activity. The setup below uses a Docker-based Hermes WebUI container. Verify the image name and Docker options against the current WebUI documentation before running it.

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 the dashboard locally:

http://127.0.0.1:8787

If the page does not load, check that Docker Desktop is running and that port 8787 is not already in use.

Step 5: Enable Remote Access on Your Local Network

If you need to connect from another device on the same local network, configure the API server carefully.

Open the Hermes environment configuration file:

nano ~/.hermes/.env

Add or update:

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

Restart the gateway:

hermes gateway stop && hermes gateway

From another device on the same network, connect with:

URL: http://<YOUR_MAC_MINI_IP_ADDRESS>:8642/v1
Secret Key: your-super-secure-password

Use a strong secret key and avoid reusing credentials from other services.

Secure Remote Access

Do not expose Hermes or dashboard ports directly to the public internet with router port forwarding. An agent that can automate your desktop or access local files should be treated as a high-risk service.

A safer approach is to install Tailscale on both the Mac Mini and the client devices. Tailscale creates an encrypted private network, so you can connect to the Mac Mini through its Tailscale IP instead of exposing local ports publicly.

Recommended approach:

  1. Install Tailscale on the Mac Mini.
  2. Install Tailscale on your laptop or phone.
  3. Sign in to the same Tailscale network.
  4. Access the Hermes API or dashboard through the Mac Mini’s Tailscale IP.
  5. Keep API keys enabled even inside the private network.

For the dashboard, prefer keeping Docker bound to 127.0.0.1 and using an authenticated tunnel or a private network path instead of publishing it broadly on your LAN.

Operational Best Practices

For a local agent server, security and maintenance matter as much as installation.

  • Keep Hermes, Ollama, Docker images, and macOS updated.
  • Use strong API keys and avoid hardcoding them in public notes or repositories.
  • Keep the dashboard bound to local or private network access unless there is a specific reason to expose it.
  • Review automation permissions regularly in macOS settings.
  • Start with low-risk tasks before letting the agent perform file or desktop actions.
  • Keep logs enabled so you can audit what the agent attempted.
  • Back up important local files before testing autonomous workflows.

Troubleshooting Checklist

Use this checklist when the setup does not work as expected.

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

Common issues:

  • hermes command not found: shell profile was not reloaded or PATH was not updated.
  • Ollama endpoint not reachable: Ollama is not running or the endpoint differs.
  • Desktop automation fails: Accessibility or Screen Recording permission is missing.
  • Dashboard fails to start: Docker is not running or the port is already occupied.
  • Remote client cannot connect: firewall, API host binding, or network routing is blocking access.

Summary

The overall setup is:

  1. Install Hermes Agent.
  2. Run a local model through Ollama.
  3. Grant macOS permissions for desktop automation.
  4. Run a web dashboard with Docker.
  5. Enable API access only on trusted networks.
  6. Use Tailscale for secure remote access.

With this structure, a Mac Mini can function as a private local AI agent server for experimentation, automation, and remote access without depending entirely on hosted AI services.

Related