Set Up Hermes Agent with AWS Bedrock

Install and configure a self-improving AI agent powered by AWS Bedrock on macOS.

Introduction

30 Second Summary

Your phone has Siri, your browser has ChatGPT, but your actual development machine doesn't have an AI that truly knows you, remembers your preferences, and gets better every time you use it.

In this project, you will install and configure Hermes Agent on your Mac, connect it to AWS Bedrock as its LLM provider, and customize it into a personal AI agent with persistent memory, a skills system, and a custom identity.

What You'll Build

A fully configured personal AI agent running locally on your Mac, powered by Claude Sonnet 4.6 via AWS Bedrock, with shell command execution, web search, persistent memory, and a self-improving skills system.

By the end of this project, you'll have:

  • A working Hermes Agent installation connected to Claude Sonnet 4.6 via AWS Bedrock, with AWS credentials configured for the boto3 credential chain.
  • A customized SOUL.md identity file that defines your agent's personality, with memory and user profile entries that persist across sessions.
  • A verified skills system with browseable bundled skills and your first agent-created skill saved from a real task.
  • A Telegram or Discord gateway so you can talk to your agent from your phone (Secret Mission).

Are there any prerequisites?

You need an AWS account with Bedrock access and an IAM user with programmatic access (access key ID + secret access key). Your IAM user needs the AmazonBedrockFullAccess managed policy, which covers bedrock:InvokeModel, bedrock:InvokeModelWithResponseStream, bedrock:ListFoundationModels, and bedrock:ListInferenceProfiles. You also need Anthropic Claude models enabled in the Bedrock console for your chosen region.

Install Hermes Agent

Before you can connect your AI agent to AWS Bedrock, you need Hermes Agent installed on your Mac. Hermes has a one-line installer that handles all dependencies automatically, including Python, Node.js, and several system utilities. The only prerequisite is Git, which you'll verify first.

In This Step, Get Ready To:
  • Confirm Git is installed on your Mac.
  • Run the Hermes Agent one-line installer.
  • Verify the hermes command is available in your terminal.
Verify Git Is Installed

The Hermes installer needs Git to clone the Hermes repository during setup. Most Macs have Git pre-installed through the Xcode Command Line Tools, but it's worth confirming before you run the installer.

  • Open Terminal.
  • Run the following command:
git --version

I see a version number

You should see something like git version 2.39.5. The exact version number doesn't matter. Git is ready to go.

I see a prompt to install

If Git isn't installed, macOS will prompt you to install the Xcode Command Line Tools.

  • Click Install when the dialog appears.
  • Wait for the installation to complete. This can take a few minutes.
  • Run git --version again to confirm Git is now available.
Run the Hermes Agent Installer

Hermes provides a one-line installer that handles everything: Python 3.11 (via uv), Node.js v22, ripgrep, ffmpeg, the repository clone, virtual environment creation, and the global hermes command.

  • Run the installer in your terminal:
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash

What does this command do?

This downloads and runs the official Hermes install script. curl -fsSL fetches the script silently, and piping it to bash executes it immediately. The installer takes 2-3 minutes to complete.

Once the installer finishes, you need to reload your shell so it picks up the new hermes command.

  • Run the following command to reload your shell configuration:
source ~/.zshrc

Why ~/.zshrc?

macOS uses zsh as its default shell since macOS Catalina. The ~/.zshrc file is where your shell configuration lives. Sourcing it reloads any new PATH entries the installer added.

Verify the Installation
  • Run the following command to confirm Hermes is installed:
hermes --version

You should see the current version number (v2026.4.16 or later).

Getting "command not found"?

If you see "command not found", try opening a brand new terminal window instead of reloading your current one. If you use bash instead of zsh, run source ~/.bashrc instead.

Still stuck? Help me troubleshoot the Hermes installation.

Hermes is installed and ready. Next up, you'll configure your AWS credentials so Hermes can connect to Bedrock as its LLM provider.

Configure AWS Credentials

Hermes Agent uses AWS Bedrock as its LLM provider, which means it needs valid AWS credentials to make API calls. Hermes relies on the boto3 credential chain to find your credentials automatically. The standard way to set this up on macOS is through the AWS CLI, which stores your access keys in a well-known location that boto3 checks by default.

