Please click here if you are not redirected within a few seconds.
Hermes Agents › shanebow.com
Hermes Agents
Hermes Agent "Hermes remembers you, works while you sleep, and lives in the apps you already use."

Background Server Setup (Docker + Hermes)

The plan is to have multiple Hermes agents each running in their own docker container with separate roles and duties for each agent. The root directory is /home/ai/agents (which exists on a spacious drive separate from the OS).

Because Docker runs as a system daemon, containers run completely independently of who is logged into the desktop interface.

I would like to set up collaboration between these agents as a first step, then eventually use headscale to communicate/coordinate with other agents on separate systems with the same directory structure.

To deploy the Hermes AI Agent using Docker on Ubuntu, follow this step-by-step guide to install the Docker runtime, prepare the environment, and spin up the official Hermes image.

Step 1: Install Docker Engine and Compose

Official Script

Run the official automated script to install the latest Docker environment on your Ubuntu server:

# Download and execute the official Docker installation script
curl -fsSL https://get.docker.com | sh

# Enable and start the Docker service
sudo systemctl enable --now docker

# Add your current user to the docker group to run containers without sudo
sudo usermod -aG docker $USER

# Apply the group changes without logging out
newgrp docker

Clean apt Installation

For Ubuntu 22.04 LTS

Ubuntu 22.04 is fully supported out of the box. Run this to setup the apt repository:

# Add Docker's official GPG key:
sudo apt-get update
sudo apt-get install ca-certificates curl
sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://docker.com -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc

# Add the repository to Apt sources:
echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://docker.com(. /etc/os-release && echo "$ID") \
  $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

sudo apt-get update

For Linux Mint

Linux Mint is built on top of Ubuntu, but it hides its Ubuntu codebase name (like jammy or noble) behind its own version names (like wilma or virginia).

Because the standard Docker script looks at Mint's name, it can sometimes get confused about which repository to pull from. So, it is much safer to explicitly add the official Docker apt repository mapped to Mint's underlying Ubuntu base.

However, Linux Mint 22 is based on Ubuntu 24.04 (Noble Numbat), and the installation command provided will automatically map UBUNTU_CODENAME to noble, ensuring a clean, native apt installation.

Force the script to look at the underlying Ubuntu codebase name (e.g., Mint 21 uses Ubuntu jammy, Mint 22 uses Ubuntu noble):

# Add Docker's official GPG key:
sudo apt-get update
sudo apt-get install ca-certificates curl
sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://docker.com -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc

# Add the repository using the underlying Ubuntu base name (UBUNTU_CODENAME):
echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://docker.com \
  $(. /etc/os-release && echo "$UBUNTU_CODENAME") stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

sudo apt-get update

Install the Packages (Same for both Ubuntu & Mint)

Once the repository is added to either system, run this clean apt-get command to pull down the engine and the Compose plugin:

sudo apt-get install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

# Setup user permissions so you don't need sudo for docker commands
sudo usermod -aG docker $USER
newgrp docker

Verify the installation by running docker compose version to ensure the environment is ready.

Step 2: Create the Project Structure

You do not strictly need separate folders for Docker to run, but creating separate sub-directories under /home/ai/agents is the best practice for giving each Hermes agent its own memory, config, and workspace while keeping a clean shared space for collaboration.

Because you plan to mirror this directory layout across multiple machines via Headscale later, organizing /home/ai/agents intentionally now will make scaling across nodes seamless.

Hard Drive Adjustments

Set up a dedicated workspace directory and prepare the storage volume. Hermes stores all configurations, persistent states, and active memory databases inside a mounted data directory.

In Moving /home, I showed how to mount the /home directory on a separate drive to maintain a separation between your data and the operating system. I put /home/ai on this spacious drive, so we want to establish the Docker infrastructure (for each agent) exactly inside that path.

# Create directories for the project and persistent volume
mkdir -p ~/hermes-agent/data
cd ~/hermes-agent

