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

# Hermes Agent

> Autonomous AI agent from Nous Research on a dedicated VPS with multi-model routing via OpenRouter, a web dashboard, and messaging integrations

## Hermes Agent on RepoCloud

Hermes Agent is an open-source autonomous AI agent from Nous Research that breaks complex goals into sub-tasks, executes them through tool integrations, and handles errors without human supervision. On RepoCloud, Hermes Agent runs on a dedicated VPS with full root access, SSH, a browser console, and all the management tools in the RepoCloud dashboard.

<CardGroup cols={2}>
  <Card title="Autonomous Execution" icon="robot">
    Define a goal and Hermes plans, executes, observes, and refines until the job is done or it needs your input
  </Card>

  <Card title="400+ Models" icon="brain">
    Route through Claude, GPT, Gemini, and open-source models via OpenRouter — pick the best cost-quality tradeoff for each task
  </Card>

  <Card title="Web Dashboard" icon="display">
    Real-time progress view with step-by-step reasoning, tool calls, and output artifacts in a full TUI and web interface
  </Card>

  <Card title="Messaging Gateway" icon="comments">
    Connect Telegram, Discord, Slack, WhatsApp, and Signal for cross-platform conversation continuity
  </Card>

  <Card title="Memory and Skills" icon="graduation-cap">
    Agent-curated memory with periodic nudges and autonomous skill creation after complex tasks — skills self-improve during use
  </Card>

  <Card title="Full Root Access" icon="terminal">
    SSH into your server, customize the environment, install tools, and manage everything at the OS level
  </Card>
</CardGroup>

## Prerequisites

Before deploying Hermes Agent on RepoCloud, you need an **OpenRouter API key**:

<Steps>
  <Step title="Create an OpenRouter Account">
    Go to [openrouter.ai](https://openrouter.ai) and sign up or log in.
  </Step>

  <Step title="Add Credits">
    Navigate to **Credits** and add funds. OpenRouter charges per token based on the model you use — prices vary from fractions of a cent (open-source models) to a few cents per thousand tokens (frontier models).
  </Step>

  <Step title="Generate an API Key">
    Go to **Keys**, click **Create Key**, and give it a name (e.g., "hermes-agent"). Copy the key — it starts with `sk-or-`.
  </Step>
</Steps>

<Note>
  Hermes Agent uses pay-per-use OpenRouter billing. The API key you provide powers all LLM calls; token costs are billed to your OpenRouter account, separate from your RepoCloud subscription. OpenRouter provides access to 400+ models from 70+ providers with a single key.
</Note>

## Deploying Hermes Agent on RepoCloud

<Steps>
  <Step title="Find Hermes Agent in the Marketplace">
    Go to the RepoCloud marketplace and search for "Hermes Agent". Click on the listing.
  </Step>

  <Step title="Enter a Project Name">
    Choose a friendly name for your project (e.g., "my-hermes").
  </Step>

  <Step title="Enter Your Admin Email">
    Provide the email address for the Hermes admin account.
  </Step>

  <Step title="Enter Your OpenRouter API Key">
    Paste your `sk-or-...` API key. This is stored on the VPS and used by Hermes to authenticate with OpenRouter.
  </Step>

  <Step title="Choose Resource Settings">
    Select a tier for your server. Tiers below 2 GB RAM are greyed out because Hermes Agent requires at least 2 GB. Servers can be upgraded to a higher tier but not downsized.
  </Step>

  <Step title="Deploy">
    A dedicated IPv4 address is included with every VPS at no extra charge. Click **Deploy Hermes Agent** and wait 5–10 minutes.
  </Step>

  <Step title="Check Your Email">
    Once deployment finishes, you receive an email with:

    * **Dashboard URL** — the HTTPS link to your Hermes web interface
    * **App Credentials** — admin password for the web dashboard
    * **SSH command** — `ssh root@<your-ip>`
    * **SSH Private Key** — save it to a file, `chmod 600`, and use it to connect
  </Step>
</Steps>

## First-Time Setup

<Steps>
  <Step title="Open the Web Dashboard">
    Open the dashboard URL from your deployment email. Hermes serves a web interface for browser-based interaction with the agent.
  </Step>

  <Step title="Log In">
    Hermes uses password-based authentication. Use the password from your deployment email (shown in the RepoCloud manage page under **Access > App Credentials**). The login endpoint is `/auth/password-login` — the dashboard redirects you there automatically.
  </Step>

  <Step title="Verify Your Model Connection">
    Once logged in, start a conversation to confirm the OpenRouter API key is working. If the agent responds, your setup is complete.
  </Step>
</Steps>

<Warning>
  Hermes uses a `BasicAuthProvider` — navigate directly to the dashboard URL and use the password login form. If you see an "Internal Server Error" at `/auth/login`, go to `/auth/password-login` instead; the OAuth redirect flow is not supported by the basic auth provider.
</Warning>

## Configuring Models

### Default Configuration

Hermes is deployed with OpenRouter as the default provider. Your API key is stored in `~/.hermes/.env`:

```bash theme={null}
OPENROUTER_API_KEY=sk-or-your-key-here
```

The model configuration lives in `~/.hermes/config.yaml`:

```yaml theme={null}
model:
  provider: openrouter
  default: ~anthropic/claude-sonnet-latest
```

The `~` prefix resolves to the latest version in that model family automatically.

### Switching Models

Change the active model via SSH:

```bash theme={null}
ssh root@<your-ip>
hermes config set model anthropic/claude-opus-4-8
```

Or use the interactive model selector:

```bash theme={null}
hermes model
```

This presents a curated list of agentic models for each provider. The change takes effect immediately for new conversations.

### Popular Model Choices

| Model                             | Best For                                | Context |
| --------------------------------- | --------------------------------------- | ------- |
| `~anthropic/claude-sonnet-latest` | General tasks, balanced speed/quality   | 200K    |
| `~anthropic/claude-opus-latest`   | Complex reasoning, long tasks           | 200K    |
| `~openai/gpt-4o`                  | Fast responses, broad knowledge         | 128K    |
| `openrouter/auto`                 | Automatic model selection by OpenRouter | Varies  |
| `openrouter/pareto-code`          | Cost-optimized coding tasks             | Varies  |

<Note>
  Most agentic configurations require a model with at least 64K context tokens. Smaller context windows may be rejected because the system prompt and tool schemas fill them.
</Note>

### Auxiliary Models

Hermes can offload side tasks (titling, summarization, vision) to cheaper models while using a frontier model for the main agent loop:

```yaml theme={null}
auxiliary:
  title:
    provider: openrouter
    model: google/gemini-2.5-flash
  vision:
    provider: openrouter
    model: google/gemini-2.5-flash
```

Edit `~/.hermes/config.yaml` via SSH to configure auxiliary models.

## Using Hermes Agent

### Starting Conversations

From the web dashboard, type a goal or question. Hermes will:

1. **Plan** — break the goal into sub-tasks
2. **Execute** — run each sub-task using available tools (terminal, file system, web search, APIs)
3. **Observe** — check the results and handle errors
4. **Refine** — adjust the approach based on observations and iterate

The dashboard shows real-time progress with step-by-step reasoning, tool calls, and output artifacts.

### Tool Framework

Hermes has a pluggable tool framework that connects to:

* **Terminal** — run shell commands on the VPS
* **File system** — read, write, and manage files
* **Web search** — search the internet for information
* **APIs** — connect to external services via HTTP
* **Databases** — query and manage data stores

Configure tool access via SSH:

```bash theme={null}
hermes tools
```

### Skills System

Hermes creates reusable skills after completing complex tasks:

* Skills are saved automatically and improve during subsequent use
* Browse and manage skills from the dashboard
* Skills can be shared across sessions and conversations

### Session Management

* Conversations persist across sessions
* Full-text search (FTS5) across session history with LLM summarization
* Use `/session` commands to list, switch, and manage sessions

## Messaging Integrations

Hermes includes a gateway process that connects to messaging platforms. Configure via SSH:

```bash theme={null}
hermes gateway
```

Supported platforms:

* **Telegram** — set a bot token and chat with Hermes via Telegram
* **Discord** — connect a bot to your Discord server
* **Slack** — integrate with a Slack workspace
* **WhatsApp** — connect via the WhatsApp Business API
* **Signal** — secure messaging integration

Each platform maintains conversation continuity — start a conversation in the web dashboard and continue it from Telegram, or vice versa.

<Tip>
  To set up Telegram, create a bot via [@BotFather](https://t.me/BotFather) on Telegram, copy the bot token, and configure it: `hermes config set TELEGRAM_BOT_TOKEN your-token-here`. Then start the gateway: `hermes gateway`.
</Tip>

## RepoCloud Manage Page

Your Hermes Agent VPS has a dedicated manage page in the RepoCloud dashboard:

<AccordionGroup>
  <Accordion title="Access">
    View your server's default domain (HTTPS link to Hermes dashboard), dedicated IPv4 address, SSH connection command, and app credentials (login password).
  </Accordion>

  <Accordion title="Power">
    **Power Off**, **Power On**, and **Reboot** controls.
  </Accordion>

  <Accordion title="Console">
    Browser-based serial console for emergency access.
  </Accordion>

  <Accordion title="SSH Keys">
    Manage SSH public keys for root access.
  </Accordion>

  <Accordion title="Resize">
    Switch between tiers. Disk cannot be shrunk after an upgrade. Hermes benefits from more RAM for complex agent tasks.
  </Accordion>

  <Accordion title="Snapshots">
    Create up to 5 point-in-time snapshots. To restore, click **Restore** next to the target snapshot. If newer snapshots exist, a warning lists which ones will be permanently destroyed. The server restarts during restore (\~10–25 seconds) and the page refreshes automatically when complete.
  </Accordion>

  <Accordion title="Custom Domain">
    Point your own domain to the VPS by creating an A record to your IPv4.
  </Accordion>

  <Accordion title="Danger Zone">
    Permanently delete the server and all data.
  </Accordion>
</AccordionGroup>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Internal Server Error at /auth/login">
    Hermes uses a `BasicAuthProvider` that does not support OAuth redirect flows. Navigate to `/auth/password-login` directly, or access the dashboard root URL which should redirect correctly. Use the password from your deployment email.
  </Accordion>

  <Accordion title="Agent not responding or 'No credentials found'">
    SSH into the server and verify the API key: `cat ~/.hermes/.env | grep OPENROUTER`. If missing, re-add it: `hermes config set OPENROUTER_API_KEY sk-or-...`.
  </Accordion>

  <Accordion title="Model rejected due to context length">
    Most agentic setups need 64K+ context. If you chose a model with a smaller window, switch to one with sufficient context: `hermes config set model ~anthropic/claude-sonnet-latest` (200K context).
  </Accordion>

  <Accordion title="High OpenRouter costs">
    Frontier models (Claude Opus, GPT-4o) cost more per token. For routine tasks, use a cheaper model as the default and switch to frontier models only for complex work. Configure auxiliary models for side tasks (titling, summarization) to reduce costs.
  </Accordion>

  <Accordion title="Messaging gateway not connecting">
    Ensure the bot token or API credentials are correct. SSH in and check `hermes gateway status`. Restart with `hermes gateway restart`. Verify that the VPS has outbound internet access to the messaging platform's API endpoints.
  </Accordion>
</AccordionGroup>

## Use Cases

Hermes Agent is ideal for:

* **Developers** who want an autonomous AI assistant on their own infrastructure for research, coding, and task execution
* **Teams** that need a shared AI agent accessible from Slack, Discord, or Telegram
* **Power users** who want to route tasks through different LLM models depending on cost, speed, and quality requirements
* **Automation builders** who need an agent that can execute multi-step workflows involving terminal commands, file manipulation, and API calls

## Next Steps

<CardGroup>
  <Card title="Deploy Hermes Agent" icon="rocket" href="https://repocloud.io/details/Hermes%20Agent">
    Launch your Hermes Agent VPS from the RepoCloud marketplace
  </Card>

  <Card title="Hermes Documentation" icon="book" href="https://hermes-agent.nousresearch.com/docs">
    Read the official Hermes Agent documentation from Nous Research
  </Card>

  <Card title="OpenClaw" icon="code" href="/platforms/openclaw">
    Explore OpenClaw for Claude-powered code generation
  </Card>

  <Card title="VPS Apps Overview" icon="server" href="/platforms/introduction">
    Learn about all VPS Apps and the RepoCloud manage page
  </Card>
</CardGroup>