In This Step, Get Ready To:
  • Install the AWS CLI v2 on your Mac.
  • Configure your AWS access key and secret key for programmatic access.
  • Verify that your credentials can reach AWS Bedrock and list available models.
Install the AWS CLI

The AWS CLI is the command-line tool for interacting with AWS services. You need it to store your credentials in the format that Hermes expects.

  • Run the following commands in Terminal to download and install the AWS CLI v2.
curl "https://awscli.amazonaws.com/AWSCLIV2.pkg" -o "AWSCLIV2.pkg"
sudo installer -pkg AWSCLIV2.pkg -target /
rm AWSCLIV2.pkg

What do these commands do?

The first command downloads the official AWS CLI installer package. The second command runs the macOS package installer with sudo (you will be prompted for your Mac password). The third command cleans up the downloaded file. This installer is a universal binary that supports both Intel and Apple Silicon Macs.

  • Verify the installation by running:
aws --version

I see a version number

You should see something like aws-cli/2.x.x followed by Python version info. You are all set to configure your credentials.

Command not found

If you see "command not found", try opening a new Terminal window first. The installer adds the aws command to your PATH, but your current shell session may not have picked it up yet.

If a new window does not help, help me troubleshoot my AWS CLI installation on macOS.

Configure Your AWS Credentials

Hermes checks for AWS credentials in a specific order. On your Mac, the most common path is through the credentials file at ~/.aws/credentials. The aws configure command creates this file for you.

  • Run aws configure and enter your credentials when prompted.
aws configure

You will be prompted for four values. Enter them as follows:

AWS Access Key ID: your-access-key-id-here
AWS Secret Access Key: your-secret-access-key-here
Default region name: us-east-1
Default output format: json

What region should I choose?

Choose a region where you have Bedrock model access enabled. us-east-1 is the most common choice because it has the widest selection of Bedrock models. If you have already enabled model access in a different region, use that region instead.

What does this create?

This command creates two files: ~/.aws/credentials (stores your access key and secret key) and ~/.aws/config (stores your default region and output format). Hermes finds these files automatically through the boto3 credential chain.

Verify Your Bedrock Access

Before connecting Hermes, you should confirm that your credentials can actually reach AWS Bedrock and that you have model access enabled.

  • Run the following command to list available Anthropic models in your region.
aws bedrock list-foundation-models --region us-east-1 --query "modelSummaries[?providerName=='Anthropic'].modelId" --output table

What does this command do?

This calls the Bedrock API to list all available foundation models, then filters the results to show only Anthropic models. The --query flag uses JMESPath syntax to filter, and --output table formats the results as a readable table.

I see a table of model IDs

You should see a table listing Anthropic model IDs like anthropic.claude-sonnet-4-6-20250514-v1:0 and others. This confirms your credentials are working and Bedrock is reachable. Your IAM permissions are correctly configured.

I see an access denied error

An access denied error means your IAM user is missing the required permissions. Your IAM user needs at minimum these permissions: bedrock:InvokeModel, bedrock:InvokeModelWithResponseStream, bedrock:ListFoundationModels, and bedrock:ListInferenceProfiles.

The easiest fix is to attach the AmazonBedrockFullAccess managed policy to your IAM user. You also need to enable model access for Anthropic Claude models in the Bedrock console for your region.

If you are still stuck, help me troubleshoot my Bedrock access denied error.

Your AWS credentials are configured and verified. Next up, you will connect Hermes to Bedrock and select your model.

Connect Hermes to Bedrock

Your AWS credentials are configured and verified. Now it is time to point Hermes at AWS Bedrock so it has a brain to think with. Hermes uses Bedrock's native Converse API to communicate with foundation models. This means no middleman services, no API key wrappers. Your agent talks directly to Bedrock using the IAM credentials you just set up.

In This Step, Get Ready To:
  • Select Claude Sonnet 4.6 as your model through the interactive model picker.
  • Run diagnostics to confirm Hermes can reach Bedrock.
  • Verify your configuration file has the correct Bedrock settings.
