> ## Documentation Index
> Fetch the complete documentation index at: https://docs.suji.fr/llms.txt
> Use this file to discover all available pages before exploring further.

# Hermes Agent

> Nous Research's open-source autonomous AI agent — persistent memory, scheduled tasks, self-written skills. Runs on your VM with your own model key.

[Hermes Agent](https://github.com/NousResearch/hermes-agent) is Nous Research's open-source autonomous AI agent. Unlike a session-based chat tool, it runs as a persistent daemon: it keeps **memory across sessions**, runs **scheduled tasks**, and **writes its own reusable skills** from experience. You drive it from a web dashboard at your `*.suji.fr` address.

Hermes is an **orchestrator** — it calls out to an LLM provider you choose (Anthropic, OpenAI, or OpenRouter) rather than running model weights locally, so it runs fine on a normal CPU VM. You bring your own model key.

This page covers running Hermes on Suji end-to-end. Hermes is maintained upstream; Suji provides the [marketplace packaging](https://github.com/suji-hq/suji-templates/tree/main/hermes).

<Warning>
  The Hermes workspace can **approve and run shell commands**. Suji always protects the dashboard with a mandatory sign-in (username + password are required at install) — but choose a strong password and treat access like root on the VM.
</Warning>

***

## Before you install

You need an API key for **one** model provider:

* **Anthropic** — [console.anthropic.com](https://console.anthropic.com) → API keys
* **OpenAI** — [platform.openai.com](https://platform.openai.com) → API keys
* **OpenRouter** — [openrouter.ai/keys](https://openrouter.ai/keys) (one key, many models)

Have the key ready for the install form.

***

## Install

Dashboard → **Apps** → **Hermes Agent** → **Install**:

| Field              | Required | Notes                                                                         |
| ------------------ | -------- | ----------------------------------------------------------------------------- |
| VM                 | yes      | **Medium (8 GB) or larger** — it runs a 4 GB container plus bundled Chromium. |
| Subdomain          | no       | Suggestion is `hermes`. Reached at `https://<subdomain>.suji.fr`.             |
| Model provider     | yes      | Anthropic, OpenAI, or OpenRouter.                                             |
| API key            | yes      | The key for the provider you picked (the form shows the matching field).      |
| Dashboard username | yes      | For logging into the dashboard. Defaults to `admin`.                          |
| Dashboard password | yes      | Choose a strong one — this guards an agent that can run commands.             |
| Session secret     | no       | Auto-generated. Keeps you logged in across restarts.                          |

Click **Deploy**. When the install is `running`, the dashboard is live at `https://hermes-<random>.suji.fr` over HTTPS through the tunnel.

***

## First connection

1. Open the install URL (`https://hermes-<random>.suji.fr`).
2. You're taken to a **Hermes sign-in page** — enter the **dashboard username and password** you set at install.
3. You land in the Hermes workspace. Start a chat, set up cron tasks, or connect a messaging channel.

The provider key you supplied is already wired in, so the agent can reason immediately — no extra setup to start chatting.

***

## What you can do with it

* **Persistent memory** — Hermes remembers context across sessions, unlike a stateless chat.
* **Scheduled tasks** — give it recurring jobs (cron) that run unattended.
* **Self-written skills** — it turns successful workflows into reusable skills.
* **Messaging channels** — connect Telegram, Discord, and other platforms so you can talk to it outside the dashboard. Configure these from the workspace after install.

***

## Switching or adding a model provider

Hermes auto-detects the provider from whichever key is set. To change it, go to the install detail page → **Edit Install**, change **Model provider** and supply that provider's key, then redeploy. You can also fine-tune model selection and add provider keys from inside the workspace settings.

***

## Day-to-day management

| Want to…                          | Where                                                    |
| --------------------------------- | -------------------------------------------------------- |
| Chat / schedule tasks / channels  | The Hermes dashboard (`https://hermes-<random>.suji.fr`) |
| Change provider or password       | Install detail page → Edit Install → redeploy            |
| View container logs               | Dashboard → Logs (pick Hermes)                           |
| Open a shell inside the container | Dashboard → Terminal (pick Hermes)                       |
| Restart the app                   | Install detail page → Restart                            |
| Upgrade to a newer version        | Install detail page → Upgrade (when available)           |
| Remove the install + its data     | Install detail page → Uninstall                          |

<Note>
  Hermes ships frequently and upgrades can include breaking changes, so its upgrade policy is **breaking-changes-flagged** — the dashboard asks you to acknowledge before upgrading rather than applying silently.
</Note>

***

## Troubleshooting

<AccordionGroup>
  <Accordion title="Dashboard asks for a login I don't have">
    Use the **Dashboard username and password** you set at install (username defaults to `admin`). Forgot the password? Set a new one via Edit Install → redeploy.
  </Accordion>

  <Accordion title="Agent won't respond / model errors">
    Check the API key for your chosen provider is valid and has credit, then look at the Logs tab. You can re-enter the key via Edit Install.
  </Accordion>

  <Accordion title="Out of memory / container restarts">
    Hermes runs a 4 GB container plus bundled Chromium, so it needs a Medium (8 GB) VM for headroom. Move it to Medium or larger if it's being OOM-killed.
  </Accordion>

  <Accordion title="Bad gateway (Cloudflare 502)">
    The dashboard isn't up through the tunnel yet — usually still starting (wait \~30–60 s). If it persists, the Logs tab shows why the container isn't running.
  </Accordion>
</AccordionGroup>

***

## Where things live

| What                                                  | Service  | Named volume  |
| ----------------------------------------------------- | -------- | ------------- |
| Config, sessions, memories, self-written skills, logs | `hermes` | `hermes-data` |

Uninstalling deletes the volume by default — that's all the agent's memory and skills. Choose **keep data** during uninstall to preserve it.

***

## Recommended size

* **Medium (8 GB) or larger.** Hermes runs with a 4 GB container limit and bundles Chromium for browser automation; an 8 GB VM gives the OS the headroom a 4 GB VM lacks.
* The agent itself is light (it offloads reasoning to your LLM provider) — sizing is about the tools it runs, not the model.

***

## Reporting issues

| Class                                                         | Where                                                                                   |
| ------------------------------------------------------------- | --------------------------------------------------------------------------------------- |
| Hermes bug (agent, dashboard, skills, channels)               | [NousResearch/hermes-agent issues](https://github.com/NousResearch/hermes-agent/issues) |
| Marketplace packaging bug (compose / manifest / install form) | [suji-hq/suji-templates issues](https://github.com/suji-hq/suji-templates/issues)       |
| Suji platform bug (dashboard, billing, network)               | Support ticket from the dashboard                                                       |