Run Your First AI Agent with Hermes — Step-by-Step (30 Minutes, Zero to Working)

Why this guide exists

This is the exact step-by-step companion to the "Agentic AI in Action" talk I gave to the AWS Student Builder Group at UNISA on 20 May 2026. If you were on the call and saw me run an AI agent that web-searched, used the AWS CLI, and uploaded files to my own S3 bucket — this is how you do the same on your own machine, tonight, in about 30 minutes.

If you weren't on the call, the full talk is here → Agentic AI in Action — the deck + write-up. Watch that first if you want the why. This guide is the how.

The harness we'll use: Hermes Agent

We're using Hermes Agent by NousResearch. It is, as of May 2026:

• #1 on OpenRouter — 224 billion tokens / day, beating the closed-source paid competitors
• MIT open-source — you fork it, you own it, no vendor pulls the rug
• Free to run — bring your own API key (OpenRouter has free credits), or use the Nous-hosted gateway
• Built-in tools — web search, browser, file ops, terminal, vision, scheduled automations, persistent memory — all ship out of the box
• MCP support — plug in the official AWS MCP server with a few lines of YAML and the agent has every AWS service

That's the BYOS thesis from the talk: compose, don't construct. Tonight you'll compose a working agent in 30 minutes.

What you'll have at the end

• ✅ Hermes installed and running on your machine
• ✅ Connected to a real LLM via OpenRouter (or Anthropic / Nous / OpenAI — your pick)
• ✅ The agent uses web search to find real things on the live internet
• ✅ The official AWS MCP server plugged in — your agent can use every AWS service
• ✅ Files written to your own S3 bucket by an AI agent
• ✅ Foundation for scheduled, always-on agents

Time: ~30 min if you have nothing installed. ~15 min if you have AWS CLI + API keys ready.

Cost: R0 / $0 to follow this guide. AWS free tier covers everything. OpenRouter gives free credits on signup.

Prerequisites

You need:

• A laptop running macOS, Linux, or Windows with WSL2. (Plain Windows works but every step is painful — install WSL2 first.)
• Terminal comfort — you don't need to be a wizard, but you should know how to open a terminal, cd into a folder, and run commands.
• An email address for the three free signups below.

You'll create three free accounts:

• OpenRouter (openrouter.ai) — one API key, 200+ models, free credits to start
• AWS (aws.amazon.com/free) — for S3 free tier
• (Optional) GitHub if you don't already have one

Step 1 · Install Hermes (5 min)

One command does it all. It downloads and configures Python 3.11, Node, uv (the package manager), ripgrep, ffmpeg, and Git for you.

macOS / Linux / WSL2:

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

Windows native PowerShell (early beta — WSL2 recommended):

iex (irm https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.ps1)

After it finishes, reload your shell:

source ~/.zshrc    # macOS default shell
# or
source ~/.bashrc   # Linux / WSL2

Verify:

hermes --version

You should see a version like hermes 0.x.x. If you get "command not found," close and reopen your terminal.

Step 2 · Get an OpenRouter API key (3 min)

We'll use OpenRouter as the model gateway. One key, 200+ models. Free credits on signup.

1. Go to openrouter.ai, sign up (free), verify email.
2. Top-right menu → Keys → Create Key.
3. Copy the key (starts with sk-or-...) — you won't see it again.

Export it so Hermes can find it:

# zsh (default on Mac)
echo 'export OPENROUTER_API_KEY="sk-or-YOUR-KEY-HERE"' >> ~/.zshrc
source ~/.zshrc

# bash (default on Linux/WSL2)
echo 'export OPENROUTER_API_KEY="sk-or-YOUR-KEY-HERE"' >> ~/.bashrc
source ~/.bashrc

Verify:

echo $OPENROUTER_API_KEY | head -c 15

You should see the first 15 chars of your key.

Step 3 · Configure Hermes to use OpenRouter (2 min)

Hermes ships with a setup wizard. Run it:

hermes model

You'll see an interactive prompt — pick OpenRouter as the provider. Then pick a model. Recommendations:

Model	When
openai/gpt-4o-mini	Fast + cheap, great for first-timers
anthropic/claude-sonnet-4-6	Strong reasoning, best tool use
nousresearch/hermes-4-405b	Hermes's own tuned model

