How to Install Hermes Agent on a VPS
The always-on server setup — Docker or direct install, sized from the official docs, secured properly. A platform page of the install guide.
TL;DR
A $5 VPS (1 CPU, 1 GB RAM) is enough to run Hermes as an always-on agent — a Telegram/Discord bot that answers at 3am, cron automations, a remote backend for Hermes Desktop — as long as the model is a hosted API (Nous Portal, Anthropic, OpenAI) rather than local inference. Recommended path: Docker (nousresearch/hermes-agent, Tier 1 on x86_64 and aarch64) with --restart unless-stopped; the image's s6 supervisor restarts a crashed gateway within seconds. This guide covers Hermes Agent v0.21.5.
One rule before anything else: connect over SSH, not your provider's browser console. The official Docker docs warn that browser-based VPS consoles (Hetzner Cloud and others) mis-transmit special characters — : may arrive as ;, @ gets mangled — silently corrupting docker run -v/-e arguments and pasted API keys.
Sizing
| Resource | Minimum | Recommended |
|---|---|---|
| Memory | 1 GB | 2–4 GB |
| CPU | 1 core | 2 cores |
| Disk (data) | 500 MB | 2+ GB (grows with sessions/skills) |
Straight from the official resource table, which adds: "browser automation (Playwright/Chromium) is the most memory-hungry feature. If you don't need browser tools, 1 GB is sufficient." Distro-wise, anything glibc/systemd/FHS works; Ubuntu is the tested reference — details on the Linux page.
Path A — Docker (recommended)
ssh root@<your-vps>
mkdir -p ~/.hermes
docker run -it --rm -v ~/.hermes:/opt/data nousresearch/hermes-agent setup
docker run -d --name hermes --restart unless-stopped \
-v ~/.hermes:/opt/data -p 8642:8642 \
nousresearch/hermes-agent gateway runThe first command runs the setup wizard once (keys land in ~/.hermes/.env on the host); the second starts the persistent gateway. All state lives in the mounted directory — the container is stateless, so upgrading is docker pull + recreate (hermes update is intentionally unsupported in Docker). One container hosts multiple profiles — the officially recommended pattern — each gateway s6-supervised with per-profile rotated logs. Two rules that save real pain: never point two gateway containers at one data directory (session/memory corruption), and add --shm-size=1g if you enable browser tools.
Path B — direct install (service user)
The standard Linux installer, run as a dedicated unprivileged user:
curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash -s -- --skip-browser(--skip-browser skips Chromium on headless boxes; drop it if you want browser automation, in which case an admin first runs sudo npx playwright install-deps chromium.) Then hermes gateway setup — it offers to install a systemd user unit — and sudo loginctl enable-linger <user> so the gateway starts at boot and survives logout. The complete recipe, including PATH for service accounts, is on the Linux page.
Security: the part people get wrong
Exposing the dashboard or API server on a VPS means binding to a non-loopback address, and that engages a mandatory auth gate. This isn't theoretical: per the official docs, unauthenticated public dashboards were the entry point for a real June 2026 campaign in which internet scanners drove exposed agents into planting SSH-key backdoors — and the old --insecure escape hatch is now a deprecated no-op. The official guidance:
- OAuth via Nous Portal for anything reachable from the public internet.
- Username/password (
HERMES_DASHBOARD_BASIC_AUTH_USERNAME/_PASSWORD) only on a trusted LAN or VPN such as Tailscale. - Or skip exposure entirely: bind to
127.0.0.1and reach the dashboard over an SSH tunnel. - The gateway's OpenAI-compatible API server is off by default; enabling it beyond loopback requires an
API_SERVER_KEY. "Opening any port on an internet-facing machine is a security risk" — the docs' words.
Using the VPS from your desktop and phone
Hermes Desktop connects to the VPS as a remote gateway: keep a hermes serve backend running on the VPS (systemd is the natural home), then add its URL under Settings → Gateways in the app — the desktop docs call OAuth "preferred for anything reachable beyond your own machine." One connection serves every profile on the box via the app's profile switcher.
Your phone is the reason most people do this at all: configure the messaging gateway (hermes gateway setup) and talk to your agent over Telegram, Discord, or WhatsApp from anywhere — the full pattern is in the Hermes in your pocket use case. Community Compose stacks, systemd templates, and reverse-proxy configs live in deployment options.
FAQ
How small a VPS can run Hermes Agent?
1 GB RAM / 1 core is the documented minimum (without browser tools); 2–4 GB recommended. The typical $5 tier works with a hosted model API.
Which provider should I use?
Any standard Ubuntu/Debian VPS — Hermes has no provider-specific requirements. Whatever you pick, install over SSH: browser-based consoles (e.g. Hetzner's) corrupt special characters in pasted commands.
Docker or direct install on a VPS?
Docker for supervised auto-restart and image-based upgrades; direct install for in-place hermes update and the lightest footprint.
Is it safe to expose the Hermes dashboard on a VPS?
Only behind the mandatory auth gate — OAuth (Nous Portal) for public reachability, username/password strictly for LAN/VPN, or loopback-only behind an SSH tunnel. --insecure no longer bypasses anything.
Can Hermes Desktop connect to my VPS?
Yes — run hermes serve on the VPS and add it as a remote gateway in Desktop's Settings → Gateways, protected by OAuth.
How do I update Hermes on the VPS?
Docker: docker pull + recreate (state persists in ~/.hermes). Direct install: hermes update.
Next: configure a model provider, then decide what the box should do — the modes guide compares always-on gateways, managed Hermes Cloud, and everything in between. On your own ARM hardware instead? The Raspberry Pi setup is this page without the rent.