Skip to the page content

VPS App GuidesHermes Agent

VPS App Guides

Hermes Agent

Install Hermes Agent, the open-source AI agent from Nous Research, on your own VPS with the DevOps AI Agent: a terminal chat, a web dashboard and messaging

Hermes Agent on RepoCloud

Hermes Agent is an open-source autonomous AI agent from Nous Research: it works toward a goal with its tools, can delegate to subagents, and checks dangerous commands with its approval rules. On RepoCloud you install it on your own VPS with AI Deploy: a plain Ubuntu 24.04 server is created and the DevOps AI Agent installs Hermes Agent on it while you follow the chat. The server has root access, SSH, a browser-based serial console, and the manage page.

  • Autonomous Execution

    Give Hermes a task and it works on it with its tools; /goal keeps it working across turns until a judge model decides the goal is done (20 turns by default), and a dangerous command waits for approval

  • Any Model

    Use OpenRouter or another provider, switch models with hermes model or /model, and give side tasks their own model

  • Web Dashboard

    A web dashboard, started with hermes dashboard, whose Chat tab embeds Hermes’s terminal interface, with pages for sessions, skills, configuration, and logs

  • Messaging Gateway

    Connect Telegram, Discord, Slack, WhatsApp, and Signal; each chat stays one continuous session

  • Memory and Skills

    Agent-curated memory with periodic nudges and autonomous skill creation after complex tasks — skills self-improve during use, and skill and memory writes can be staged for review with write_approval

  • Full Root Access

    SSH into your server, customize the environment, install tools, and manage everything at the OS level

Before You Start

Hermes needs a model to talk to, so have an API key from a model provider ready when the agent asks for it. The steps below use OpenRouter, which gives access to many models with one key:

  1. Create an OpenRouter Account

    Go to openrouter.ai and sign up or log in.

  2. Add Credits

    The account behind the key needs credits, and OpenRouter bills by use.

  3. Generate an API Key

    Go to openrouter.ai/keys, create a key, and copy it. It starts with sk-or-.

Hermes Agent is free: you pay your model provider for what the model uses. The tokens are billed to your OpenRouter account, separate from your RepoCloud balance, which pays for the server by the hour.

Installing Hermes Agent with AI Deploy

RepoCloud has no ready-made Hermes Agent template. Hermes Agent is installed on a blank Ubuntu server by the DevOps AI Agent, from Hermes Agent’s public repository. You need a RepoCloud account with a balance above $3.

  1. Open AI Deploy

    Go to repocloud.io/ai-deploy.

  2. Paste the Repository

    Enter Hermes Agent’s repository, https://github.com/NousResearch/hermes-agent, and a project name for your own reference.

  3. Choose a Tier

    Select a server tier; AI Deploy starts at Tier 2. A server can later move to a tier whose disk is the same size or larger, and a resize can be refused.

  4. Add Instructions (Optional)

    Custom instructions tell the agent what you expect. Examples: “Install Hermes Agent and set it up to use OpenRouter. Ask me for my OpenRouter API key when you need it.” and “Do not expose Hermes’s web dashboard to the public internet.”

  5. Deploy and Follow the Chat

    Click Deploy. A dedicated IPv4 address is included with every VPS at no extra charge. The chat opens once the server is ready, and AI-assisted deployment typically takes 5–15 minutes. The agent is instructed to ask you for any key it needs, and to report what it installed and any logins it created.

The agent is an AI and can make mistakes: read what it reports, steer it in the chat when something is off, and take a snapshot before a risky change. A key you paste into the chat reaches the AI model that runs the agent, like everything else you write there: Safety and Control explains who sees what.

First-Time Setup

  1. Check the Install

    Connect over SSH and run hermes status and hermes doctor: they show what Hermes will use and what is wrong.

  2. Start a Chat

    Run hermes on the server to start chatting with the agent in the terminal.

  3. Open the Web Dashboard (Optional)

    hermes dashboard starts Hermes’s web dashboard, which listens on 127.0.0.1, port 9119, by default: the server itself. To open it from your own computer, use an SSH tunnel, for example ssh -L 9119:127.0.0.1:9119 root@<your-ip>, and then open http://127.0.0.1:9119 in your browser. Send a message in the Chat tab to check the model connection.

Hermes’s dashboard can read and change your API keys and run commands. Hermes’s own documentation says that it requires a sign-in before it listens on any address other than the server itself, that its username and password sign-in is meant for a trusted network or a VPN, and that it is not suitable for direct exposure to the public internet; it recommends an SSH tunnel or a VPN instead. Read Hermes’s dashboard documentation before the dashboard is reachable from outside the server, and ask the agent how it set the dashboard up.

Configuring Models

Where Hermes Keeps Its Settings

Hermes keeps secrets in ~/.hermes/.env (the OpenRouter key is OPENROUTER_API_KEY) and settings in ~/.hermes/config.yaml. To check that the key line exists without printing the key, run:

bash
grep -c '^OPENROUTER_API_KEY=' ~/.hermes/.env
hermes status

A result of 1 means the line is present, and hermes status shows what Hermes will use.

With OpenRouter, the model configuration in ~/.hermes/config.yaml looks like this (the model name is an example):

yaml
model:
  provider: openrouter
  default: anthropic/claude-opus-4.6

Read the live value with hermes config get model --json.

Switching Models