Don't overthink — pick openai/gpt-4o-mini for this guide. You can swap any time with /model inside the TUI.

Step 4 · Enable Hermes's built-in tools (2 min)

Hermes ships with 40+ tools. Enable the ones we need:

hermes tools

In the interactive prompt, make sure these are enabled (toggle with space):

• ✅ web_search — fetch live web results
• ✅ read_file, patch — local file ops
• ✅ terminal, process — run shell commands
• ✅ browser_navigate, browser_snapshot (optional) — for visual browsing

Save when done.

Step 5 · Run Hermes for the first time (1 min) 🎉

hermes

The TUI opens. Type:

Hi Hermes. List three tools you can use right now.

You should see Hermes acknowledge web_search, terminal, read_file, etc. That's the agent loaded and live.

Type /exit to quit. Or stay in and try things — Ctrl+C cancels in-flight tool calls.

Step 6 · Install AWS CLI (skip if you have it) (3 min)

Check first:

aws --version

Install (macOS):

brew install awscli

Install (Linux / WSL2):

curl "https://awscli.amazonaws.com/awscli-exe-linux-x86_64.zip" -o "awscliv2.zip"
unzip awscliv2.zip
sudo ./aws/install

Step 7 · Set up a free AWS account + IAM user (10 min — skip if you have one)

1. Go to aws.amazon.com/free → Create a Free Account.
2. Credit card required for verification, free tier is generous (5 GB S3, plenty for us).
3. Pick Basic Support — Free.
4. After signup, go to the IAM console (search "IAM" in top bar).
5. Users → Create user → name hermes-agent-demo.
6. Attach policies directly → check AmazonS3FullAccess (for this demo).
7. Create user → click into it → Security credentials tab → Create access key → pick CLI.
8. Copy both the Access Key ID and the Secret Access Key — you won't see the secret again.

Configure the AWS CLI:

aws configure

Enter when prompted:

• Access Key ID: <paste it>
• Secret Access Key: <paste it>
• Default region: us-east-1
• Output format: json

Verify:

aws sts get-caller-identity

You should see your AWS account ID + the user hermes-agent-demo. Great — your AWS is wired.

Step 8 · Plug the AWS MCP server into Hermes (3 min) 🎉 The magic moment

AWS shipped the official AWS MCP server (awslabs/aws-api-mcp-server) GA on 6 May 2026. It exposes every AWS API as MCP tools — IAM-aware, CloudTrail-audited.

Open your Hermes config:

mkdir -p ~/.hermes
nano ~/.hermes/config.yaml

If the file already exists with other content, append this section. Otherwise paste it as the file:

mcp_servers:
  aws_api:
    command: "uvx"
    args: ["awslabs.aws-api-mcp-server@latest"]
    enabled: true

Save and exit nano (Ctrl+O, Enter, Ctrl+X).

Note: uvx was installed automatically by the Hermes installer in Step 1. If for some reason it's missing: curl -LsSf https://astral.sh/uv/install.sh | sh then reload your shell.

Step 9 · Verify Hermes sees the AWS MCP (1 min)

hermes

Inside the TUI, type:

/reload-mcp

Then:

What MCP servers do you have access to, and what tools does each expose?

You should see aws_api listed with a long list of AWS tools (s3, ec2, iam, lambda, bedrock, etc.). The agent now has every AWS service one tool call away.

Step 10 · Have the agent do real work (5 min) 🎉 The "wow"

Still inside the Hermes TUI, type:

Use the aws_api MCP to do these things, in order:

1. Create an S3 bucket called <yourname>-hermes-demo in us-east-1, skip if it already exists
2. Search the web for 3 entry-level software engineering jobs in Cape Town
3. Save the list of jobs as JSON to s3://<yourname>-hermes-demo/jobs-today.json
4. Tell me what you did

Use my AWS credentials. Show me the commands you run before running them.

(Replace <yourname> with something unique — S3 bucket names are globally unique. e.g. akhil-hermes-demo.)

Watch Hermes:

1. Show the planned AWS API calls
2. Create the bucket (or skip if exists)
3. Use web_search to find real job postings
4. Use the aws_api MCP to upload the JSON
5. Summarise what it did