Run the Model Selector

Hermes includes an interactive model picker that walks you through choosing a provider and model. This is the easiest way to wire up Bedrock without manually editing configuration files.

  • Run the model selector command.
hermes model
  • Select More providers... from the list.
  • Select AWS Bedrock.
  • Choose your region. This should match the region you set during aws configure (e.g., us-east-1).
  • Pick us.anthropic.claude-sonnet-4-6 as your model.

Why Claude Sonnet 4.6?

Hermes requires a model with at least 64K context. Claude Sonnet 4.6 has the best balance of speed, capability, and tool-use reliability for agent tasks. Opus 4.6 is more capable but slower and more expensive. Haiku 4.5 is fastest but less capable for complex multi-tool workflows.

Always Use Inference Profile IDs

Always use model IDs prefixed with us. (e.g., us.anthropic.claude-sonnet-4-6), not bare foundation model IDs (e.g., anthropic.claude-sonnet-4-6).

The us. prefix enables cross-region inference, which provides better capacity and automatic failover. Using the bare ID results in the error: "Invocation of model ID ... with on-demand throughput isn't supported."

Run Diagnostics

Hermes includes a built-in diagnostic command that checks every piece of the Bedrock connection. This is the fastest way to confirm everything is wired up correctly before starting your first conversation.

  • Run the diagnostics command.
hermes doctor

What Does This Command Do?

The hermes doctor command runs four checks. It verifies that AWS credentials are available. It confirms that boto3 is installed. It tests whether the Bedrock API is reachable by calling ListFoundationModels. It reports how many models are available in your region.

All checks should pass with green checkmarks.

All checks passed

You are good to go. Move on to verifying your configuration file.

boto3 is missing

If the doctor reports that boto3 is not installed, you can install the Bedrock-specific extra manually.

pip install hermes-agent[bedrock]

If you used the one-line installer from Step 1, boto3 should already be included in the [all] extra. This fallback is only needed if something went wrong during installation.

  • Run hermes doctor again after installing to confirm all checks pass.

Another error

Still Seeing Errors?

Double-check that your IAM user has the AmazonBedrockFullAccess policy attached and that you have enabled model access for Anthropic Claude models in the Bedrock console for your chosen region.

If you are still stuck, help me debug my hermes doctor output.

Verify Your Configuration File

The model selector writes your choices to a YAML configuration file. Checking this file confirms that Hermes knows which provider, model, and region to use every time it starts.

  • Open ~/.hermes/config.yaml in your editor.
cat ~/.hermes/config.yaml
  • Confirm the file contains the correct Bedrock configuration.
model:
  default: us.anthropic.claude-sonnet-4-6
  provider: bedrock
  base_url: https://bedrock-runtime.us-east-1.amazonaws.com
bedrock:
  region: us-east-1

What Should I See?

