How to Self-Host Hermes Agent: Complete Beginner Guide

Q: How do I self‑host Hermes Agent?

Run the official one‑line installer: curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash. After installation, configure your model provider with hermes model, run hermes doctor to verify the setup, and start chatting with hermes.

Q: Do I need Docker to install Hermes Agent?

No. The official beginner path uses a one‑line installer that handles all dependencies. Docker is optional and available for users who prefer container‑level isolation, but it's not the default method.

Q: How do I make Hermes Agent always‑on?

Use hermes gateway install to create a systemd user service, then enable it with systemctl --user enable --now hermes-gateway. This keeps the agent running after SSH logout and restarts it automatically on crash or reboot.

Q: How do I back up Hermes Agent?

Since v0.9.0, Hermes includes a hermes backup command that creates a timestamped snapshot of your entire ~/.hermes/ directory. Schedule it with cron and rsync the backups off‑server.

Q: What does it cost to self‑host Hermes Agent?

The software is free and open‑source (MIT license). You pay for the VPS (roughly $5–12/month) and LLM API usage, which varies by model and volume. Local models via Ollama can eliminate API costs but require a GPU for good performance.

Q: Should beginners self‑host Hermes Agent?

Yes — for testing and learning, the one‑line installer makes it beginner‑friendly. For always‑on use, team workflows, or business reliance, managed hosting is usually the easier and safer path.

Self Host ChallengesAgntable · April 28, 2026 · 16 min read

Can you self-host Hermes Agent?

Yes - you can self-host Hermes Agent on Linux, macOS, WSL2, Android via Termux, or a VPS. The official installer is a one-line command that handles Python 3.11, Node.js, ripgrep, ffmpeg, and the global hermes CLI setup automatically. On a VPS with a non-root user and basic firewall, the whole install takes under five minutes.

For testing, your own laptop is fine. For a genuine always-on assistant, a VPS or managed infrastructure is the practical next step. The important question is not just "Can I install Hermes Agent?" - it's whether you want to maintain the server yourself or simply start using the agent. That's what this guide will help you decide.

If you're completely new to Hermes and want to understand what it does before installing, start with our beginner explainer: What is Hermes Agent?

Who should self-host Hermes Agent?

Self-hosting is a good fit if you:

Are comfortable using a terminal and SSH
Want full control over your infrastructure, API keys, and models
Enjoy learning how the system works under the hood
Need custom configurations that a managed platform might not expose

Self-hosting may not be the best path if you:

Don't want to manage Linux servers, updates, or dependency issues
Need Hermes online 24/7 with guaranteed uptime
Expect backups and monitoring to be handled for you
Are you setting it up for a team or business workflow where downtime costs real time

If that second list sounds more like your situation, self-hosting Hermes Agent without the setup pain is a pragmatic alternative. You still get the persistent agent with memory and skills - just without the infrastructure chores.

Before you install: pick your hosting environment

There are three common paths. Each serves a different goal.

Option	Best for	Main trade-off
Local machine	Testing, learning the basics	Not always-on; dies when your laptop sleeps
VPS	Technical users who want full control	You manage everything: updates, backups, security, monitoring
Managed hosting	Users who want Hermes to run reliably without server work	Less low-level control; faster time-to-value

Start local to learn. Move to a VPS when you're ready for 24/7 uptime. Choose managed hosting when you realise you'd rather use the agent than maintain it.

Option 1: Install Hermes Agent locally (the quick test)

This is where every beginner should start. You'll verify that Hermes works before committing to a server.

Prerequisites

The only hard prerequisite is Git. The official installer provisions Python 3.11 (via uv), Node.js v22, ripgrep, and ffmpeg automatically. Hermes supports Linux, macOS, WSL2, and Android/Termux. Native Windows is not supported - use WSL2 on Windows machines.

The one-line installer

Open your terminal and run:

Install Hermes

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

When it finishes, reload your shell:

Reload shell

source ~/.bashrc   # or source ~/.zshrc

Check that the install succeeded:

Verify install

hermes --version

You should see something like Hermes Agent v0.9.0, along with Python and project path details.

Run the diagnostic tool

Before having your first conversation, run hermes doctor. It checks that the model connection, memory system, and tools are all healthy. Look for green checkmarks. If anything shows red, fix it before moving on.

Set up a model provider

Hermes doesn't ship with a built-in model - you need to connect it to one. Run:

Model wizard

hermes model

This opens an interactive wizard. You can choose OpenRouter (200+ models with a single key), Anthropic, OpenAI, Google Gemini, xAI Grok, or Ollama for local models, or any OpenAI-compatible endpoint. Hermes requires a model with at least 64,000 tokens of context; most hosted models meet this easily.

After selecting a provider and entering your API key, start chatting:

Start Hermes

hermes

That's it. You've completed a basic Hermes Agent install guide on your local machine.

When local install makes sense - and when it doesn't

A local install is perfect for testing, learning commands, and trying different providers. It becomes a limitation when your laptop is turned off, your internet changes, you want remote access via Telegram or Slack, or you need scheduled tasks to run reliably. Hermes is most useful when it can stay alive - that's why most people move to a VPS next.