Adjusting your setup to store container data on your Ubuntu machine's dedicated 2TB drive layout while keeping the single-drive Mint computers clean requires a few quick modifications.

1. Ubuntu Machine (Separate 2TB /home Drive)

Since /home/ai lives on a spacious 2TB drive, we want to establish the Docker infrastructure exactly inside that path.

On the Ubuntu machine, set up the directory structure and set correct ownership so your user doesn't hit permission errors:

sudo mkdir -p /home/ai/hermes-agent/data
sudo chown -R $USER:$USER /home/ai/hermes-agent
cd /home/ai/hermes-agent

The mkdir -p command creates a directory along with all required parent directories in a single step. The -p flag (short for --parents) also prevents error messages if any part of the directory path already exists.

Your Ubuntu compose.yaml volume section should look like this to map explicitly to your 2TB array:

    volumes:
      - /home/ai/hermes-agent/data:/opt/data
  1. Linux Mint Machines (Single Drive)

Because these machines double as kid-friendly kiosks with a single drive, keep the footprint compact and out of sight. Run this on your Mint machines:

mkdir -p ~/hermes-agent/data
cd ~/hermes-agent

Your Mint compose.yaml volume section can simply use a clean, localized relative path:

    volumes:
      - ./data:/opt/data

Configure the Docker Compose File

Create a configuration file to pull the official image managed by nousresearch.

Open a new file using a text editor like Nano:

nano compose.yaml

Paste the following configurations into the file:

services:
  hermes:
    image: nousresearch/hermes-agent:latest
    container_name: hermes-agent
    restart: unless-stopped
    ports:
      - "8642:8642"  # Gateway API Port
      - "9119:9119"  # Dashboard Web UI Port (optional)
    environment:
      - HERMES_DASHBOARD=1
    volumes:
      # Maps local data folder to container backend storage
      - ./data:/opt/data
    deploy:
      resources:
        limits:
          cpus: '2'
          memory: 4GB
        reservations:
          cpus: '1'
          memory: 1GB

(Press Ctrl + O, Enter, and then Ctrl + X to save and exit in Nano).

Step 4: Build and Launch the Agent

Start the container detached in the background:

docker compose up -d

Configure Restart Policies: When launching your Hermes container, ensure you include the --restart unless-stopped flag.

docker run -d --restart unless-stopped --name hermes <hermes-image-name>

Step 5: Configure Hermes

Once the container is online, you must launch the internal setup wizard to bind your preferred AI model providers (like OpenAI, Anthropic, or OpenRouter). Access the container's interactive terminal directly:

docker compose exec hermes bash

Once inside the container shell, initialize the setup parameters:

hermes-agent setup

Follow the on-screen prompts to input your API subscriptions or connection tokens. When completed, exit the container by typing exit. You can access the local dashboard or gateway at http://your-server-ip:9119.

Skills

At its core, a skill is a folder containing a SKILL.md file. This file includes metadata (name and description, at minimum) and instructions that tell an agent how to perform a specific task.

Skills can also bundle scripts, templates, and reference materials.

my-skill/
├── SKILL.md          # Required: instructions + metadata
├── scripts/          # Optional: executable code
├── references/       # Optional: documentation
└── assets/           # Optional: templates, resources

Skills use progressive disclosure to manage context efficiently.

SKILL.md

Every skill starts with a SKILL.md file containing YAML frontmatter and Markdown instructions:

---
name: pdf-processing
description: Extract PDF text, fill forms, merge files. Use when handling PDFs.
---

# PDF Processing

## When to use this skill
Use this skill when the user needs to work with PDF files...

## How to extract text
1. Use pdfplumber for text extraction...

## How to fill forms
...

The following frontmatter is required at the top of SKILL.md:

  • name: A short identifier
  • description: When to use this skill

The Markdown body contains the actual instructions and has no specific restrictions on structure or content.

Setup

  • Basic memory - see tina
  • Audit chron -see tina