Change the active model via SSH:

bash
ssh root@<your-ip>
hermes config set model anthropic/claude-opus-4.6

A model change applies to new sessions. Or use the interactive model selector:

bash
hermes model

hermes model walks you through the provider (and its sign-in) and then the models of that provider’s curated catalog, and writes the choice to config.yaml. New sessions use it; inside a chat, /model switches that chat. The dashboard has a model picker too, which lists the curated models of each provider and applies to new sessions.

Hermes needs a model with a context window of at least 64,000 tokens and rejects a smaller one at startup. Most hosted models meet this.

Auxiliary Models

Hermes can give side tasks (title generation, compression, vision, and more) their own model. A block that Hermes cannot resolve runs on the main model:

yaml
auxiliary:
  title_generation:
    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, or run hermes model and choose “Configure auxiliary models…”.

Using Hermes Agent

Starting Conversations

In the dashboard’s Chat tab, type a task or question. Hermes works with its tools (terminal, files, web, browser, and more), can keep a to-do list, ask you a question, or delegate to a subagent, and checks a dangerous command with its approval rules. The Chat tab is Hermes’s terminal interface in the browser.

Tool Framework

Hermes’s tools are grouped in toolsets:

  • Terminal & Files — run shell commands on the VPS and read, write, and manage files
  • Web — search the internet for information

The other toolsets are Browser, Media, Agent orchestration, Memory & recall, Automation, and Integrations (MCP servers and plugin tools). X Search needs xAI credentials.

Configure tool access via SSH:

bash
hermes tools

hermes tools --summary lists what is enabled.

Skills System

Hermes creates and updates skills (documents in ~/.hermes/skills/) after complex tasks. The writes can be staged for your review with write_approval. You can browse skills from the dashboard.

Session Management

  • Conversations are stored in a local database and can be resumed
  • session_search finds past messages with full-text search and returns the messages themselves, with no summary
  • Use /resume, /sessions, /history, /title, and /branch to manage sessions

Messaging Integrations

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

bash
hermes gateway setup

To keep the gateway running on the server, install the system service and start it. You are root on the server, so sudo is not needed:

bash
hermes gateway install --system
hermes gateway start --system

Platforms include:

  • Telegram — create a bot with @BotFather; the setup asks for its token and the user IDs that may talk to it
  • Discord — connect a bot to your Discord server
  • Slack — connect as a bot to a Slack workspace
  • WhatsApp — connects through Hermes’s built-in bridge, which emulates a WhatsApp Web session; it is not the official Business API and carries a ban risk
  • Signal — needs the separate signal-cli daemon (Java 17 or later)

Each chat on a messaging platform is one continuous session that is not reset after inactivity. In the hermes command-line interface, /handoff moves a CLI session to a platform’s home channel.

To set up Telegram, create a bot with @BotFather, then run hermes gateway setup and enter the bot token and the user IDs that may talk to the bot (TELEGRAM_ALLOWED_USERS). Without an allowed user the bot ignores everyone. Then start the gateway as above.

Managing the Server

Your server has its own manage page in the RepoCloud dashboard: its address and SSH command, power controls, the browser console, SSH keys, resizing, snapshots, usage charts, a custom domain on a server that has that section, and the option to delete it. Managing VPS Apps describes each part, and Resume Chat on the same page reopens the chat with the DevOps AI Agent. Take a snapshot before you make risky changes, so you can roll back.

Troubleshooting

I cannot open the web dashboard

By default Hermes’s dashboard listens on 127.0.0.1, port 9119, so it is not reachable from outside the server: use an SSH tunnel (ssh -L 9119:127.0.0.1:9119 root@<your-ip>) and open http://127.0.0.1:9119 on your own computer. If the agent set it up on another address, Hermes requires its own sign-in there; resume the chat and ask the agent how it did it. Troubleshooting the Chat covers an address that does not open.

The deployment failed or the agent seems stuck

Troubleshooting the Chat covers a deployment that failed, an agent that seems stuck or asks for something, a server that does not answer, and a missing Resume Chat button.

Agent not responding

SSH into the server and check that the key line exists without printing it: grep -c '^OPENROUTER_API_KEY=' ~/.hermes/.env (1 means present), then run hermes status and hermes doctor. If the line is missing, re-add it with hermes config set OPENROUTER_API_KEY sk-or-.... Also check that your OpenRouter account has credits.

Model rejected due to context length

Hermes needs at least 64,000 tokens of context and rejects a smaller model at startup. Pick a model with a larger window with hermes model or hermes config set model <model>.

High OpenRouter costs

Choose the model with hermes model or /model, and give side tasks a different model (auxiliary.title_generation, auxiliary.compression). Read your usage in your OpenRouter account.

Messaging gateway not connecting

Ensure the bot token or API credentials are correct and that the user IDs that may talk to the bot are set. SSH in and check hermes gateway status (hermes gateway status --system for a system service). Restart with hermes gateway restart. Verify that the VPS has outbound internet access to the messaging platform’s API endpoints.

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 (each platform admits only the users you name)
  • People who want to choose the model per chat with /model and give side tasks their own model
  • Automation builders who need an agent for multi-step workflows involving terminal commands, file changes, and scheduled jobs

Next Steps

Type to search the documentation.

Get started for free

Sign up and get free credit for your first 30 days at RepoCloud

Get Started

This offer applies to new customers