How to install Hermes Agent on a VPS

Objective

Hermes Agent is an open-source autonomous AI agent (MIT license) built by Nous Research. Unlike a simple chatbot, it keeps persistent memory across sessions, creates its own skills from experience, and runs scheduled tasks 24/7 through its built-in cron scheduler.

This guide uses OVHcloud AI Endpoints as the inference provider: the agent runs on your VPS while the language model is served from OVHcloud's French datacenters through an OpenAI-compatible API. Your requests never transit through a non-European provider.

This method provides:

• An always-on agent reachable from Telegram (or Discord, Slack, WhatsApp, Signal)
• Sovereign, GDPR-compliant inference via AI Endpoints (no data is used to train the models)
• Recurring tasks (monitoring, reports, reminders) executed automatically through the built-in cron
• A systemd service that survives VPS reboots

The target architecture:

Telegram / CLI
     ↓
Hermes Gateway (systemd service on the VPS)
     ↓
OVHcloud AI Endpoints (gpt-oss-120b)

This guide explains how to deploy Hermes Agent in production on a VPS with OVHcloud AI Endpoints.

Requirements

• An OVHcloud VPS (Debian 12 or Ubuntu 22.04+). Refer to our guide "Getting started with a VPS".
  • Minimum configuration: 2 GB RAM, 1 vCPU, 10 GB disk (chat-only usage).
  • Recommended configuration: 4 GB RAM, 2 vCPU, 20 GB disk if you enable browser automation (the browser tool), which raises peak memory usage to 1.2–1.8 GB.
• SSH access to your VPS.
• An OVHcloud AI Endpoints API key. Refer to our guide "AI Endpoints - Getting started" to generate one.
• (Optional, needed from Step 5 onwards) A Telegram bot token obtained from @BotFather, if you want to talk to the agent from Telegram.

Instructions

Step 1 - Preparing the VPS

Connect to your VPS over SSH. Replace VPS_IP with the real address, and ubuntu with the user corresponding to your OS:

ssh ubuntu@VPS_IP

Update the system and install Git, the installer's only software prerequisite, along with cURL, which downloads the install script (Python 3.11+, Node.js, ripgrep and ffmpeg are fetched automatically):

sudo apt update && sudo apt upgrade -y
sudo apt install -y git curl

As a security measure, create a dedicated non-sudo user that will run the agent:

sudo adduser --disabled-password --gecos "" hermes
sudo su - hermes

Step 2 - Installing Hermes Agent

As the hermes user, run the official installer:

curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash

Reload your shell then verify the installation:

source ~/.bashrc
hermes doctor

The hermes doctor command checks dependencies and configuration. At this stage, no large language model (LLM) provider is configured yet — that is what the next step does.

Step 3 - Configuring the OVHcloud AI Endpoints provider

Hermes Agent works with any OpenAI-compatible endpoint. The most reliable approach is to let the setup wizard generate the files rather than editing them by hand: the syntax evolves between versions, the wizard always writes the one matching your version, and it verifies the endpoint along the way.

Launch the full wizard:

hermes setup

Choose Full setup (manual provider configuration), then custom (direct API) in the provider list. Enter:

• API base URL: https://oai.endpoints.kepler.ai.cloud.ovh.net/v1
• API key: your AI Endpoints API key. The wizard immediately verifies the endpoint and should print a Verified endpoint via .../v1/models confirmation line. If that line does not appear, the key is invalid: do not continue, regenerate it (see the troubleshooting in Step 4).
• API compatibility mode: 2 (Chat Completions)
• Model: select gpt-oss-120b from the displayed catalog list.
• Context length: type 131000 rather than relying on auto-detection. Hermes requires at least 64,000 tokens of context for agent use, and a wrong auto-detection silently degrades the agent.
• Display name: ovhcloud
• Terminal backend: Local (default), or Docker/Podman to run the agent's commands in an isolated container — recommended if Docker is installed on the VPS.

The wizard saves the configuration to ~/.hermes/config.yaml as a custom_providers entry. Verify the result:

cat ~/.hermes/config.yaml

You should get a block of this shape (the provider name and the environment variable name are derived from the endpoint URL):

custom_providers:
  - name: ovhcloud
    base_url: https://oai.endpoints.kepler.ai.cloud.ovh.net/v1
    key_env: HERMES_CUSTOM_OAI_ENDPOINTS_KEPLER_AI_CLOUD_OVH_NET_API_KEY
    model: gpt-oss-120b
    api_mode: chat_completions
    models:
      gpt-oss-120b:
        context_length: 131000