Verify outside Hermes:

aws s3 ls s3://<yourname>-hermes-demo/
aws s3 cp s3://<yourname>-hermes-demo/jobs-today.json - | head -50

You should see your file. It's in YOUR AWS account, written by an AI agent that you composed in 30 minutes. That's the BYOS win.

Step 11 · What you just built (the recap)

Map this back to the talk:

Talk slide	What you did
Slide 11 (Anatomy)	You used the real thing — Model = openai/gpt-4o-mini via OpenRouter · Harness = Hermes · Tools = web_search + terminal + aws_api MCP · Memory = ~/.hermes/
Slide 8 (MCP = USB-C)	You plugged the AWS USB-C in — three lines of YAML and all of AWS reachable
Slide 9 (Why Hermes)	Free, swap-anything, runs anywhere — proven
Slide 12 (AWS toolbox)	You touched S3 live. Next steps reach Bedrock, SES, Lambda, etc.

Where to go next

Easy wins:

• Try /model inside the TUI to swap models mid-conversation — see how Claude differs from GPT differs from Hermes-405B on the same task
• Ask Hermes to schedule a recurring task: "Every morning at 7am, scan OfferZen for new junior SWE roles in Cape Town and email me the top 3." Hermes has native cron via hermes cron
• Add more AWS MCP servers — aws_iac for CDK/CloudFormation, aws_pricing for cost queries

Make it always-on:

• Hermes supports remote backends — Docker, Modal, Vercel Sandbox — so you can move from local laptop to cloud without rewriting anything
• Wrap a Hermes session in an AWS Lambda triggered by EventBridge

Explore the BYOS stack:

• Compare models on the same task — Claude vs GPT vs DeepSeek vs Llama via OpenRouter
• Add other MCP servers — GitHub, Slack, Linear, Notion — all from mcpservers.org
• (For Claude Code users) if you want a more turnkey job-hunt agent, santifer/career-ops is the Claude Code equivalent (46K stars, MIT) — different harness, same composition idea

Troubleshooting

hermes: command not found → Close and reopen your terminal. If still missing, re-run the install command.

/reload-mcp does nothing → Quit the TUI (/exit), restart with hermes. Some changes require a full restart.

MCP server times out / errors → Check that uvx --version works in your shell. If not: curl -LsSf https://astral.sh/uv/install.sh | sh, reload shell, try again.

aws s3 cp says "Access Denied" → Your IAM user hermes-agent-demo doesn't have S3 perms. Go back to Step 7 and attach AmazonS3FullAccess.

Agent uploads to S3 but the AWS console looks empty → Check the region selector (top-right of console) — we wrote to us-east-1.

Hermes asks me confirmation for every tool call → This is the default safety mode. Type y to confirm. To loosen: /config set tool_confirmation false (only do this once you trust what's happening).

hermes model keeps showing rate-limit errors → OpenRouter's free tier has limits. Either top up a few dollars at openrouter.ai/credits, or pick a free model from the list (DeepSeek + Llama have free tiers).

Cost reality check

• Hermes: $0 — it's the CLI
• OpenRouter: ~$0.20 to run through this entire guide once with gpt-4o-mini. Free credits cover it.
• AWS S3: $0 (5 GB free tier — our JSON file is tiny)
• AWS data transfer: $0 for what we do

You can do this whole guide for under R5.

Resources from the talk

• 📺 Full talk + deck: /presentations/2026-05-13-agentic-ai-byos — comment BYOS on my IG for the link
• 🤖 Hermes Agent: github.com/NousResearch/hermes-agent · docs
• 🟧 AWS MCP servers: github.com/awslabs/mcp
• 🌐 OpenRouter: openrouter.ai
• 🧩 MCP server registry: mcpservers.org
• 🐙 (Claude Code alternative) career-ops: github.com/santifer/career-ops

Stuck?

DM me on Instagram → @africantechbro.ai. Tell me where you got stuck and I'll help. If you fix something the guide missed, message me — I'll update it.

You're not behind. You're early.

You just ran an open-source AI agent end-to-end with AWS integration in 30 minutes. Most South African devs haven't done this yet. You're now in the top 5% who have. Use the leverage.

— Akhil africantechbro.ai · zaio.io