"Hermes remembers you, works while you sleep, and lives in the apps you already use."
Contents
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.
- Install Docker: Follow the official Docker engine guide for Ubuntu (which Mint is based on) under your Admin account.
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.
- Why this works perfectly: When the computer turns on, it will automatically log into the Kids' account. Simultaneously, in the background, Docker will boot your Hermes container. Your kids can play their MIDI keyboard on the TV, and when they go to sleep, you can simply open a browser on a laptop (or switch users on the PC) to configure Hermes without interrupting anything.
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 versionto 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
- 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.