Installing Hermes Agent on Mac Studio#

1. Install Hermes Agent#

Official documentation:

https://hermes-agent.nousresearch.com

GitHub repository:

https://github.com/NousResearch/hermes-agent

1.1 Run the installer#

curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash

The installer handles the Hermes repository, Python environment, and required dependencies.

Expected installation paths:

~/.hermes/
~/.hermes/config.yaml
~/.hermes/.env
~/.hermes/hermes-agent/
~/.local/bin/hermes

1.2 Verify installation#

hermes --version

The MacBook Air installation used Hermes Agent v0.21.1.

The Mac Studio should use the current available release.

2. Hermes Setup Wizard#

Run:

hermes setup

Recommended selections are based on the previous successful installation.

2.1 Setup type#

Choose:

Full setup

This allows configuration of local inference, tools, browser integration, and other options.

2.2 Inference provider#

Choose:

Custom OpenAI-compatible endpoint

Configure:

If the setup requires a nonempty API key for Ollama, use a dummy value such as ollama. Ollama’s local endpoint does not require an actual cloud API key.

After entering the base URL, confirm that Hermes reports the endpoint as verified and lists the models it found.

When prompted to Select API compatibility mode, press Enter to keep the current Auto-detect choice. Auto-detect uses Hermes URL heuristics and is appropriate for Ollama’s standard OpenAI-compatible endpoint.

The setup should detect the models exposed by Ollama. Select qwen3.8:latest if the wizard asks you to choose a model.

2.3 Terminal backend#

Choose:

Local

This allows Hermes to execute commands directly on macOS.

2.4 Messaging platforms#

Skip Telegram, Discord, and other messaging integrations unless needed.

They are not required for local Hermes operation.

2.5 Browser provider#

Choose:

Local Browser

This uses local browser automation rather than requiring a paid cloud browser service.

2.6 Image generation#

Choose:

Skip

Image generation can be configured later.

3. Configure Hermes#

Inspect the current configuration:

hermes config

The expected model configuration is equivalent to:

model:
  default: qwen3.8:latest
  provider: custom
  base_url: http://localhost:11434/v1
  context_length: 65536

3.1 Match context length#

Run:

hermes config set model.context_length 65536

Expected confirmation:

✓ Set model.context_length = 65536

3.2 Enable tool-use enforcement#

This setting was essential during the MacBook Air troubleshooting.

Run:

hermes config set agent.tool_use_enforcement true

Expected confirmation:

✓ Set agent.tool_use_enforcement = true

This encourages Hermes to require actual tool invocation rather than accepting textual descriptions of actions.

3.3 Confirm active provider#

Run:

hermes model

Confirm that the active provider is:

Ollama Local

And the selected model is:

qwen3.8:latest

If a different provider is active, select the Ollama custom endpoint.

4. Validate Installation#

Run:

hermes doctor

Review the results.

Important checks:

• Python environment healthy.
• Configuration file found.
• Custom inference endpoint configured.
• Terminal tool available.
• Browser dependencies available.
• Required directories present.
• No critical security advisories.

Some warnings may be irrelevant:

• Anthropic API not configured.
• OpenRouter not configured.
• Telegram or Discord packages missing.
• Docker unavailable.
• Optional integrations disabled.

These are not necessarily installation failures.

During the MacBook Air setup, hermes doctor reported an invalid Anthropic API key even though Ollama was the active provider.

Verify the active provider independently before troubleshooting unused cloud services.

5. Test Hermes CLI#

Launch:

hermes

The CLI should display:

• Selected Qwen model.
• Available tools.
• Available skills.
• Session information.

5.1 Test actual terminal execution#

Enter:

Use the terminal tool to execute `uname -m`. Return the exact output.

Expected terminal command:

uname -m

Expected output:

arm64

Success requires seeing Hermes invoke the terminal tool.

A response that merely prints the command without executing it is not sufficient.

5.2 Test macOS version#

Enter:

Use your terminal tool to execute `sw_vers -productVersion`. Return the exact output.

The response should contain the actual installed macOS version.

5.3 Test filesystem access#

Enter:

Use your terminal tool to list the files in my home directory. Return the first 10 entries.

Hermes should invoke a terminal command and report its output.

6. Install and Launch Hermes Desktop#

Hermes Desktop is a graphical interface to the same Hermes environment.

It does not require a separate inference provider or a second Ollama installation.

Launch:

hermes desktop

Launch Desktop with 1Password-backed MCP servers#

The shared MCP configuration uses 1Password-backed MCP servers. The token is stored in ~/.zshrc; compile it into Hermes’ local MCP config before launching Desktop:

source ~/.zshrc && mcp hermes

The compiler writes the token into each op run server’s environment block in ~/.hermes/config.yaml and sets the file to mode 0600. The token stays in this local file and is not committed to the MCP Git repository. After recompiling, fully quit and relaunch Hermes Desktop from its app icon. Repeat after rotating the service-account token. mcp hermes compiles configuration; it does not launch or restart Desktop. hermes mcp list shows configured/enabled servers, not connection health; verify with hermes mcp test <server> or a real tool call.

