> ## Documentation Index > Fetch the complete documentation index at: https://repocloud.io/docs/llms.txt > Use this file to discover all available pages before exploring further. # 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](https://repocloud.io/docs/deployment/ai-deploy.md): a plain Ubuntu 24.04 server is created and the [DevOps AI Agent](https://repocloud.io/docs/ai-agents/devops-ai-agent.md) 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](https://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](https://openrouter.ai/keys), create a key, and copy it. It starts with `sk-or-`. > [!NOTE] > > 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](https://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](https://repocloud.io/docs/ai-agents/custom-instructions.md) 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. > [!NOTE] > > 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](https://repocloud.io/docs/ai-agents/safety-and-control.md) 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@`, and then open `http://127.0.0.1:9119` in your browser. Send a message in the **Chat** tab to check the model connection. > [!WARNING] > > 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](https://hermes-agent.nousresearch.com/docs/user-guide/features/web-dashboard) 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@ 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. > [!NOTE] > > 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. > [!TIP] > > To set up Telegram, create a bot with [@BotFather](https://t.me/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](https://repocloud.io/docs/manage/vps-apps.md) 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@`) 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](https://repocloud.io/docs/ai-agents/troubleshooting.md) covers an address that does not open. > **The deployment failed or the agent seems stuck** > > [Troubleshooting the Chat](https://repocloud.io/docs/ai-agents/troubleshooting.md) 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 `. > **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 > **[Install Hermes Agent](https://repocloud.io/docs/deployment/ai-deploy.md)** > > Start an AI Deploy with Hermes Agent's repository > **[Hermes Documentation](https://hermes-agent.nousresearch.com/docs)** > > Read the official Hermes Agent documentation from Nous Research > **[OpenClaw](https://repocloud.io/docs/deployment/openclaw.md)** > > A personal AI assistant on your own server > **[Agent Apps](https://repocloud.io/docs/ai-agents/agent-apps.md)** > > How OpenClaw and Hermes Agent differ from the DevOps AI Agent > **[VPS Apps Overview](https://repocloud.io/docs/deployment/vps-apps.md)** > > Learn about VPS Apps and the RepoCloud manage page