Deploying Hermes Agent on AWS: A Quick-Start Guide

1. Introduction

• Hassle-free: No local resource consumption, runs 24/7
• Secure: API keys stored in a cloud secret management service
• Scalable: Start with t3.small, upgrade anytime to higher specs

2. Technical Background

What is Hermes Agent?

System Requirements

Officially Supported Backends

3. AWS Deployment Plan

EC2 + Direct Installation

1. Lowest cost: t3.small instance + 20 GB EBS, only $25/month
2. Simple and intuitive: Official one-click script handles all dependencies — no need to manually install Python or Node.js
3. Flexible and controllable: SSH access for debugging and configuration changes

Resource Breakdown

4. Step-by-Step Deployment

Step 0: Prerequisites

• ✅ AWS account (sign up at aws.amazon.com  if you don't have one)
• ✅ AWS IAM user with EC2 management permissions
• ✅ SSH key pair (for EC2 login)
• ✅ Credit card (AWS requires it for pay-as-you-go billing)

Step 1: Configure Security Group

1.1 Create a Security Group

1.2 Configure Inbound Rules

1.3 Configure Outbound Rules

Security reminder: Always restrict SSH port 22 to your fixed IP address. Never open it to 0.0.0.0/0.

Step 2: Create IAM Role (Authorize EC2 to Access AWS Services)

2.1 Create IAM Role

1. Search for IAM in the AWS console and navigate to the IAM dashboard
2. Select "Roles" from the left menu → Click "Create role"
3. Trusted entity type: Select "AWS service"
4. Use case: Select "EC2" → Click "Next"
5. Add permissions: Skip for now (we'll add them next), click "Next"
6. Role name: Enter hermes-agent-bedrock-role
7. Click "Create role"

2.2 Add Bedrock Permissions

1. Find the hermes-agent-bedrock-role role you just created in the IAM console
2. Click the role name to enter its details page
3. Click "Add permissions" → "Create inline policy"
4. Select the "JSON" tab and enter the following policy:

1. Click "Next"
2. Policy name: Enter BedrockAccessPolicy
3. Click "Create policy"

2.3 Add Secrets Manager Read Permissions (Optional)

⚠️ Only required if you use third-party APIs like OpenRouter/OpenAI. If you only use Bedrock, skip this step.

1. In the IAM console, go to the hermes-agent-bedrock-role role details page
2. Click "Add permissions" → "Create inline policy"
3. Select the "JSON" tab and enter the following policy:

1. Click "Next"
2. Policy name: Enter SecretsManagerReadPolicy
3. Click "Create policy"

Verification: Once the role is created, you'll be able to see it in the "Advanced details" section of the EC2 launch wizard (referenced in Step 3).

Step 3: Create EC2 Instance

3.1 Log in to AWS Console

3.2 Navigate to EC2 Console

3.3 Launch a New Instance

3.4 Configure Instance Parameters

Tip: It takes 1-2 minutes for the instance to start. You can check the status on the EC2 console's "Instances" page.

Step 4: Connect to Your EC2 Instance

4.1 Get the Public IP

4.2 Log in via SSH

First-time login: If this is your first time connecting to this host, the terminal will ask you to verify the host fingerprint. Type yes to confirm.

Step 5: Verify Network Connectivity

5.1 Check Public IP

• ✅ Has an address (e.g., 54.xxx.xxx.xxx): A public IP is assigned, proceed to the next test
• ❌ Empty: You need to allocate an Elastic IP (EIP) — see the "Allocate Elastic IP" step below

Note: If the instance has no public IP, you must allocate an EIP to access the internet.

5.2 Allocate and Associate an Elastic IP (if needed)

1. In the EC2 console, select "Elastic IPs" from the left menu
2. Click "Allocate Elastic IP address"
3. Select "Amazon's pool of IPv4 addresses", then click "Allocate"
4. Once allocated, select the IP, click "Actions" → "Associate Elastic IP address"
5. Select the hermes-agent instance and its private IP, then click "Associate"

Cost note: An EIP associated with a running instance is free. An unassociated EIP (while the instance is stopped) costs approximately $0.005/hour.

5.3 Check Route Table (Subnet Internet Gateway)

1. EC2 console → "Network Interfaces" in the left menu
2. Find the network interface of the hermes-agent instance, note its Subnet ID
3. Go to the VPC console → "Route Tables"
4. Filter for the route table associated with this subnet and check for the following route:

1. VPC console → "Internet Gateways" → "Create internet gateway"
2. Attach the internet gateway to your current VPC
3. Add a 0.0.0.0/0 route pointing to the internet gateway in the route table

5.4 Test Network Connectivity

Step 6: Install Hermes Agent (Official One-Click Script)

6.1 Run the Official Install Script

• Installs uv (high-performance Python package manager)
• Installs Python 3.11 (via uv, no sudo needed)
• Installs Node.js v22 (for browser automation and WeChat bridging)
• Installs ripgrep (high-speed file search)
• Installs ffmpeg (TTS audio format conversion)
• Clones the Hermes Agent repository
• Creates a virtual environment
• Sets up the global hermes command

6.2 Verify Installation

6.3 Run Diagnostics (Optional but Recommended)

6.4 Start Hermes and Test

Tip: Type /exit or press Ctrl+C to exit the conversation.

Step 7: Configure Secrets Manager (Optional)

⚠️ Only required if you use third-party APIs like OpenRouter/OpenAI. If you only use Bedrock, skip this step.

7.1 Create Secrets

5. Configuration and Usage

Run the hermes command to enter Quick Setup

Select AWS Bedrock as the LLM Provider

Configure Model Region

Select Gateway: WeChat

Configure WeChat Parameters

Verify the Model is Working

Verify WeChat Integration

6. Troubleshooting Guide (Real-World Debugging Experience)

The following are typical issues encountered during actual deployment, along with their solutions.

Issue 1: Missing boto3 (Bedrock Provider Error)

Issue 2: PEP 668 Externally-Managed Environment Error

Issue 3: which python Returns Empty

Issue 4: uv tool install boto3 Fails

Issue 5: hermes-agent Is Not on PyPI

Issue 6: uv sync Succeeds but hermes Still Reports Missing boto3

Debugging Experience Summary

Related Resources

• Hermes Agent Official Documentation 
• Hermes Agent GitHub Repository 
• AWS EC2 Pricing 
• AWS Secrets Manager Documentation