Option 2: Self-host Hermes Agent on a VPS

A cloud VPS gives you an always-on home for your agent. The setup is straightforward: spin up a VM, create a non-root user, install Hermes, pick a provider, configure the messaging gateway, and wrap everything in a systemd service.

Step 1: Choose and provision a VPS

Pick a provider - DigitalOcean, Linode, Vultr, Hetzner, or Hostinger all work well. Use Ubuntu 22.04 or 24.04 LTS. The minimum spec is 2 GB RAM and 10 GB disk. For a smoother experience with the web dashboard and multiple gateway sessions, go with 4 GB RAM and 20 GB+ disk.

Step 2: Initial server hardening

SSH into your server as root and create a dedicated user for Hermes:

Create user

adduser hermes --disabled-password --gecos ""
usermod -aG sudo hermes

Copy your SSH key so you can log in as the hermes user, then switch to that account:

Switch user

su - hermes

Set up a firewall that allows only SSH inbound:

Firewall setup

sudo apt-get install -y ufw
sudo ufw default deny incoming
sudo ufw default allow outgoing
sudo ufw allow ssh
sudo ufw --force enable

The Hermes gateway makes outbound connections to messaging APIs, so no inbound ports beyond SSH need to be open.

Step 3: Install Hermes

Run the same one-line installer, this time on your VPS:

Install on VPS

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

Step 4: Configure your LLM provider

Lock down the environment file and add your API key:

Edit env

chmod 600 ~/.hermes/.env
nano ~/.hermes/.env

Add your key (for example, with OpenRouter):

OPENROUTER_API_KEY=sk-or-your-key-here

Save and exit. Then set the default model:

Set model

hermes config set model.provider openrouter
hermes config set model.default anthropic/claude-sonnet-4

Test the connection:

Test model

hermes -m "What is 2+2? Reply with just the number."

If you get a response, the provider is configured. This completes your basic Hermes Agent VPS setup.

Step 5: Connect the messaging gateway

The gateway lets you talk to Hermes from Telegram, Discord, Slack, or any of 16 supported platforms. To add Telegram:

Open env

nano ~/.hermes/.env

Add:

TELEGRAM_BOT_TOKEN=your-bot-token-from-botfather
TELEGRAM_ALLOWED_USERS=your-telegram-user-id

The TELEGRAM_ALLOWED_USERS variable is critical - without it, anyone who finds your bot can send it commands. Start the gateway to verify it works:

Start gateway

hermes gateway

Send a test message from Telegram. You should see the message in your terminal and receive a response. Press Ctrl+C to stop once you've confirmed it works.

Step 6: Run Hermes as a systemd service (always-on agent)

Running hermes gateway in a terminal session means it stops when you disconnect. A systemd user service keeps it alive after logout and restarts it automatically after crashes or reboots.

Hermes has a built-in command for this:

Install service

hermes gateway install

This creates the service file and enables lingering, which keeps user services running after SSH logout. Start the service:

Enable service

systemctl --user enable --now hermes-gateway
systemctl --user status hermes-gateway

Look for Active: active (running). If it shows failed, check the logs:

Gateway logs

journalctl --user -u hermes-gateway -f

You now have an always-on agent that survives reboots and SSH disconnects.

What about Docker?

The official beginner path is the one-line installer. Docker is available, and some users prefer it for the container-level isolation - Hostinger, for example, offers a Docker template that deploys Hermes with one click from their VPS catalogue. Community-maintained Docker images also exist and can be useful if your broader stack already runs on Docker. But for a beginner's first setup, the installer is simpler and the one the official docs recommend. Don't add Docker complexity unless it solves a real problem you already have.

Environment variables: your control panel

Your ~/.hermes/.env file is the single source of truth for secrets. The ~/.hermes/config.yaml holds structured settings like provider routing, MCP servers, and toolset configuration. Never put API keys in config.yaml - keys stay in .env, and .env should have chmod 600 permissions. Key variables worth setting early:

Variable	What it does
`OPENROUTER_API_KEY`	Your model-provider API key
`LLM_MODEL`	Default model identifier
`TELEGRAM_BOT_TOKEN`	Telegram bot token for messaging
`TELEGRAM_ALLOWED_USERS`	Whitelist: comma-separated Telegram user IDs
`APPROVAL_MODE`	`ask` (recommended), `smart`, or `off`

Keep approval mode on ask for any VPS deployment. It prompts you before the agent runs potentially dangerous commands. Telegram and Slack show native approval buttons, so you don't even need to type a response.

The real maintenance burden

Installing Hermes is quick. Keeping it healthy for months is the real job - and it's the part most tutorials skip.