If the context_length: 131000 line is missing, add it as shown: Hermes requires at least 64,000 tokens of context for agent use, and the gpt-oss-120b model served by AI Endpoints offers 131,000; declaring the value explicitly avoids an incorrect auto-detection.

Finally, check where the wizard stored your API key:

grep -l "API_KEY" ~/.hermes/.env ~/.hermes/config.yaml 2>/dev/null
chmod 600 ~/.hermes/.env

Step 4 - Verifying the model connection

Start a test session:

hermes chat

Ask a simple question, then one that triggers a tool call, for example:

What time is it on this server? Use the terminal to check.

The agent should run a command (for example date) and answer with the result. This confirms that function calling works through AI Endpoints.

Also verify in the logs that requests are sent to the OVHcloud endpoint and not to a fallback provider:

grep -r "oai.endpoints.kepler" ~/.hermes/logs/ | tail -n 5

If requests do not reach the expected endpoint, run hermes model and check that the Active provider is your custom_providers entry, not a fallback provider such as OpenRouter.

On a 401 or 403 error, test the key outside Hermes to isolate the cause:

source ~/.hermes/.env
curl -s -o /dev/null -w "HTTP %{http_code}\n" \
  https://oai.endpoints.kepler.ai.cloud.ovh.net/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $HERMES_CUSTOM_OAI_ENDPOINTS_KEPLER_AI_CLOUD_OVH_NET_API_KEY" \
  -d '{"model":"gpt-oss-120b","messages":[{"role":"user","content":"ping"}],"max_tokens":5}'

• HTTP 200: the key is valid; the problem is on the Hermes side — look for a leftover key (see the "one key" warning in Step 3).
• HTTP 401/403: the key is invalid on the OVHcloud side — regenerate it from the AI Endpoints section of your Public Cloud project.

Step 5 - Connecting the Telegram gateway

Creating the Telegram bot

The token is obtained from @BotFather, Telegram's official service for creating bots — an account operated by Telegram itself, and the only channel that issues bot tokens:

1. In Telegram, open a chat with @BotFather (check the verification badge: impersonator accounts exist).
2. Send the /newbot command.
3. Give a display name (for example My Hermes agent), then a unique username ending in bot (for example myagent_hermes_bot).
4. BotFather replies with the bot token, of the form 123456789:AAEXXXXXXXX. This is what the wizard in the next section will ask for.

Configuring the gateway

Launch the messaging platform setup wizard:

hermes gateway setup

Select Telegram and enter the token provided by @BotFather. The wizard then offers the other platforms (WhatsApp, Discord, Slack, etc.): answer n to those you do not use — a platform that is enabled but misconfigured can prevent the whole gateway from starting. The configuration is saved in ~/.hermes/config.yaml and ~/.hermes/.env.

Start the gateway manually for a first test:

hermes gateway run

In the first lines of output, check that Telegram connects, then send a message to your bot from Telegram (search for its @myagent_hermes_bot username and open the chat). Received messages appear in the gateway terminal — keep it visible during the test. On first contact, if you have not set an allowlist, Hermes replies with a pairing code. In a second terminal, run the command shown in the logs (of the form hermes pairing approve telegram <CODE>) to authorise your account. Once the exchange works, stop the gateway (Ctrl+C) and move on to the next step to make it permanent.

Step 6 - Running Hermes as a systemd service

Hermes installs its own systemd service, in user mode. Still as the hermes user:

hermes gateway install

Answer Y to both questions (start now, and start automatically on boot). The command installs the service at ~/.config/systemd/user/hermes-gateway.service and enables systemd lingering (✓ Linger enabled), which keeps the service running after you log out of SSH and restarts it automatically when the VPS reboots.

Check the service's status and logs:

systemctl --user status hermes-gateway
journalctl --user -u hermes-gateway -f

The agent is now permanently reachable from Telegram and will survive VPS reboots.

Step 7 - Scheduling a recurring task

Hermes ships its own scheduler, separate from the system crontab: jobs are stored in ~/.hermes/cron/jobs.json, and the gateway ticks them every 60 seconds — so they only run while the Step 6 service is up.

The most direct way is the dedicated command family:

hermes cron create "every 2h" "Check <your topic> and send me a summary on Telegram"
hermes cron list
hermes cron remove <job_id>

You can also phrase the request in natural language from Telegram ("Every Monday at 8am, search this week's news about <your topic> and send me a 10-line summary"): the agent then creates the job through its internal cronjob_manage tool.

Go further

How to secure a VPS

AI Endpoints - Getting started

Official Hermes Agent documentation

How to install OpenClaw on a VPS

Join our community of users.