Hermes Agent is an open-source, self-hosted AI agent developed by Nous Research. It features persistent memory, autonomous skill creation, and multi-platform messaging integrations including Telegram, Discord, Slack, and WhatsApp. Unlike chatbot wrappers or IDE-bound copilots, Hermes Agent runs continuously on your server, learns from interactions, and improves its capabilities over time.

This article explains how to deploy Hermes Agent on a Linux server using Docker Compose with Traefik for automatic HTTPS. It covers directory setup, environment configuration, LLM provider setup (including free access via Nous Portal), and demonstrates the application by creating a task and verifying persistent memory.

Prerequisites

Before you begin, you need to:

• Have access to a Linux-based server as a non-root user with sudo privileges.
• Install Docker and Docker Compose.
• Create a DNS A record pointing to your server's IP address (for example, hermes.example.com).

Set Up the Directory Structure, Configuration, and Environment Variables

Hermes Agent stores all user data including configuration, API keys, sessions, skills, and memories in a persistent data directory. The Docker container mounts this directory to preserve state across restarts and upgrades.

1. Create the project directory with subdirectories for persistent data.

   console Copy

   $ mkdir -p ~/hermes/data
   

   Explain Code
   • data/: Persists Hermes Agent configuration, sessions, skills, and memory files.

2. Navigate to the project directory.

   console Copy

   $ cd ~/hermes
   

   Explain Code

3. Create the environment file.

   console Copy

   $ nano .env
   

   Explain Code

4. Add the following configuration. Replace hermes.example.com with your domain name and admin@example.com with your email address.

   ini Copy

   DOMAIN=hermes.example.com
   LETSENCRYPT_EMAIL=admin@example.com
   

   Explain Code

   Save and close the file.

Deploy with Docker Compose

Docker Compose orchestrates the Hermes Agent gateway, dashboard, and Traefik reverse proxy. The gateway handles messaging integrations and agent execution, while the dashboard provides a web interface for monitoring and configuration. This setup extends the official Docker deployment guide with Traefik for automatic HTTPS and basic authentication.

1. Generate a hashed password file for Traefik basic authentication. Replace DASHBOARD_USERNAME with your preferred username and STRONG_DASHBOARD_PASSWORD with a secure password.

   console Copy

   $ docker run --rm httpd:2.4-alpine htpasswd -nbB DASHBOARD_USERNAME 'STRONG_DASHBOARD_PASSWORD' > .htpasswd
   

   Explain Code

2. Create the Docker Compose file.

   console Copy

   $ nano docker-compose.yml
   

   Explain Code

3. Add the following configuration.

   yaml Copy

   services:
     traefik:
       image: traefik:v3.6.15
       container_name: traefik
       command:
         - "--providers.docker=true"
         - "--providers.docker.exposedbydefault=false"
         - "--entrypoints.web.address=:80"
         - "--entrypoints.websecure.address=:443"
         - "--entrypoints.web.http.redirections.entrypoint.to=websecure"
         - "--entrypoints.web.http.redirections.entrypoint.scheme=https"
         - "--certificatesresolvers.letsencrypt.acme.httpchallenge=true"
         - "--certificatesresolvers.letsencrypt.acme.httpchallenge.entrypoint=web"
         - "--certificatesresolvers.letsencrypt.acme.email=${LETSENCRYPT_EMAIL}"
         - "--certificatesresolvers.letsencrypt.acme.storage=/letsencrypt/acme.json"
       ports:
         - "80:80"
         - "443:443"
       volumes:
         - "/var/run/docker.sock:/var/run/docker.sock:ro"
         - "letsencrypt:/letsencrypt"
         - "./.htpasswd:/etc/traefik/.htpasswd:ro"
       restart: unless-stopped
   
     hermes:
       image: nousresearch/hermes-agent:v2026.4.30
       container_name: hermes
       command: gateway run
       volumes:
         - ./data:/opt/data
       expose:
         - "8642"
       restart: unless-stopped
   
     dashboard:
       image: nousresearch/hermes-agent:v2026.4.30
       container_name: hermes-dashboard
       command: dashboard --host 0.0.0.0 --port 9119 --no-open --insecure
       environment:
         - GATEWAY_HEALTH_URL=http://hermes:8642
       volumes:
         - ./data:/opt/data
       depends_on:
         - hermes
       deploy:
         resources:
           limits:
             memory: 512M
             cpus: "0.5"
       labels:
         - "traefik.enable=true"
         - "traefik.http.routers.hermes.rule=Host(`${DOMAIN}`)"
         - "traefik.http.routers.hermes.entrypoints=websecure"
         - "traefik.http.routers.hermes.tls.certresolver=letsencrypt"
         - "traefik.http.services.hermes.loadbalancer.server.port=9119"
         - "traefik.http.middlewares.hermes-auth.basicauth.usersfile=/etc/traefik/.htpasswd"
         - "traefik.http.routers.hermes.middlewares=hermes-auth"
       restart: unless-stopped
   
   volumes:
     letsencrypt:
   

   Explain Code

   Save and close the file.

   In the above manifest:

   • traefik: Serves as the reverse proxy and TLS termination point with automatic Let's Encrypt certificate provisioning. Mounts the .htpasswd file for basic authentication.
   • hermes: Runs the Hermes Agent gateway that handles messaging integrations and agent execution.
   • dashboard: Provides a web interface for monitoring agent activity, viewing sessions, and managing configuration. The --insecure flag allows binding to 0.0.0.0, which is safe because Traefik handles HTTPS. The basicauth.usersfile label configures basic authentication for dashboard access.
   • volumes: The ./data mount persists all Hermes Agent state including OAuth tokens from Nous Portal. The letsencrypt volume stores TLS certificates.

