How to Install Hermes Agent on a VPS (2026 Step-by-Step Guide) 

What you need to know:

• Hermes Agent is the open-source, self-improving AI agent from Nous Research, built to run on a CLI and reach you via messaging apps.
• Install it on any Linux, macOS, or WSL2 host with Git and Python 3.11+. The one-line installer is fastest on a VPS.
• A small VPS with 1 vCPU and 1 GB of RAM is enough when the LLM runs over an API. Plan for 2 GB or more for local tools or memory. A Cloud VPS 10 from Contabo is more than enough to get started.
• Docker is supported with a one-container-per-profile pattern, recommended for production.
• Connect Telegram, Discord, Slack, WhatsApp, Signal, or email through the gateway so the agent stays reachable off the terminal.
• Hermes Agent drives any Hermes AI model with a 64,000-token context window, including the Hermes 3 and Hermes 4 families.

Installing Hermes Agent on a VPS gives you a self-improving AI agent that lives on your server, remembers context across sessions, and is reachable through Telegram, Discord, or Slack. This guide walks through the install end to end on a fresh Contabo VPS running Ubuntu, covering Docker, the setup wizard, an LLM provider, and a systemd unit. Plan for about 15 minutes from a fresh SSH session to a running agent.

Before You Install: Hermes Agent in 60 Seconds

Hermes Agent is the open-source autonomous AI agent built by Nous Research. It runs as a CLI, exposes an OpenAI-compatible API server, and ships with built-in tools for terminal access, file ops, web search, persistent memory, and a self-improving skills loop.

What is Hermes Agent AI?

Hermes Agent AI is Nous Research’s term for the agent plus its full runtime: the CLI, the memory store, the skills system, and the gateway that connects it to your messaging apps. You bring your own LLM; Hermes provides everything that turns that LLM into a persistent, self-improving agent.

What sets the Hermes AI agent apart from a chatbot wrapper is the closed learning loop. It curates its own memory, persists skills across sessions, and builds a model of you and your work through Honcho-based user modeling. The longer it runs on your VPS, the more useful it gets.

Hermes Agent System Requirements in 2026

The Hermes AI agent framework itself is lightweight; the real resource cost is the LLM, the memory store, and any local tooling. A small VPS with 1 vCPU and 1 GB of RAM is enough for the API-only path. For a local LLM with Ollama on the same box, plan for more RAM and ideally a GPU.

The Hermes AI agent works with any model that supports a 64,000-token context window, including the Hermes 3 AI and Hermes 4 AI families. An entry-level Contabo Cloud VPS covers the API-only setup. For a local model alongside it, you can go for a higher-end plan with enough resources for a light Ollama model.

Step 1: Prepare Your VPS Environment

Provision a fresh Ubuntu VPS, then SSH in as root and update the system. Most install issues come from a stale package index or a missing dependency.

Connect via SSH and Update Packages

ssh root@your-vps-ip
apt update && apt upgrade -y
apt install -y git curl ca-certificates

Git is required. curl and ca-certificates handle the installer and HTTPS calls to your LLM provider. Python 3.11+ is needed but the installer provisions a managed Python through uv. If you plan to use the Hermes Agent AI Docker path, follow Step 2 instead.

Create a Non-Root User and Harden SSH

Don’t run Hermes Agent as root. Create a sudo user, then switch to it:

adduser hermes
usermod -aG sudo hermes
rsync --archive --chown=hermes:hermes ~/.ssh /home/hermes
su - hermes

Use SSH key-only login, disable password auth in /etc/ssh/sshd_config, and confirm a firewall is in place. Server hygiene matters once an autonomous Hermes AI agent acts on your behalf.

Step 2: Install Docker for Hermes Agent

You have two paths for the Hermes Agent install on a VPS: native with the one-line script, or a Hermes Agent AI Docker deployment. Docker is the recommended pattern for production because it isolates the agent and makes profile management cleaner.

Install Docker Engine from the official apt repository:

1. Add Docker’s GPG key and apt source.
2. Update the package index.
3. Install docker-ce, docker-ce-cli, containerd.io, and docker-compose-plugin.
4. Add your user to the docker group: sudo usermod -aG docker $USER.
5. Log out and back in, then confirm with docker --version.

Pick Docker for production; the native installer in Step 3 is faster for personal use. If your Contabo VPS shipped with the Docker Add-On, this step is already done.

Step 3: Deploy Hermes Agent with the Official Installer

Hermes Agent ships an official one-line installer maintained by Nous Research. It provisions Python via uv, installs Node.js, fetches dependencies, and creates the hermes CLI command. Source lives in the Hermes GitHub repository.

Option A: One-Line curl Installer (Native)

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

The first command installs the Hermes Agent AI runtime end to end, pulled from the Hermes GitHub repo. The source reload makes hermes available in the current shell. To skip the wizard, pass -s -- --skip-setup.

Option B: Docker Deployment (Recommended)

For a Hermes Agent AI Docker deployment, Nous Research recommends one container per profile, not the built-in multi-profile feature.

docker run -d \
  --name hermes-agent \
  --restart unless-stopped \
  -v hermes-data:/home/hermes/.hermes \
  -e HERMES_PROFILE=default \
  nousresearch/hermes-agent:latest

