Setup Hermes Agent on Your Own Machine

If you want to experiment with AI agents, Hermes Agent is a good starting point for understanding how an AI agent works. You don't need to define the entire LLM workflow yourself because Hermes already provides the agent workflow. You mainly need to act as the orchestrator: building memories, scheduling tasks, and connecting external tools.

The use cases for AI agents are extensive. An agent can become your personal assistant, research assistant, or the foundation for other AI-powered products.

Before getting into the technical details, you need a machine that can run your agent 24/7, so your agent is always ready whenever you need it.

I believe there are two good ways to set up your AI agent:

Manually set it up on any Linux Virtual Private Server (VPS).
Use the same setup as the first approach, but deploy it with Docker.

In this guide, we'll go through the first approach. If I have time, I'll document the Docker-based deployment separately.

Prerequisites

For this setup, you'll need a Linux VPS from any provider, such as AWS Lightsail, DigitalOcean, Vultr, or another VPS provider.

Minimum requirements

A Linux VPS running Ubuntu 24.04 LTS.
- Make sure the system can run Python 3.11+.
Root or sudo access.
At least 2 GB RAM and 2 CPU cores.
A public IP address.

1. Sanity Check

First, check whether the required tools are already installed:

python3 --version    # Requires Python 3.11+
curl --version
git --version

If one or more of the commands above are missing, install the required packages:

sudo apt update
sudo apt install -y python3 python3-pip python3-venv curl git

After installation, you can run the version checks again to make sure everything is available.

2. Install Hermes Agent

Download the Hermes installation script:

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

Then execute the installation script:

bash install-hermes.sh

After the installation completes, the hermes command should be available.

Verify the installation:

hermes --version

If the command returns the Hermes version, the installation was successful.

3. Configure the LLM Provider

There are many LLM providers available. For seamless integration, you can use a provider that supports the OpenAI-compatible API.

After registering with your chosen provider, make sure you have your API key available.

Create the Hermes configuration directory:

mkdir -p ~/.hermes

Create the environment file:

nano ~/.hermes/.env

Add your API credentials:

OPENAI_API_KEY=<paste-api-key-here>
OPENAI_BASE_URL=https://api.yourproviderurl.ai/v1

Replace the placeholder values with the API key and OpenAI-compatible base URL provided by your LLM provider.

For security, restrict access to the .env file:

chmod 600 ~/.hermes/.env

Configure the model

Create the Hermes configuration file:

nano ~/.hermes/config.yaml

Add:

model:
  provider: openai
  default: gpt-4o-mini

Change default to a model supported by your provider.

4. Test the API Connection

Before integrating everything with Hermes, it's a good idea to test the API directly.

This step is useful for troubleshooting:

If curl succeeds but hermes chat fails, the problem is likely related to the Hermes configuration.
If curl also fails, the problem is more likely related to your API key, provider configuration, network, or model name.

Load the environment variables:

source ~/.hermes/.env

Then test the OpenAI-compatible API:

curl -s https://api.yourproviderurl.ai/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -d '{
    "model": "gpt-4o-mini",
    "messages": [
      {
        "role": "user",
        "content": "Say hi in 5 words"
      }
    ]
  }' | jq .

You should receive a JSON response containing the model's response, for example:

{
  "choices": [
    {
      "message": {
        "role": "assistant",
        "content": "Hi there, nice to meet!"
      }
    }
  ]
}

Note: The exact response structure and content may vary depending on your provider.

Common errors

401 Unauthorized

Usually indicates that your API key is invalid, missing, or incorrectly configured.

404 Not Found

Can indicate that the endpoint or model name is incorrect, or that the selected model isn't available through your provider.

5. Run Hermes

Once the API connection works, start Hermes:

hermes chat

Try sending your first message:

Halo, apa kabar? Balas dalam Bahasa Indonesia.

If Hermes responds in Bahasa Indonesia, congratulations! 🎉

Your Hermes Agent is now running with a minimal configuration.

Optional: Keep Hermes Running with `tmux`

If you're running Hermes on a VPS, you may want to use tmux so the session can continue running even after you disconnect from SSH.

Setup Hermes Agent on Your Own Machine