Installing Hermes Agent on a $5 VPS: A Step-by-Step Setup Guide
Stand up a persistent Claude agent on a $5 Hetzner or DigitalOcean VPS in under 15 minutes. Full install walkthrough with config.
Stand up a persistent Claude agent on a $5 Hetzner or DigitalOcean VPS in under 15 minutes. Full install walkthrough with config.
Hermes Agent was built to live on a server, not a laptop. That is the whole point: an agent that remembers what it learned, keeps cron jobs running, and stays reachable over Telegram while you are on a flight. The good news is that the hardware bar is absurdly low. A $5 VPS from Hetzner or DigitalOcean runs it comfortably.
This tutorial walks through the full install on a fresh Ubuntu 24.04 box, from provisioning through your first hermes chat against Claude Sonnet 4.6. Assume roughly 15 minutes if you already have SSH keys in hand.
curl | bash from the official GitHub repo.~/.hermes/config.yaml; memory and skills live under ~/.hermes/.ANTHROPIC_API_KEY or a logged-in Claude Code credential store to talk to Claude.Before we touch a terminal, have these ready:
On Hetzner Cloud: create a new project, click Add Server, pick Ubuntu 24.04, select the CX11 type in the location nearest you (4 GB RAM, 1 vCPU, 20 GB SSD, around $4.51/mo). Paste your SSH key under the SSH Keys section. Give it a hostname like hermes-01 and hit Create.
On DigitalOcean: Droplets > Create Droplet > Ubuntu 24.04 > Basic Shared CPU > $6/mo tier. Same SSH key workflow.
You should be SSH-ready in under 60 seconds.
ssh root@YOUR_SERVER_IP
Hermes needs Python 3.11 or newer. Ubuntu 24.04 ships with 3.12 by default. For 22.04 you may need to add the deadsnakes PPA.
apt update && apt upgrade -y
apt install -y python3 python3-pip python3-venv git curl tmux
python3 --version
Create a non-root user for day-to-day agent work. Running autonomous agents as root is the kind of decision your future self files complaints about.
adduser --disabled-password --gecos "" hermes
usermod -aG sudo hermes
rsync --archive --chown=hermes:hermes ~/.ssh /home/hermes
su - hermes
The rest of the tutorial assumes you are in a shell owned by the hermes user.
This is the single command straight from the GitHub repo:
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash
The script provisions a Python virtual environment, installs the hermes-agent package from PyPI (currently 0.10.0), pulls the bundled skill library, and adds three entry points to your PATH:
hermes for the day-to-day CLIhermes-agent as an aliashermes-acp for the Agent Communication Protocol adapterVerify the install:
hermes --version
which hermes
If hermes is not found, either restart the shell or source your updated profile with source ~/.bashrc.
Hermes creates ~/.hermes/ on first run. The config file we care about is ~/.hermes/config.yaml. Open it and set the default provider and model:
model:
provider: "anthropic"
default: "claude-sonnet-4-6"
Export your Anthropic key for the shell session, and add it to ~/.bashrc so it persists:
export ANTHROPIC_API_KEY=sk-ant-***
echo 'export ANTHROPIC_API_KEY=sk-ant-***' >> ~/.bashrc
If you already have Claude Code logged in on this machine, Hermes can read that credential store directly and skip the API key entirely. That is the topic of the next article in this series.
Smoke test with a direct chat invocation:
hermes chat --provider anthropic --model claude-sonnet-4-6
You should get a prompt. Ask it something testable, like write a hello world in rust and explain the main function. Watch Hermes spin up the terminal tool, write a file, compile it, and report back.
You have just run an autonomous Claude agent on a $5 VPS.
A quick map of the filesystem so you know what to back up and what to inspect:
~/.hermes/config.yaml — model provider, API keys, tool toggles.~/.hermes/memory/ — markdown memory files, FTS5-indexed. The agent writes here.~/.hermes/skills/ — the bundled skill library plus any SKILL.md you author.~/.hermes/logs/ — session transcripts and error logs.Back up ~/.hermes/ regularly. That directory is the entirety of your agent's identity.
For headless operation you have two options. For a first install I recommend tmux:
tmux new -s hermes
hermes chat --provider anthropic --model claude-sonnet-4-6
# Ctrl+b then d to detach
Reattach later with tmux attach -t hermes. Once you are ready for production, move to a systemd unit file pointing at hermes server (the long-running daemon mode). We cover that in the operations articles later in the series.
Keep it tight. For a headless install you only need SSH in and HTTPS out:
sudo ufw allow OpenSSH
sudo ufw --force enable
If you add the messaging gateways (Telegram, Discord, Slack) later, those are outbound connections to the provider's API and do not require opened inbound ports.
You have a working Hermes install. The next move is to wire it into your Claude Pro or Max account so you are not burning API credit unnecessarily — that is covered in running Hermes on Claude Sonnet 4.6. After that, write your first custom skill in writing your first Hermes SKILL.md. For the full context on what Hermes is and why it exists, loop back to what is Hermes Agent.
Manage Apple Reminders via remindctl CLI (list, add, complete, delete).
Delegate coding tasks to OpenAI Codex CLI agent. Use for building features, refactoring, PR reviews, and batch issue fixing. Requires the codex CLI and a git repository.
Manage Apple Notes via the memo CLI on macOS (create, view, search, edit).
Track Apple devices and AirTags via FindMy.app on macOS using AppleScript and screen capture.