The named volume preserves memory, skills, and credentials between recreations. Pin the image tag for production.

Step 4: Run the Setup Wizard and Configure an LLM Provider

Hermes Agent needs an LLM behind it. The setup wizard handles provider selection, API key entry, and the default model:

hermes setup

The wizard asks for:

• Hermes Agent AI LLM — the model the agent will reason with.
• LLM Provider — OpenRouter, MiniMax, Nous Portal, Anthropic, OpenAI, a local Ollama endpoint, or any supported provider.
• API Key — stored locally under ~/.hermes.
• Model — must support at least a 64,000-token context window.
• Tools — toggle terminal access, file ops, web search, and memory.
• Profile name — useful when running multiple profiles on one host.

The Hermes AI agent re-reads its config on launch, so you can re-run any section with hermes setup model, hermes setup tools, or hermes config set.

Step 5: Verify Hermes Agent Is Running

Before you connect a messaging gateway, confirm the agent is healthy:

hermes doctor
hermes --version
hermes

The doctor command checks dependencies, Python version, model context window, and API connectivity. The third command drops you into an interactive session where a quick “hello” confirms the LLM round-trip. Fix anything hermes doctor flags before moving on.

Step 6: Connect a Messaging Gateway (Telegram, Discord, Slack)

A Hermes Agent AI assistant only earns its keep on a VPS if you can reach it from anywhere. The built-in gateway connects the agent to Telegram, Discord, Slack, WhatsApp, Signal, or email.

Telegram is the most common starting point because Telegram bots are the quickest to provision. The general flow:

1. Create a bot on the platform (Telegram BotFather, Discord developer portal, Slack app).
2. Copy the bot token and any required IDs.
3. Add them with hermes config set or your environment file.
4. Start the gateway with hermes gateway.
5. Send a test message and confirm Hermes replies.

Hermes AI Agent Telegram Integration

For Telegram, the gateway turns Hermes into a private bot you DM from your phone. Slack and Discord work the same way: the agent lives in a channel or DM and respects the scopes you grant during app setup. Treat bot tokens as production secrets.

Step 7: Run Hermes Agent as a 24/7 Service

A VPS is only useful if the agent stays online after reboots. For a Docker install, the restart policy is doing the work:

docker update --restart unless-stopped hermes-agent

For a native install, register Hermes as a systemd service:

# /etc/systemd/system/hermes.service
[Unit]
Description=Hermes Agent
After=network-online.target

[Service]
Type=simple
User=hermes
WorkingDirectory=/home/hermes
ExecStart=/home/hermes/.local/bin/hermes gateway
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target

Then enable and start it:

sudo systemctl daemon-reload
sudo systemctl enable --now hermes

This is the systemd shape that makes Hermes Agent AI automation reliable across reboots. Restart=always brings the agent back after a crash; only systemctl stop keeps it down on purpose.

Hermes Agent Install Checklist

A fast post-install audit:

• VPS on a supported OS (Linux or WSL2)
• System packages updated; git, curl, ca-certificates installed
• Non-root user created; SSH key-only login
• Docker installed (or skipped for native)
• Hermes Agent installed via script or Docker image
• hermes --version returns the expected version
• Setup wizard completed with LLM provider, API key, and model
• Chosen model supports a 64,000-token context window
• hermes doctor reports clean and the Hermes AI agent answered a test prompt
• At least one messaging gateway connected and tested
• systemd unit or Docker restart policy in place
• Memory volume (~/.hermes) backed up

Common Hermes Agent Install Mistakes to Avoid

• Native Windows install attempts. Hermes Agent does not run on native Windows. Use WSL2 or a Linux VPS.
• Wrong Python version. The installer wants Python 3.11+ via uv. System Python 3.10 or 3.9 causes silent dependency errors.
• Models with too-small context windows. Anything under 64,000 tokens drops context mid-task.
• Running as root. Hermes has terminal access as a built-in tool. Give it an unprivileged user.
• Skipping hermes doctor. Most install issues surface there first.
• Forgetting to persist ~/.hermes. It holds memory, skills, and credentials.
• Using the built-in multi-profile feature inside a Hermes Agent AI Docker container. Nous Research recommends one container per profile.
• Leaving the gateway exposed. Treat bot tokens and the API key as production secrets.

Why Contabo VPS/VDS Is a Good Fit for Hermes Agent

Hermes Agent runs comfortably on small hardware when the LLM is hosted, and scales up cleanly for local models. A basic Cloud VPS handles the API-only path at the price most providers charge for half the resources. For a local LLM next to the agent, a higher-end VPS or VDS gives you more resources to handle light inference, or for production workloads.

Portability matters too. The same installer and Docker image work across all Contabo VPS options, so you can start small and scale up later. The same goes for the wider open-source agent ecosystem: if you ever want to compare a Hermes AI agent setup with alternatives like OpenClaw, you can spin one up next to it on the same VPS without changing providers.

You can easily install Hermes on a Contabo VPS in one click from your Customer Control Panel. Simply reinstall the server with Hermes Agent selected as the application.

FAQ: Installing Hermes Agent on a VPS