Hermes Agent Setup on Mac (Local Install Guide)

Overview

This guide walks you through setting up Hermes Agent on a brand new MacBook. The local setup gives you full control over your AI assistant running directly on your Mac.

Video Reference: Watch on YouTube
Duration: ~7 minutes
Difficulty: Beginner

---

Important Note

Setting up Hermes Agent locally means building everything from scratch: skills, workflows, and file organization. This can be time-consuming. If you prefer an all-in-one solution with everything pre-configured, consider cloud alternatives or VPS setups.

---

Prerequisites

• MacBook with macOS
• Internet connection
• Terminal access
• API key from your chosen provider (Anthropic, Kimi, MiniMax, DeepSeek, etc.)

---

Installation Steps

Step 1: Install Hermes Agent

1.1 Get the Installation Command

Visit hermes-agent.newsresearch.com and copy the installation command.

1.2 Run Installation

Open Terminal and paste the command:

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

This installs packages and dependencies for Hermes Agent.

Step 2: Install Command Line Tools (If Needed)

If you see "command not found" when trying to run hermes setup, you need to install Xcode Command Line Tools first.

2.1 Install Command Line Tools

xcode-select --install

2.2 Check System Settings

A popup will appear. Click "Install" to proceed.

Alternatively, go to:

• System Settings → Software Update
• Look for "Command Line Tools for Xcode"
• Click "Update Now"

Installation time: ~2-5 minutes (varies by connection speed)

2.3 Verify Installation

Once complete, you should see confirmation that tools are installed in /Library/Developer/CommandLineTools.

2.4 Re-run Installation

Now run the Hermes installation command again:

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

The installation should now proceed without errors. This typically takes 2-3 minutes.

Step 3: Run Hermes Setup

Once installation completes, start the setup wizard:

hermes setup

3.1 Choose Setup Type

You'll see two options:

• Quick Setup (Recommended): Faster, customize later
• Full Setup: Step-by-step configuration

Choose Quick Setup for your first installation.

3.2 Select API Provider

Choose your AI model provider. Options include:

• Anthropic (Claude)
• Kimi
• MiniMax
• DeepSeek
• Gemini
• OpenRouter

Important:

• For Kimi: Choose "Kimi (International)" if you're outside China
• For MiniMax: Choose "MiniMax (Global)" if you're outside China

3.3 Enter API Key

Paste your API key when prompted.

3.4 Select Default Model

Choose the model you want to use (e.g., Kimi K2.6, MiniMax M2.7, Claude Opus).

3.5 Configure Messaging Platform (Optional)

You can set up Telegram or Discord integration, or skip this step to use the local TUI (Terminal User Interface).

For local setup, select: Launch Hermes Agent chat now

Step 4: Launch and Test

4.1 First Launch

The Hermes TUI should load automatically. If you see errors at the bottom of the screen, don't worry—this is common on first launch.

4.2 Restart if Needed

If you can't type in the terminal:

1. Press Ctrl+C to terminate
2. Open a new terminal window
3. Run: hermes

4.3 Test Your Agent

Type a simple message:

Hi! How are you?

If you get a response, setup is complete! 🎉

---

Troubleshooting

"Command Not Found" Error

Problem: Running hermes setup shows "command not found"

Solution: Install Xcode Command Line Tools (see Step 2)

Installation Hangs or Fails

Problem: Installation stops or shows errors

Solutions:

1. Check your internet connection
2. Ensure you have enough disk space (at least 2GB free)
3. Try running the installation command again
4. Restart your Mac and try again

TUI Won't Load or Shows Errors

Problem: Terminal UI has errors at the bottom or won't accept input

Solution:

1. Terminate the current session (Ctrl+C)
2. Open a new terminal window
3. Run hermes again

API Key Errors

Problem: "Invalid API key" or authentication errors

Solutions:

1. Verify you copied the entire API key (no extra spaces)
2. Check that the API key is for the correct provider
3. Ensure your API key is active and has credits/quota available

---

Post-Setup Configuration

Accessing Configuration Files

Your Hermes configuration is stored at:

~/.hermes/config.json

Updating Hermes

To update to the latest version:

hermes update

Starting Hermes

After setup, start Hermes anytime with:

hermes

---

Next Steps

After successful installation:

1. Explore the Dashboard: Run hermes dashboard to access the web interface
2. Set Up Skills: Create custom skills for your workflow
3. Configure Integrations: Add Telegram, Discord, or other platforms
4. Create Cron Jobs: Automate recurring tasks
5. Customize Settings: Adjust personality, memory, and behavior

---

Comparison: Local vs VPS vs Cloud

Local Setup (This Guide)

Pros:

• Full control over your system
• No monthly VPS costs
• Data stays on your machine

Cons:

• Mac must be running for agent to work
• Uses local resources (CPU, RAM)
• More complex initial setup

VPS Setup

Pros:

• 24/7 availability
• Doesn't use local resources
• Clean separation from personal files

Cons:

• Monthly cost ($2-10)
• Requires SSH knowledge

Cloud Solutions

Pros:

• Zero configuration
• Everything pre-configured
• Professional support

Cons:

• Subscription costs
• Less customization
• Vendor lock-in

---

Related Resources

• Hermes Agent Setup on VPS
• Hermes Agent Dashboard Setup
• Hermes Agent Curator Guide

---

Getting Help

If you encounter issues:

1. Check the official Hermes documentation
2. Ask your Hermes Agent for help (once it's running)
3. Join the community Discord
4. Search for similar issues on GitHub

---

Last Updated: 2026-05-06