4. Build and start all services in detached mode.

   console Copy

   $ docker compose up -d
   

   Explain Code

5. Verify all services are running.

   console Copy

   $ docker compose ps -a
   

   Explain Code

   Output:

   NAME               IMAGE                                  COMMAND                  SERVICE     CREATED         STATUS         PORTS
   hermes             nousresearch/hermes-agent:v2026.4.30   "/usr/bin/tini -g --…"   hermes      9 seconds ago   Up 8 seconds   8642/tcp
   hermes-dashboard   nousresearch/hermes-agent:v2026.4.30   "/usr/bin/tini -g --…"   dashboard   8 seconds ago   Up 8 seconds   
   traefik            traefik:v3.6.15                        "/entrypoint.sh --pr…"   traefik     9 seconds ago   Up 8 seconds   0.0.0.0:80->80/tcp, [::]:80->80/tcp, 0.0.0.0:443->443/tcp, [::]:443->443/tcp

6. View the logs for the services.

   console Copy

   $ docker compose logs
   

   Explain Code

   For more information on managing a Docker Compose stack, see the How To Use Docker Compose article.

Access and Configure Hermes Agent

After deployment, configure your LLM provider and access the dashboard.

1. Configure your LLM provider using the hermes model command.

   console Copy

   $ docker run -it --rm \
       -v ~/hermes/data:/opt/data \
       nousresearch/hermes-agent:v2026.4.30 model
   

   Explain Code

   Select your preferred provider. For free access, choose Nous Portal and complete the OAuth authentication flow. You can also select OpenAI, Anthropic, OpenRouter, or other providers and enter API keys when prompted. The configuration is saved to the data directory and persists across container restarts.

2. Open a web browser and navigate to https://hermes.example.com. Replace hermes.example.com with your configured domain.

3. Enter the basic authentication credentials when prompted (the DASHBOARD_USERNAME and STRONG_DASHBOARD_PASSWORD you used when generating the .htpasswd file).

4. Verify the dashboard displays the agent status and active sessions.

5. Navigate to the Config section in the dashboard to review model settings, memory preferences, and messaging integrations.

Verify the Hermes Agent Application

Testing core agent functionality confirms that memory persistence, skill execution, and the LLM integration work correctly.

1. Open a terminal session with the agent.

   console Copy

   $ docker run -it --rm \
       -v ~/hermes/data:/opt/data \
       nousresearch/hermes-agent:v2026.4.30
   

   Explain Code

   This opens an interactive chat session with the Hermes Agent.

2. Send a test message to verify the LLM connection.

   What is your name and what can you do?

   The agent responds with its capabilities and confirms the configured LLM provider (Nous Portal, OpenAI, Anthropic, or OpenRouter) is working.

3. Test persistent memory by asking the agent to remember information.

   Remember that my favorite programming language is Python.

4. Exit the chat session by typing /exit or Ctrl+C, then start a new session.

   console Copy

   $ docker run -it --rm \
       -v ~/hermes/data:/opt/data \
       nousresearch/hermes-agent:v2026.4.30
   

   Explain Code

5. Verify memory persistence by asking about the stored information.

   What is my favorite programming language?

   The agent recalls the previously stored information, confirming persistent memory is working.

6. Test a built-in tool by asking the agent to perform a task.

   What is the current date and time?

   The agent uses its tools to retrieve and display the current timestamp.

Conclusion

You have deployed Hermes Agent on a Linux server using Docker Compose with Traefik for automatic HTTPS and basic authentication for dashboard access. The setup provides a self-hosted AI agent with persistent memory, autonomous skill creation, and support for multiple LLM providers including Nous Portal (free MiMo v2 Pro access), OpenAI, Anthropic, and OpenRouter. For messaging platform integrations, scheduled automations, and advanced configuration, refer to the official Hermes Agent documentation.