Hermes on Docker with MCP and agentic memory

The Hermes Agent is able to be run on many platforms and this repository is an attempt to sanitize its installation, use and future upgrades by hosting it on Docker Desktop (or Docker CLI).

Installation (Windows)

Clone the repo and navigate using PowerShell or Command Window (shown) to its directory. Create necessary directories for launch:

mkdir %USERPROFILE%\Documents\Workspace
cd \path\to\hermes-brain

(These directories are used by the MCP server and Hermes WebUI, respectively.)

Installation (Linux terminal)

Clone the repo and navigate using a terminal to its directory. Create necessary directories for launch:

mkdir ~/Workspace
cd /path/to/hermes-brain

(These directories are used by the MCP server and Hermes WebUI, respectively.)

Usage

Inspect the .env file which should allow loading with default settings, to enable the Hindsight memory server it is necessary to set:

HERMES_USE_HINDSIGHT=true

And then add other required Hindsight configuration variables from this example configuration (in order to set up LLM and embeddings providers).

• Note: See the file README-Hindsight.md for example senarios and configurations.

• Note: The dimensions for the vector store backend cannot be changed once configured, so choose the embeddings model with care.

Then decide on any, all or none from the profiles webui, dashboard, mcp and memory (or use --profile all instead of multiple --profile ...), such as:

docker compose -f docker-compose.windows.yml --profile webui --profile mcp up -d

(or under Linux)

docker compose --profile all up -d

Note that -f selects a filename other than the default (docker-compose.yml), while -d indicates the process runs in the background after loading.

After several minutes of pulling the dependencies of the containers and initializing them, the preconfigure.py script should run successfully and allow all of them to start. The above command must be repeated for any changes to .env (or the compose script itself).

Upgrades

To upgrade the whole setup, it is necessary to remove the hermes-agent-src volume entirely (don't remove the others as they contain your session history and memory).

# Omit [-f ...] from both docker compose commands for Linux
docker compose -f docker-compose.windows.yml --profile all down
docker volume rm hermes-brain_hermes-agent-src
docker compose -f docker-compose.windows.yml --profile all pull

Then run the same docker compose command as previously to rebuild the containers.

Issues

There are many known issues with these scripts. You will need to be able to navigate the Docker Desktop interface (including files, logs and exec shell) in order to investigate and fix them.

1. Permissions: Sometimes large parts of hermes-home becomes user 10000 instead of hermes (1000). To fix this without deleting the volume go to Exec under container hermes-agent and execute (as root user) chown -R hermes:hermes /home/hermes/.hermes

2. Memory: The preconfigure.py script tries to take the initial configuration pain out of this combination of containers, however it is incomplete in setting up the Hindsight memory server. It is necessary to use the dashboard "Plugins" tab (on port 9119 by default) to set the use of Hindsight.

3. General configuration: To reconfigure manually, it is necessary to perform the following in the Exec tab of the hermes-agent container:

su hermes # Important, or files get root permissions
hermes [command] [options...]

4. To use Gemini embeddings (3072 dimensions), it is necessary to make use of a different database backend or limit the dimensions to under 2000.

5. An internet connection is necessary for the Docker MCP service to load.

6. It appears necessary to set interface:port instead of just port for several of the containers

7. Should you run hermes as root user by accident, it may be necessary to use chown as above to restore permissions.

8. The amount of allocated memory and CPU capacity is guesswork at the moment, look out for OOM errors.

9. When using Docker CLI under Linux it is not possible to run Docker MCP tools from the Hermes WebUI although these run as expected under Docker Desktop. (Under investigation)

10. Docker containers must have become ready within 300s or they are restarted. The Hindsight container will attempt to download embeddings and reranker models by default so a fast connection (or suitable configuration) is necessary to avoid a failed loop.

Volumes

Care has been taken to ensure no anonymous volumes are created for the various different containers. See the Docker compose scripts for mountpoints within each container for these volumes, the purposes are described below:

• hermes-home: All session and configuration data (do not delete)
• hermes-memory: All memories and facts (PostgreSQL data, do not delete)
• hermes-agent-src: Shared Python source (delete before upgrading)
• hermes-data: Various persistent data for: nousresearch/hermes-agent:latest
• hermes-mcp: Various persistent data for: docker/mcp-gateway:latest
• hermes-cache: Downloaded embeddings and reranker models for Hindsight

Credits

These scripts are based upon the following two: docker-compose.three-container.yml and local-llm/docker-compose.yaml

Any bugs introduced are most likely the fault of myself, refer to these two for detailed comments and explanations.

The software is believed fully functional at present with reference to the known issues above; please raise GitHub issues and submit PRs in case of suggestions for improvement.

License

This is free software released under the MIT license (as for the Hermes-related portions of its dependencies).

Release History

2026/08/12: Release of version 1.0

2026/08/28: Initial release of 1.0-beta

2026/08/25: Initial release of 1.0-alpha