On the first launch, Hermes may:

1. Install npm workspace dependencies.
2. Download Electron.
3. Build the graphical interface.
4. Package the macOS application.
5. Launch Hermes Desktop.

The first build may take several minutes.

6.1 Expected application path#

~/.hermes/hermes-agent/apps/desktop/release/mac-arm64/Hermes.app

To launch the packaged application directly:

open ~/.hermes/hermes-agent/apps/desktop/release/mac-arm64/Hermes.app

6.2 Verify Desktop#

In the Desktop interface, confirm:

• Ollama Local is selected.
• qwen3.8:latest is active.
• Gateway status shows ready.
• New sessions can be created.
• Terminal tools execute correctly.

Repeat the test:

Use your terminal tool to execute `uname -m`. Do not explain the command before executing it. Execute it first, then return the exact terminal output.

Expected result:

Ran uname -m

arm64

7. Troubleshooting#

7.1 Hermes describes commands instead of executing them#

Observed on MacBook Air:

Hermes produced responses resembling:

I will execute uname -m.

Output:
[ARCHITECTURE]

But no actual terminal tool was invoked.

The working configuration included:

model:
  context_length: 65536

agent:
  tool_use_enforcement: true

Also verify:

ollama ps

The active model must show the intended context length.

7.2 Ollama shows only 4096 context#

Open:

Ollama → Settings → Context Length

Set:

64K

Reload the model and verify:

ollama ps

Do not rely solely on the context configured inside Hermes.

7.3 Electron installation fails#

During the previous installation, Electron failed with:

npm error RequestError: read ECONNRESET

This indicated an interrupted network download.

First retry:

hermes desktop

If Electron’s cached download is corrupted, clear the partial cached archives:

rm -f "$HOME/Library/Caches/electron"/electron-*.zip

Then retry:

hermes desktop

The previous installation eventually completed successfully.

7.4 npm deprecation warnings#

Warnings such as:

npm warn deprecated rimraf
npm warn deprecated glob
npm warn deprecated inflight

do not necessarily mean the installation failed.

Check for an actual npm error or build failure before intervening.

7.5 Hermes Desktop is slow#

During the MacBook Air tests, Hermes Desktop displayed:

waiting on qwen3.5:9b — no stream output for 60s

It eventually executed the terminal command successfully.

This showed that the integration was functional, but inference and response latency remained significant.

Possible contributing factors:

• Model prefill time.
• Large system prompts.
• Tool schemas.
• Context length.
• Hardware memory bandwidth.
• Model size and quantization.

The Mac Studio M4 with 64 GB should be benchmarked independently.

A larger model may provide better reasoning while also taking longer to respond.

7.6 Auxiliary title generation timeout#

The CLI previously displayed:

Auxiliary title generation failed: Request timed out.

The main terminal task still completed successfully.

This warning alone does not mean Hermes tool execution failed.

8. Everyday Commands#

Stopping Ollama#

To unload the model and free its allocated memory:

ollama stop qwen3.8:latest

To quit the Ollama server entirely when using the macOS application, quit Ollama from its menu-bar icon.

Stopping a model is not the same as stopping the Ollama server.

9. Performance and Resource Considerations#

The Mac Studio has:

Apple M4
64 GB unified memory

The larger memory capacity makes it suitable for testing models beyond the 9B model used on the MacBook Air.

However, agent performance depends on more than parameter count.

Important measurements:

• Time to first response.
• Total time to complete a tool task.
• Tool-calling reliability.
• Memory consumption.
• Context size.
• Model quantization.
• CPU/GPU utilization.

Suggested benchmark#

Use the same task with each model:

Use the terminal tool to determine my Mac's architecture, macOS version, and total physical memory. Execute the commands and present the actual results.

Record:

Do not automatically assume that the larger model is the better daily agent.

For simple and medium tasks, responsiveness may be more important than maximum reasoning capability.

10. Security Considerations#

Hermes is an agent, not merely a chatbot.

With the local terminal backend, it can execute commands using the permissions of the macOS user running it.

Recommended precautions:

• Review terminal commands before approving potentially destructive actions.
• Avoid granting unnecessary permissions.
• Do not expose the Ollama API to the public internet.
• Keep secrets in the appropriate local configuration or environment files.
• Avoid placing API keys in chat sessions.
• Review browser automation permissions.
• Use version control for development projects.
• Maintain backups before granting write access to important files.

For initial testing, prefer simple read-only terminal commands.

11. Final Verification Checklist#

