How to Run Hermes Agent Using Docker Compose

According to the 2025 Docker State of Application Development Report, container usage has reached 92% among IT professionals, with Docker Compose remaining the dominant orchestration tool for local development environments [Docker State of Application Development Report 2025]. The 92% container adoption rate highlights why developers are transitioning to Docker Compose orchestration configurations when deploying workloads like the Nous Research Hermes Agent. As engineering teams deploy autonomous agents to automate software development, repository analysis, and database tasks, managing the state of these agents becomes a primary concern. The Hermes Agent is designed to run locally, within virtual machines, or inside Docker containers. However, running the agent in a container without configuring persistent storage leads to immediate data loss.

The agent stores its learned skills, local configurations, database histories, and session states in the user's home directory. In a standard setup, this directory defaults to ~/.hermes on the host, which maps to /opt/data inside the official Docker image [Nous Research Hermes Agent Official Documentation]. In stateless containerized architectures, any container restart or update destroys these local files. When the container restarts, the agent loses its configuration, history, and any dynamically learned skills, forcing it to re-initialize.

Interest in containerizing agent environments is growing. The primary keyword "hermes agent docker compose" commands a search volume of 70 monthly queries and a cost-per-click of 5 dollars and 57 cents [DataForSEO Keyword Metrics]. This indicates that developers are actively investing budget and time to build repeatable containerized setups rather than running agents on bare-metal systems, as detailed in the Fastio agent onboarding guide. Implementing a structured container orchestration setup ensures that agents retain their memory and skills across deployments.

Moving from raw docker run commands to Docker Compose introduces structure, predictability, and repeatability. A raw command-line setup requires typing long strings of volume mounts, port bindings, and environment variables in the terminal. Docker Compose allows teams to define these parameters in a single configuration file. When containerizing the Nous Research Hermes Agent, the architecture must mount the host directory to /opt/data inside the container. This mount maps configuration files and skills, preserving agent memory across container rebuilds. Developers can use local bind mounts or named Docker volumes to achieve this persistence.

Another architectural challenge is handling file permissions. Inside the official Docker image, the agent process can run as a specific user. If host files are mounted without configuring matching user IDs, permissions mismatch errors will prevent the container from writing to the host filesystem.

To solve this, developers configure matching user and group IDs, typically setting both user and group identifiers to one thousand to match standard Linux and macOS host users. This configuration prevents permissions issues and ensures smooth operation.

To run the Nous Research Hermes Agent using Docker Compose, developers create a docker-compose.yml file alongside a .env file to manage sensitive API keys. This configuration defines the service, volume mounts, ports, and environment variables.

Below is the complete configuration file for your deployment:

services:
  hermes-agent:
    image: ghcr.io/nousresearch/hermes-agent:latest
    container_name: hermes-agent
    restart: unless-stopped
    ports:
      - "8642:8642"
    volumes:
      - ~/.hermes:/opt/data
    environment:
      - HERMES_UID=1000
      - HERMES_GID=1000
      - OPENROUTER_API_KEY=${OPENROUTER_API_KEY}

This configuration specifies the following parameters:

• Image: Uses ghcr.io/nousresearch/hermes-agent:latest, which is the official container registry for the project.
• Ports: Exposes port 8642, the default port for the Hermes Agent dashboard and API interface. Exposing this port allows developers to connect to the agent's web-based workspace from localhost.
• Volumes: Mounts the host directory ~/.hermes to the container directory /opt/data, ensuring all learned skills, database files, and session configurations are persisted.
• Environment Variables: Passes HERMES_UID and HERMES_GID to align container file ownership with the host. It also pulls the OPENROUTER_API_KEY from the host system environment or a local .env file, keeping API keys secure.

Step-by-step launch commands:

Step One: Create a new directory named hermes-setup and create a .env file within it.

mkdir hermes-setup
cd hermes-setup
echo "OPENROUTER_API_KEY=your_api_key_here" > .env

Step Two: Write the docker-compose.yml file.

Step Three: Launch the agent using the Docker Compose command:

docker compose up -d

Step Four: Run the interactive setup command using Docker Compose:

docker compose exec -it hermes-agent hermes setup

Step Five: Monitor the container logs to verify that the agent starts and connects successfully:

docker compose logs -f hermes-agent

Persist Hermes Agent databases and skills securely

Create a shared cloud workspace with built-in versioning, automated metadata extraction, and a dedicated MCP server interface for your running agent. Starts with a 14-day free trial.

Start 14-Day Trial

Deploying the Nous Research Hermes Agent with Docker Compose ensures that files and settings persist across container lifecycles. However, local host directories present collaboration bottlenecks for distributed engineering teams. When an agent runs on a local workstation or a private development server, human team members cannot easily view its outputs, review its code modifications, or supply it with new context documents.

Local Bind Mounts Local storage limits collaboration to the physical machine running the container. If another developer needs to inspect a report generated by the agent, they must copy the file manually.

Amazon S3 Some teams write custom scripts to sync local directories to Amazon S3 buckets. While S3 provides durable object storage, it does not support real-time team collaboration or file previews. Managing bucket policies and writing synchronization code increases maintenance overhead.

Google Drive Using standard cloud drives like Google Drive creates data silos. These platforms require complex OAuth flows and do not support direct integration with containerized agents without extensive customization.

Fastio Workspaces To solve these collaboration bottlenecks, development teams can connect containerized agents to Fastio workspaces. Fastio is an intelligent workspace platform that allows humans and agents to share the exact same files and workspace context. By running the Fastio MCP server, containerized agents read and write files directly within shared directories.

The platform supports streamable HTTP at /mcp and legacy Server-Sent Events at /sse, allowing any running agent to authenticate and access files. Developers can refer to the Fastio MCP documentation at mcp.fast.io/skill.md for tool integration details. Files uploaded to the workspace automatically maintain a complete version history. If an agent modifies a script or configuration file, the platform records the changes, allowing human engineers to review diffs and restore previous versions directly from the dashboard.

Integrating the containerized Nous Research Hermes Agent with Fastio workspaces unlocks advanced file processing capabilities. When Intelligence Mode is enabled, files uploaded to the workspace are automatically indexed for semantic search and citation-backed chat. This built-in RAG capability allows the agent to search through large repositories and return precise references. For structured extraction, developers can configure Metadata Views, which turn raw documents into a live, queryable database. No templates or OCR rules are required.

Natural Language Schema Definition Developers describe the columns they want to extract in plain English. The platform supports Text, Integer, Decimal, Boolean, URL, JSON, and Date & Time fields.

Smart File Matching The AI scans the workspace and classifies matching files, extracting details like invoice totals, policy numbers, or contract dates, and populating them in a spreadsheet grid. Agents can create these views and query results programmatically via MCP, allowing them to automate document analysis at scale. For more information, visit the Metadata Views page.

Webhooks and Ownership Handoff To enable automated pipelines, Fastio supports webhooks that trigger notifications when files are added or modified, allowing developers to trigger containerized agent runs without constant polling. If team files are located on other platforms, the URL Import feature pulls files from Google Drive, OneDrive, Box, or Dropbox via OAuth without using the agent's local bandwidth.

Pricing and Subscriptions Using these workspaces requires an organization subscription. Fastio offers the Starter plan at $29/mo, the Business plan at $99/mo, and the Growth plan at $299/mo [Fastio Pricing]. Every organization starts with a 14-day free trial that requires a credit card [Fastio Terms of Service]. An agent can sign up for free, configure the workspace, and transfer administrative ownership to a human. This handoff gives billing control to the human while letting the agent retain admin access to continue its tasks.