The model.provider should be bedrock and the model.default should start with us. followed by your chosen model. If you selected a different region (e.g., us-east-2), the base_url and bedrock.region values will reflect that (e.g., https://bedrock-runtime.us-east-2.amazonaws.com).

How Does Hermes Find Your AWS Credentials?

Hermes uses the boto3 credential chain to find your AWS credentials automatically. It checks environment variables first, then falls back to the ~/.aws/credentials file you created with aws configure. You do not need to paste any API keys into the Hermes config file.

Hermes is now connected to Bedrock and ready to think. Next up, you will start your first real conversation and watch your agent use tools to accomplish tasks.

Run Your First Conversation

Your agent is installed, your credentials are configured, and Bedrock is connected. Now it is time to put everything to the test.

In this step, you will launch Hermes and have a real conversation that exercises its tool execution, multi-turn context, and slash commands. This is where you confirm that the LLM connection and the agent's ability to act on your system are both working end to end.

In This Step, Get Ready To:
  • Start Hermes and verify tool execution by giving it a real task.
  • Test multi-turn conversation to confirm context carries across turns.
  • Explore slash commands to understand session management and token usage.
Start Hermes and Have a Real Conversation

Hermes is not a simple chatbot. It has access to tools that let it run shell commands, read files, and interact with your system. Your first prompt should exercise these tools so you can confirm everything works.

  • Run hermes in your terminal to start a conversation.
hermes

You will see a welcome banner showing your model, available tools, and skills. This confirms that Hermes loaded your Bedrock configuration successfully.

  • Give Hermes a task that forces it to use its terminal tool. Type the following prompt:
Summarize this directory in 5 bullets and tell me what the main entrypoint is.

Watch Hermes run commands, read files, and synthesize a response. This confirms that both the LLM connection and tool execution are working.

What should I see?

Hermes will show you each tool call it makes in real time. You will see it run commands like ls or cat to inspect files, then produce a structured summary. If you see tool calls executing and a coherent response, everything is working.

Getting an error or no response?

If you see a throttling or access denied error, run hermes doctor to check your Bedrock connection. Make sure you are using the inference profile ID (us.anthropic.claude-sonnet-4-6) and not the bare foundation model ID. Help me troubleshoot my Hermes Bedrock connection.

Test Multi-Turn Interaction

A single response proves the connection works. A multi-turn conversation proves that context carries across turns and that Hermes can chain multiple tool calls together.

  • Continue the conversation with a follow-up task that builds on the first response. For example, ask Hermes to create a simple script based on what it found, or to fix something it identified.
  • Verify that Hermes references information from the first turn in its second response.

If Hermes remembers what it found in the first turn and acts on it in the second, your multi-turn context is working correctly.

Explore Slash Commands

Hermes has a set of slash commands that give you control over your session. These let you check token usage, switch models, compress context, and manage conversations without leaving the chat.

  • Type /usage to see how many tokens your session has consumed so far.
  • Type /model to see your current model and switch to a different one if needed.
  • Type /compress to manually trigger context compression.
  • Type /skills to browse the available bundled skills.
  • Type /new to start a fresh conversation.
  • Type / and use tab completion to discover all available commands.

What is context compression?

As your conversation grows, it uses more tokens. Context compression summarizes older turns to free up space while preserving the important information. Hermes triggers this automatically when needed, but /compress lets you trigger it manually.

Why does /compress matter with Bedrock?

Bedrock does not yet fully support auxiliary provider tasks like automatic compression summaries. When Bedrock is your main provider, compression may drop middle turns without generating a summary. This is a known limitation being tracked in the Hermes project. For most conversations this is fine, but for very long sessions you may notice some context loss after compression.

Pro tip: mid-session model switching

The /model command lets you switch models without restarting. You can start a conversation with us.anthropic.claude-sonnet-4-6 for speed, then switch to us.anthropic.claude-opus-4-6-v1 for a particularly complex task.

You have a working agent that can understand your requests, execute commands on your system, and maintain context across a conversation. Next up, you will make this agent truly yours by customizing its identity and memory.

Customize Your Agent's Identity and Memory

Your agent is running and connected to Bedrock, but right now it has a generic personality and no memory of who you are. Hermes has three systems that make it genuinely personal: SOUL.md for identity, persistent memory files for context that carries across sessions, and a skills system that lets the agent learn new procedures from real tasks. In this step, you will configure all three.

In This Step, Get Ready To:
  • Define your agent's personality and communication style in SOUL.md.
  • Verify that Hermes saves facts about you to persistent memory files.
  • Explore bundled skills and trigger the agent to create a new skill from a real task.
Edit SOUL.md to Define Your Agent's Personality

SOUL.md occupies slot #1 in the system prompt. It completely replaces the default identity, so everything you write here shapes how your agent thinks and communicates. This file lives at ~/.hermes/SOUL.md and is loaded from your Hermes home directory only, not from your current working directory.

  • Open ~/.hermes/SOUL.md in your preferred text editor.
  • Replace the default content with a personality that matches how you want your agent to communicate.

Here is an example tailored for someone with deep AI/ML expertise:

# Personality
You are a pragmatic senior engineer with deep AI/ML expertise.
You optimize for truth, clarity, and usefulness over politeness theater.

## Style
- Be direct without being cold
- Prefer substance over filler
- Push back when something is a bad idea
- Admit uncertainty plainly
- Keep explanations compact unless depth is useful

## Technical posture
- Prefer simple systems over clever systems
- Care about operational reality, not idealized architecture
- Treat edge cases as part of the design, not cleanup
- When discussing AI/ML, assume the user has deep domain knowledge

What belongs in SOUL.md vs. other config files?

SOUL.md is for durable personality and voice guidance. Project-specific instructions belong in AGENTS.md files within your project directories. Think of SOUL.md as "who you are" and AGENTS.md as "what you're working on right now."

  • Save the file.

The new personality takes effect on the next conversation. You can start a fresh session by typing /new inside Hermes or by restarting the hermes command. Hermes security-scans and truncates SOUL.md content before injecting it, so you do not need to worry about prompt length.

Pro tip: make it yours

The example above is just a starting point. You can write your SOUL.md in any style. Some people write it as a character description. Others write it as a list of rules. The only requirement is that it tells the agent how to behave.

Verify Memory Is Working

Hermes maintains two memory files that persist across sessions. MEMORY.md (2,200 characters, roughly 800 tokens) stores the agent's own notes. USER.md (1,375 characters, roughly 500 tokens) stores facts about you. Both files are injected as frozen snapshots at the start of each session, so the agent always has context about you from the moment it wakes up.

  • Start a new conversation by running hermes.
  • Tell Hermes something memorable about yourself or your environment. For example:
I work primarily in Python, my main project is at ~/projects/my-app, and I prefer concise responses.

Hermes should automatically save relevant facts to its memory using its built-in memory tool. You may see it call this tool in the conversation output.

  • After the conversation, check the memory files to confirm your facts were saved:
cat ~/.hermes/memories/MEMORY.md
cat ~/.hermes/memories/USER.md

What does this command do?

The cat command prints the contents of a file to your terminal. You are checking that Hermes wrote your preferences into its memory files. These files live in ~/.hermes/memories/ and are security-scanned before each entry is accepted.

You should see entries reflecting what you told the agent. Changes made during a session persist to disk, but they only appear in the system prompt at the start of the next session.

Memory files are empty?

If the files are empty or missing, try being more explicit. Tell Hermes: "Please remember that I prefer Python and my main project is at ~/projects/my-app." Some models need a direct prompt to trigger the memory tool. If the files still do not update, help me troubleshoot Hermes memory.

Explore the Skills System

The skills system is how Hermes learns new procedures. Skills are on-demand knowledge documents following the agentskills.io standard. They use progressive disclosure: Level 0 gives a compact list of all available skills (roughly 3,000 tokens), Level 1 loads the full content of a specific skill, and Level 2 drills into a specific file within a skill. Skills are saved to ~/.hermes/skills/ and persist across sessions.

  • Inside a Hermes conversation, type /skills to browse the bundled skills.

You will see a list of pre-installed skills that Hermes can use. Try invoking one to see it in action.

  • Try the plan skill by typing:
/plan design a CLI tool that converts markdown to PDF

What does this command do?

The /plan slash command invokes the planning skill. Hermes creates a structured implementation plan for the task you describe, breaking it into phases with clear deliverables. This is a bundled skill, meaning it came pre-installed with Hermes.

Now trigger Hermes to create its own skill. The agent creates skills automatically when it solves a complex, multi-step task that it might need to repeat.

  • Ask Hermes to do something complex enough to warrant saving a procedure. For example:
Find all Python files in my home directory that import requests, list them, and create a summary of what each one does.
  • After Hermes completes the task, check whether a new skill was created:
ls ~/.hermes/skills/

If Hermes created a skill, you will see a new directory here. The agent uses the skill_manage tool to create, update, and delete skills. Not every task triggers skill creation. If no new skill appeared, try asking Hermes to explicitly save the procedure: "Save what you just did as a skill for future use."

Your agent now has a custom identity, persistent memory, and a growing skills library. In the next section, you will have the chance to extend Hermes even further by connecting it to a messaging platform.

Secret mission

Connect Hermes to Telegram or Discord

Your agent is powerful, but it is trapped in your terminal. What if you could message Hermes from your phone while you are away from your desk? In this secret mission, you will connect Hermes to a messaging platform so your AI agent is always within reach.

Before you go

Clean Up Your Resources

Decide whether to keep your resources running, pause them to come back later, or delete them entirely. Hermes Agent runs locally on your Mac, so there are no ongoing infrastructure costs. However, any conversations you have with Hermes will incur AWS Bedrock usage charges (Claude Sonnet 4.6 costs ~$3/M input tokens and ~$15/M output tokens).

Cost warning

Hermes itself is free, but every message you send uses AWS Bedrock API calls that are billed to your AWS account. A typical session uses well under $0.50, but leaving a gateway running (e.g., Telegram) could accumulate costs if messages are sent frequently. If you are not actively using Hermes, consider pausing or deleting your setup to avoid unexpected charges.

Resources you used:

  • Hermes Agent installation (cloned repo, virtual environment, global hermes command).
  • AWS CLI v2 installation.
  • AWS credentials stored in ~/.aws/credentials and ~/.aws/config.
  • Hermes configuration files in ~/.hermes/ (including config.yaml, SOUL.md, memories, and skills).
  • Dependencies installed by the Hermes installer (Python 3.11 via uv, Node.js v22, ripgrep, ffmpeg).
  • Telegram or Discord bot (Secret Mission only).

Keep everything running

No action needed. Choose this if you are still actively using Hermes and plan to continue experimenting with your agent.

  • Your Hermes installation, AWS credentials, SOUL.md, memories, and skills all remain in place.
  • You can start a new conversation anytime by running hermes in your terminal.
  • Remember that each conversation incurs Bedrock API charges. Monitor your usage in the AWS Billing console.
  • If you set up a Telegram or Discord gateway, stop it when not in use to avoid unintended API calls (Ctrl+C in the terminal running the gateway).

Pause - I'll come back to this later

Keep your files and configuration intact, but stop any running processes to avoid unexpected costs.

  • Stop any running Hermes gateway processes (Ctrl+C or close the terminal window).
  • Your ~/.hermes/ directory (config, SOUL.md, memories, skills) stays on disk and costs nothing.
  • Your AWS credentials in ~/.aws/ remain configured. No charges are incurred unless you make API calls.
  • To resume later, just run hermes in your terminal. Everything picks up where you left off.

Delete - I don't want to use this again

Remove all project resources and start fresh. This permanently deletes your agent's memories, skills, and configuration.

  • Stop any running Hermes processes (gateway or CLI sessions).
  • Delete the Hermes configuration directory:
rm -rf ~/.hermes
  • Remove the Hermes Agent installation. The installer clones the repo and creates a virtual environment. Check your home directory or wherever the installer placed the repo, and delete it.
  • Optionally remove the AWS CLI if you no longer need it:
sudo rm -rf /usr/local/aws-cli
sudo rm /usr/local/bin/aws
sudo rm /usr/local/bin/aws_completer
  • Optionally remove your AWS credentials if you no longer need them for other projects:
rm -rf ~/.aws
  • If you created a Telegram or Discord bot for the Secret Mission, delete the bot via @BotFather (Telegram) or the Discord Developer Portal.
  • Consider revoking or deleting the IAM access key in the AWS console if it was created solely for this project.

Mission accomplished

That's a Wrap!

Nice work! You now have a fully operational personal AI agent running on your Mac, powered by your own AWS Bedrock account.

This is not a toy demo. Hermes is a self-improving agent with persistent memory, a skills system, and the ability to execute real tasks across your system. The more you use it, the smarter it gets.

Here's what you accomplished:

  • Installed Hermes Agent on macOS and connected it to Claude Sonnet 4.6 via AWS Bedrock's native Converse API, with properly configured IAM credentials flowing through the boto3 credential chain.
  • Ran a real multi-turn conversation with tool execution, verifying that Hermes can run shell commands, analyze files, and chain actions across turns.
  • Customized your agent's identity with a SOUL.md personality file, verified persistent memory across sessions, and explored the skills system for agent-created procedural knowledge.
  • Connected Hermes to Telegram or Discord via the gateway, enabling cross-platform agent access from your phone.

Ready to quiz yourself?