Hermes Agent

The self-improving AI agent built by Nous Research. The only agent with a built-in learning loop — it creates skills from experience, improves them during use, nudges itself to persist knowledge, and builds a deepening model of who you are across sessions.

Command-line only / remote gateway

Linux / macOS / WSL2 / Android (Termux)

Install Hermes Agent:

Terminal window
curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash

Windows

Terminal window
irm https://hermes-agent.nousresearch.com/install.ps1 | iex

Fallback providers

When your main LLM provider encounters errors — rate limits, server overload, auth failures, connection drops — Hermes can automatically switch to a backup provider:model pair mid-session without losing your conversation.

Run the following command to select a fallback provider and model:

Terminal window
hermes fallback add

If you are attempting to use your xAI SuperGrok subscription but want to fallback to using your API key when you hit your weekly limit, make sure you comment out base_url in ~/.hermes/config.yaml or it’ll be incorrectly ignored as duplicate.

  1. Open hermes config in a text editor:

    Terminal window
    nano ~/.hermes/config.yaml

  2. Comment out the following two lines:

    ~/.hermes/config.yaml
    model:
      default: grok-build-0.1
      provider: xai-oauth
      base_url: https://api.x.ai/v1
    #  base_url: https://api.x.ai/v1
    fallback_providers:
      - provider: xai
        model: grok-build-0.1
        base_url: https://api.x.ai/v1
    #    base_url: https://api.x.ai/v1

  3. Press Ctrl + O to save the file and Ctrl + X to exit.

Web Dashboard

Configure basic auth

All secrets should be stored in ~/.hermes/.env/

  1. Set a username, replacing example_username with a unique username:

    Terminal window
    hermes config set HERMES_DASHBOARD_BASIC_AUTH_USERNAME example_user

  2. Enter a secure password and store the hashed value:

    Terminal window
    HASH=$(~/.hermes/hermes-agent/venv/bin/python -c 'from plugins.dashboard_auth.basic import hash_password; import getpass; print(hash_password(getpass.getpass("Password: ")))')
    hermes config set HERMES_DASHBOARD_BASIC_AUTH_PASSWORD_HASH "$HASH"
    unset HASH

  3. Set a randomly generated secret for persistent auth sessions:

    Terminal window
    hermes config set HERMES_DASHBOARD_BASIC_AUTH_SECRET "$(openssl rand -base64 32)"

  4. Set access-token lifetime for the basic provider to 0 if using Hermes Desktop:

    Terminal window
    hermes config set HERMES_DASHBOARD_BASIC_AUTH_TTL_SECONDS 0

  5. Set the public URL, replacing hermes.example.com with your custom domain:

    Terminal window
    hermes config set HERMES_DASHBOARD_PUBLIC_URL https://hermes.example.com

You may also add or modify these settings by opening ~/.hermes/.env in a text editor:

Terminal window
nano ~/.hermes/.env

Make sure you run the dashboard with --host 0.0.0.0 if using a reverse proxy:

Terminal window
hermes dashboard --host 0.0.0.0 --port 9119 --no-open

Note: The --port 9119 part is redundant and can be omitted (as it’s the default port).

Install as a systemd service

The easiest way to have a persistent web dashboard is to set it up exactly like the messaging gateway.

  1. Change to the following directory:

    Terminal window
    cd ~/.config/systemd/user

  2. Copy the existing gateway service:

    Terminal window
    cp hermes-gateway.service hermes-dashboard.service

  3. Open the new file into a text editor

    Terminal window
    nano hermes-dashboard.service

  4. Change the following two lines:

    hermes-dashboard.service
    [Unit]
    Description=Hermes Agent Gateway - Messaging Platform Integration
    Description=Hermes Agent Web Dashboard
    After=network-online.target
    Wants=network-online.target
    StartLimitIntervalSec=0
    

    [Service]
    Type=simple
    ExecStart=/home/example_user/.hermes/hermes-agent/venv/bin/python -m hermes_cli.main gateway run
    ExecStart=/home/example_user/.hermes/hermes-agent/venv/bin/python -m hermes_cli.main dashboard --host 0.0.0.0 --port 9119 --no-open
    WorkingDirectory=/home/example_user/.hermes
    Environment="PATH=/home/example_user/.hermes/hermes-agent/venv/bin:/home/example_user/.hermes/hermes-agent/node_modules/.bin:/usr/bin:/home/example_user/.local/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin"
    Environment="VIRTUAL_ENV=/home/example_user/.hermes/hermes-agent/venv"
    Environment="HERMES_HOME=/home/example_user/.hermes"
    Restart=always
    RestartSec=5
    RestartForceExitStatus=75
    KillMode=mixed
    KillSignal=SIGTERM
    ExecReload=/bin/kill -USR1 $MAINPID
    TimeoutStopSec=210
    StandardOutput=journal
    StandardError=journal
    

    [Install]
    WantedBy=default.target

    Here’s the exact command to copy and paste:

    Terminal window
    dashboard --host 0.0.0.0 --port 9119 --no-open

  5. Press Ctrl + O to save the file and Ctrl + X to exit.

  6. Run the following commands:

    Terminal window
    systemctl --user daemon-reload
    systemctl --user enable --now hermes-dashboard.service
    systemctl --user status hermes-dashboard.service

Restart dashboard

To restart the web dashboard (e.g., to reload secrets stored in environment variables):

Terminal window
systemctl --user restart hermes-dashboard.service

Desktop app

  1. Download and install the Hermes Desktop app from the official website.

  2. Click on I'll choose a provider later in the lower left corner.

  3. Click on the settings gear icon in the top right corner.

  4. Click Gateways and under Gateway Connection, click on Remote gateway.

  5. Enter the remote URL for the dashboard backend (E.g., https://hermes.example.com). I strongly recommend connecting over a secure connection.

  6. Click Sign in and enter your Hermes Dashboard username and password.

  7. Click Test remote, followed by Save and reconnect.

  8. Close the settings window by clicking on the smaller x in the top right corner.

Updating

  1. Close the desktop app

  2. Open Windows Terminal

  3. Run hermes update

  4. Wait

Troubleshooting

HTTP 429 errors when running hermes update

Sometimes the GitHub HTTP server isn’t reliable and you need to switch to using the SSH origin:

Terminal window
git -C ~/.hermes/hermes-agent remote set-url origin [email protected]:NousResearch/hermes-agent.git

Failed to fetch updates from origin

Interrupting hermes update too many times seems to break things.

  1. Check for git errors

    Terminal window
    cd ~/.hermes/hermes-agent
    git fsck --full

  2. Wipe and start over

    Terminal window
    cd ~/.hermes/hermes-agent
    rm -rf .git
    git init
    git remote add origin [email protected]:NousResearch/hermes-agent.git
    git fetch origin main --depth 1
    git checkout -B main FETCH_HEAD
    git reset --hard FETCH_HEAD

References