📝 Tutorials
· 5 min read

How to Run Hermes Agent Locally: Setup on VPS, Docker, or Your Mac

Hermes Agent is designed to run on your own infrastructure. A $5 VPS, your MacBook, a Docker container, or a GPU cluster. Your data stays on your hardware, your agent talks to you via Telegram or Discord, and it learns from every interaction.

This guide covers every deployment option.

A $5 VPS from DigitalOcean, Hetzner, or Vultr is the sweet spot. Always-on, accessible from anywhere, costs almost nothing.

Prerequisites

  • VPS with 1GB+ RAM (2GB recommended)
  • Ubuntu 22.04+ or Debian 12+
  • SSH access

Installation

# SSH into your VPS
ssh root@your-vps-ip

# Install Hermes Agent
curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash

# Reload shell
source ~/.bashrc

# Run setup wizard
hermes setup

# Configure your model
hermes model openrouter:anthropic/claude-sonnet-5

# Start the messaging gateway
hermes gateway setup
hermes gateway start

Keep it running with systemd

# Create a systemd service
sudo tee /etc/systemd/system/hermes-gateway.service << EOF
[Unit]
Description=Hermes Agent Gateway
After=network.target

[Service]
Type=simple
User=$USER
WorkingDirectory=$HOME
ExecStart=$(which hermes) gateway start
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target
EOF

# Enable and start
sudo systemctl enable hermes-gateway
sudo systemctl start hermes-gateway

# Check status
sudo systemctl status hermes-gateway

Now your agent runs 24/7 and restarts on reboot.

Option 2: Docker

# Clone the repo
git clone https://github.com/NousResearch/hermes-agent.git
cd hermes-agent

# Copy env template
cp .env.example .env

# Edit .env with your API keys
nano .env

# Build and run
docker-compose up -d

# Check logs
docker-compose logs -f

Docker with messaging

# Start with gateway
docker-compose up -d

# Access the TUI
docker exec -it hermes-agent hermes

# Or talk via Telegram/Discord (configured in .env)

Option 3: macOS

# Install
curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash

# Reload shell
source ~/.zshrc

# Setup
hermes setup
hermes model openrouter:anthropic/claude-sonnet-5

# Start chatting
hermes

For 24/7 on macOS, use launchd:

# Create launchd plist
tee ~/Library/LaunchAgents/com.nousresearch.hermes-gateway.plist << EOF
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>com.nousresearch.hermes-gateway</string>
    <key>ProgramArguments</key>
    <array>
        <string>$(which hermes)</string>
        <string>gateway</string>
        <string>start</string>
    </array>
    <key>RunAtLoad</key>
    <true/>
    <key>KeepAlive</key>
    <true/>
</dict>
</plist>
EOF

# Load
launchctl load ~/Library/LaunchAgents/com.nousresearch.hermes-gateway.plist

Option 4: Windows (native)

# Install
iex (irm https://hermes-agent.nousresearch.com/install.ps1)

# Setup
hermes setup
hermes model openrouter:anthropic/claude-sonnet-5

# Start
hermes

Messaging gateway setup

Telegram

  1. Message @BotFather on Telegram
  2. Create a new bot: /newbot
  3. Copy the bot token
  4. Run hermes gateway setup and paste the token
  5. Start: hermes gateway start
  6. Message your bot to start chatting

Discord

  1. Create a Discord application at discord.com/developers
  2. Create a bot and copy the token
  3. Run hermes gateway setup and select Discord
  4. Paste the bot token
  5. Invite the bot to your server
  6. Start: hermes gateway start

Slack

  1. Create a Slack app at api.slack.com
  2. Enable Socket Mode
  3. Add bot scopes (chat:write, channels:history, etc.)
  4. Install to your workspace
  5. Run hermes gateway setup and paste the tokens

Model configuration

Using Nous Portal (easiest)

hermes setup --portal

One subscription, 300+ models, tool gateway included.

Using OpenRouter

hermes model openrouter:anthropic/claude-sonnet-5

Using OpenAI

hermes model openai:gpt-5.6-sol

Using a local model

hermes model custom:http://localhost:11434/v1

Scheduling tasks

# Daily morning digest at 9 AM
hermes cron add "Summarize open PRs and pending issues" --schedule "0 9 * * *"

# Monitor a deployment every 5 minutes
hermes cron add "Check if the production deployment is healthy" --schedule "*/5 * * * *"

# Weekly report every Monday
hermes cron add "Generate weekly code quality report" --schedule "0 9 * * 1"

Results deliver to your connected messaging platforms.

Production tips

1. Use a dedicated VPS: Don’t run Hermes Agent on the same server as your production app. Keep it isolated.

2. Set up monitoring: Use UptimeRobot or similar to monitor the gateway process.

3. Configure command approval: For production use, enable command approval so the agent asks before running destructive commands.

4. Use Docker for isolation: If you’re worried about the agent running arbitrary commands, use the Docker backend.

5. Back up your data: Hermes Agent stores memory, skills, and lessons in ~/.hermes/. Back this up regularly.

My take

The VPS option is the best for most people. A $5/month VPS gives you a 24/7 agent that talks to you via Telegram. The setup takes 10 minutes. The systemd service keeps it running.

Docker is good if you want isolation or already use Docker for other services. macOS is fine for development but not ideal for 24/7 (your laptop sleeps).

The messaging gateway is the killer feature. Talking to your agent via Telegram while it works on a cloud VM is a workflow that no other agent matches. It’s not just a coding tool. It’s a general-purpose assistant that lives where you do.

FAQ

How much does it cost to run Hermes Agent?

The agent itself is free (MIT license). You pay for: VPS ($5/month), model API calls (varies by provider and usage). Total: $10-50/month for most users.

Can I run Hermes Agent on a Raspberry Pi?

Yes, but it will be slow for complex tasks. The agent itself is lightweight, but it calls external model APIs, so the Pi’s CPU isn’t the bottleneck. Network latency is.

Does Hermes Agent need a GPU?

No. The agent calls external model APIs (OpenRouter, OpenAI, etc.). It doesn’t run models locally. A $5 VPS with 1GB RAM is sufficient.

How do I talk to my agent from my phone?

Set up the Telegram or Discord gateway. Then message your bot from the Telegram/Discord app on your phone. Your agent responds from wherever it’s running.

Can I run multiple Hermes Agent instances?

Yes. Each instance has its own ~/.hermes/ directory. You can run separate instances for different projects or purposes.

Is my data safe?

Your data stays on your own server. Nous Research doesn’t see your conversations, memory, or skills. The only external calls are to your chosen model provider.

📘

You might also like

How to Run Qwen 3.8 Max Locally: Hardware Requirements and Setup

Qwen 3.8 Max has 2.4T parameters. Here's what hardware you need to self-host it, quantization options, and when the API is a better choice.

How to Run GLM-5.2 Locally: Hardware, Quantization, and Setup Guide (2026)

Run Z.ai's GLM-5.2 (744B MoE, 40B active) locally with Ollama or llama.cpp. Hardware requirements, quantization options, and practical alternatives.

How to Run MiniMax M2.7 Locally: Hardware, GGUF Setup, and Performance Guide (2026)

Run MiniMax M2.7 (230B MoE, 10B active) locally with Ollama or llama.cpp. GGUF quantization options, hardware requirements, and speed benchmarks.

Ling 3.0 Flash for AI Agents: Hybrid Reasoning for Agent Workflows

How to build AI agents with Ling 3.0 Flash. Hybrid reasoning, function calling, and agent architectures explained with code examples.