---
title: "Hermes Agent"
description: "A guide on installing and configuring Hermes Agent."
---

# 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:

```shellsession
curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash
```

### Windows

```shellsession
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:

```shellsession
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:

   ```shellsession
   nano ~/.hermes/config.yaml
   ```

2. Comment out the following two lines:

   ```diff lang="yaml" title="~/.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 <kbd>Ctrl + O</kbd> to save the file and <kbd>Ctrl + X</kbd> 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:

   ```shellsession
   hermes config set HERMES_DASHBOARD_BASIC_AUTH_USERNAME example_user
   ```

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

   ```shellsession
   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:

   ```shellsession
   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:

   ```shellsession
   hermes config set HERMES_DASHBOARD_BASIC_AUTH_TTL_SECONDS 0
   ```

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

   ```shellsession
   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:

```shellsession
nano ~/.hermes/.env
```

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

```shellsession
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:

   ```shellsession
   cd ~/.config/systemd/user
   ```

2. Copy the existing gateway service:

   ```shellsession
   cp hermes-gateway.service hermes-dashboard.service
   ```

3. Open the new file into a text editor

   ```shellsession
   nano hermes-dashboard.service
   ```

4. Change the following two lines:

   ```diff lang="systemd" title="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:

   ```shellsession
   dashboard --host 0.0.0.0 --port 9119 --no-open
   ```

5. Press <kbd>Ctrl + O</kbd> to save the file and <kbd>Ctrl + X</kbd> to exit.

6. Run the following commands:

   ```shellsession
   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):

```shellsession
systemctl --user restart hermes-dashboard.service
```

## Desktop app

1. Download and install the Hermes Desktop app from the [official website](https://hermes-agent.nousresearch.com/desktop/).

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](#configure-basic-auth).

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:

```shellsession
git -C ~/.hermes/hermes-agent remote set-url origin git@github.com: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

   ```shellsession
   cd ~/.hermes/hermes-agent
   git fsck --full
   ```

2. Wipe and start over

   ```shellsession
   cd ~/.hermes/hermes-agent
   rm -rf .git
   git init
   git remote add origin git@github.com:NousResearch/hermes-agent.git
   git fetch origin main --depth 1
   git checkout -B main FETCH_HEAD
   git reset --hard FETCH_HEAD
   ```

## References

- [Hermes Agent Official Website](https://hermes-agent.nousresearch.com/)
- [Hermes Agent Documentation](https://hermes-agent.nousresearch.com/docs)
- [Hermes Agent Discord](https://discord.com/invite/nousresearch)
- [Hermes Agent GitHub Repo](https://github.com/NousResearch/hermes-agent)
- [xAI Console](https://console.x.ai/)