• Ollama installed.
• Ollama server running.
• Qwen model downloaded.
• Ollama context set to 64K.
• ollama ps confirms 65536 context.
• Hermes Agent installed.
• Hermes custom endpoint configured.
• Hermes model context set to 65536.
• Tool-use enforcement enabled.
• Hermes CLI launches.
• CLI executes terminal commands.
• Hermes Desktop builds and launches.
• Desktop connects to Ollama.
• Desktop executes terminal commands.
• Model performance benchmark completed.
• Security and tool approval settings reviewed.

12. Lessons from the MacBook Air Installation#

The previous installation established several important lessons.

1. Install Ollama and verify the model before configuring Hermes.

This separates inference problems from agent problems.

2. Explicitly configure the context length.

Ollama initially ran Qwen with only 4096 tokens, even though the model supported a much larger context.

3. Match Hermes and Ollama context settings.

The successful configuration used 65536 tokens on both sides.

4. Enable Hermes tool-use enforcement.

The successful test used:

agent:
  tool_use_enforcement: true

5. Test tool execution, not just conversation.

A model answering “hello” proves inference works, but does not establish that agent tools are functional.

6. Test CLI before Desktop.

The CLI helps distinguish agent/model issues from graphical-interface issues.

7. Do not mistake slow inference for broken integration.

On the MacBook Air, the Desktop interface eventually completed a tool call after initially reporting no stream output for 60 seconds.

8. CLI and Desktop share the same Hermes environment.

There is no need to configure two separate model providers.

13. References#

• Hermes Agent Documentation
• Hermes Agent GitHub
• Hermes Local Ollama Setup
• Hermes Providers
• Hermes Desktop
• Ollama
• Ollama Model Library

14. Installation Notes — Mac Studio#

Installation date: 2026-10-13

Hermes version: 0.21.7+495.g6e7b83a

Ollama version: TBD

Model and quantization: qwen3.8:latest; quantization not recorded

Effective context: TBD

CLI tool calling: MCP connections verified for git (28 tools) and home-assistant (77 tools); an agent-issued tool task is not yet recorded

Desktop tool calling: TBD

Typical task completion time: TBD

Memory consumption: TBD

Outstanding issues: TBD

15. Managed Local Models — external storage and macOS access#

Verified: 2026-10-21 · Hermes v0.22.4

Hermes’ managed llama.cpp runtime stores catalog models under the machine-scoped models/ directory: normally ~/.hermes/models. This install redirects that path to the external NVMe using a filesystem symlink:

/Users/marc/.hermes/models -> /Volumes/NVMe1TB/Hermes

The link existed before troubleshooting and was not created or changed during it. Keep the NVMe mounted at /Volumes/NVMe1TB; Hermes will otherwise be unable to use that model directory. This is a filesystem path, not a file:// URL. In v0.22.4, local_runtime.model_dirs is not configured and is not the mechanism used for this store.

Configure managed model downloads on an external drive#

1. Choose a stable external mount path and create the target model folder (for this Mac: /Volumes/NVMe1TB/Hermes).

2. Ensure Hermes’ default model directory, ~/.hermes/models, points to that folder. On this Mac it already does. For a fresh setup only when ~/.hermes/models does not exist, create the target and link:

   mkdir -p /Volumes/NVMe1TB/Hermes
   ln -s /Volumes/NVMe1TB/Hermes /Users/marc/.hermes/models

   If ~/.hermes/models already exists or is a symlink, inspect it and safely preserve/migrate its contents before changing anything. Do not run ln -s over an existing directory or replace an existing link blindly.

3. In System Settings → Privacy & Security → Full Disk Access, enable access for Hermes.app and osascript. On this Mac, Hermes’ launchd gateway is run through the osascript wrapper; granting access to Hermes.app alone did not let the background downloader write to the external model folder. Enabling Full Disk Access for osascript resolved the download’s Operation not permitted failure.

4. Download through Settings → Providers → Local Models. The catalog download goes into the managed models/ folder, therefore into /Volumes/NVMe1TB/Hermes through the link. If a download fails, stop rather than repeatedly retrying; check the exact error and macOS access grants.

Important distinction: Add model file links an already-existing GGUF into the library without copying it. It is useful for registering a model already stored elsewhere, but it does not redirect future catalog downloads. The managed directory link above is what redirects those downloads.

Successful download check: the Local Models row changes from Download to Use (or Default), and the new GGUF appears in /Volumes/NVMe1TB/Hermes. The external-drive link and downloaded models were preserved during the 2026-10-21 provider reset. The provider settings themselves were cleared and must be configured again separately.

Official references:

• https://hermes-agent.nousresearch.com/docs/user-guide/local-models
• https://hermes-agent.nousresearch.com/docs/getting-started/installation#symlinked-home-directories-and-external-storage

Status: Hermes v0.22.4 is installed. Provider configuration was reset on 2026-10-21; the provider/model selection and local-runtime settings need reconfiguration. The external model-storage link and downloaded models were preserved. The MCP compiler generates all 34 configured servers, and CLI connections have been verified for git and home-assistant. Effective context, Desktop tool calling, a model-issued tool task, and performance benchmarks remain to be recorded.