Updates: Hermes has shipped nine releases in seven weeks. Run hermes backup first, then hermes update, then hermes config migrate, and hermes doctor to apply any new configuration defaults. Restart the gateway service afterwards.
Backups: Your agent's brain lives in ~/.hermes/ - memories, skills, sessions, configuration, and persona. Since v0.9.0, Hermes includes a built-in backup command: hermes backup creates a timestamped snapshot. Schedule daily backups with cron and sync them off-server. A backup kept only on the same VPS doesn't protect against disk failure.
Security: You're running an agent with shell access on a public server. Use a non-root user, restrict SSH to key-only authentication, keep UFW active, lock .env to 600 permissions, whitelist messaging-platform user IDs, and audit the skills directory periodically as you would any code.
Monitoring: Check that the gateway service is running, disk space isn't filling up, and API costs aren't spiralling. A simple cron job that pings the health endpoint is enough for early detection.
Cost tracking: API costs are usage-based and can surprise you. A VPS might cost $5-6/month, but LLM API calls vary wildly depending on model and volume. Some users report that 73% of API call cost comes from fixed overhead like tool definitions and system prompts alone - switching to a provider-agnostic setup with hermes model gives you flexibility to optimise.

Self-Hosting vs Managed Hosting

Self-hosting gives you full sovereignty. Your data, your server, your rules. A VPS costs a few dollars a month, and you learn a lot about how the agent works under the hood.

The hidden cost is time - hours spent on updates, backups, gateway debugging, security patches, and troubleshooting when something breaks. If you enjoy that work, it's a rewarding hobby. If you'd rather focus on using the agent for your actual projects, the VPS vs managed hosting for Hermes Agent decision tips toward managed hosting.

With Managed Hermes Agent Hosting, the setup, updates, backups, gateway configuration, and monitoring are handled for you. You still get a persistent agent with memory, skills, and your choice of model - just without the system administration. For most non-technical users and teams, it's the more practical path.

If you're ready to skip the server work, you can deploy Hermes Agent on managed infrastructure and start using it today, with memory, skills, and 24/7 availability included.

Common beginner mistakes (and how to avoid them)

Installing before deciding the goal. Decide first: testing, personal use, always-on assistant, or team workflow? Your goal determines your hosting method.
Ignoring backups until it's too late. Hermes becomes more valuable as it builds memory. If those files matter, back them up from day one.
Exposing services without security. Don't open anything publicly until you understand authentication, firewall rules, and platform permissions. An agent with shell access demands caution.
Overcomplicating the first setup. Beginners often try to add Docker, Open WebUI, messaging, voice, MCP tools, and scheduled tasks all on day one. Don't. Install Hermes, configure a model, and run a basic conversation. Expand later.
Underestimating ongoing maintenance. The difference between "it runs" and "it runs reliably for months" is where most of the work lives.

Recommended beginner path

Test locally. Run the one-line installer on your laptop. Have a few conversations. Learn the commands.
Move to a VPS if you want full control and 24/7 uptime. Start simple - don't add every integration at once.
Add the gateway or Open WebUI later, once the agent is stable.
Decide if maintenance is worth your time. After a few weeks of self-hosting, ask: "Is this infrastructure work worth my time, or would I rather focus on using the agent?" Your honest answer tells you whether to stick with self-hosting or switch to managed hosting.

Conclusion

You can absolutely self-host Hermes Agent, and the official one-line installer makes the first setup faster than most open-source AI tools. But installation is only the beginning. Keeping an always-on agent running reliably requires ongoing attention to updates, backups, security, and monitoring.

If you're technical and enjoy the process, self-hosting on a VPS is a great learning experience and gives you full control. If you'd rather spend your time using the agent - building workflows, automating tasks, and letting it learn how you work - Managed Hermes Agent Hosting removes the infrastructure burden so the agent simply stays alive and keeps getting better.

FAQs

How do I self-host Hermes Agent?

Run the official one-line installer: curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash. After installation, configure your model provider with hermes model, run hermes doctor to verify the setup, and start chatting with hermes.

Can I install Hermes Agent on Windows?

Native Windows is not supported. Windows users should install WSL2 first, then run the installer inside the WSL2 terminal.

Do I need Docker to install Hermes Agent?

No. The official beginner path uses a one-line installer that handles all dependencies. Docker is optional and available for users who prefer container-level isolation, but it's not the default method.

Can I host Hermes Agent on a VPS?

Yes. A VPS running Ubuntu with at least 2 GB RAM is the most common way to keep Hermes running as an always-on assistant. You'll manage updates, backups, and security yourself.

How do I make Hermes Agent always-on?

Use hermes gateway install to create a systemd user service, then enable it with systemctl --user enable --now hermes-gateway. This keeps the agent running after SSH logout and restarts it automatically on crash or reboot.

How do I back up Hermes Agent?

Since v0.9.0, Hermes includes a hermes backup command that creates a timestamped snapshot of your entire ~/.hermes/ directory. Schedule it with cron and rsync the backups off-server.

What does it cost to self-host Hermes Agent?

The software is free and open-source (MIT license). You pay for the VPS (roughly $5-12/month) and LLM API usage, which varies by model and volume. Local models via Ollama can eliminate API costs but require a GPU for good performance.

Should beginners self-host Hermes Agent?

Yes - for testing and learning, the one-line installer makes it beginner-friendly. For always-on use, team workflows, or business reliance, managed hosting is usually the easier and safer path.