Hermes Agent on a VPS Behind WireGuard
Guide: Hermes Agent in Docker on the VPS yaksha, dashboard behind Caddy and reachable only through WireGuard, container cut off from the tunnel network.
Reviewed by adrian
on
Hermes Agent runs in Docker on the VPS yaksha. The dashboard is at https://sandbox.altner.cloud/hermes-agent/, only through the WireGuard tunnel. Public access comes later, and only after I approve it.1
Status
Running since 2026-11-13 with version v0.23.1. The model is anthropic/claude-haiku-5.5 via OpenRouter, web search uses Exa (free tier) and TTS uses Piper. Voice input is switched off.
1. Container
The base is the official Docker guide.2 It lives in /srv/altner.cloud/sandbox/hermes-agent with compose.yaml, .env (chmod 600) and data/.
- Image:
nousresearch/hermes-agent:v0.23.1. The tags carry av;0.23.1gives "manifest unknown". - Command:
gateway runwithHERMES_DASHBOARD=1,PUID/PGID1000 (the host user that ownsdata/). - Login:
HERMES_DASHBOARD_BASIC_AUTH_USERNAME,…_PASSWORDand…_SECRET(at least 32 random bytes) from.env. - Prefix:
HERMES_DASHBOARD_PUBLIC_URL: https://sandbox.altner.cloud/hermes-agent. - Port:
127.0.0.1:8100:9119. The dashboard is reachable only through Caddy, and the gateway API (8642) stays inside the container. - Data:
./data:/opt/data, plusshm_size: 1gfor browser tools and limits of 3 GB RAM and 2 CPUs. - Network: fixed subnet
172.31.0.0/24with gateway172.31.0.1. Through docker-proxy the dashboard sees this gateway as the sender, sodata/config.yamlgetsdashboard.trusted_proxies: ["172.31.0.1"].
Model and tools are set with docker exec -it hermes hermes setup; the wizard writes the API keys to data/.env, not to the compose .env. hermes doctor checks the result; warnings about image generation, computer use or "install out of sync" were harmless.
2. Caddy
One site file in /etc/caddy/sites/, loaded with caddy reload --config /etc/caddy/Caddyfile:
@outside not remote_ip 10.0.0.0/24
handle /hermes-agent {
route {
abort @outside
redir * /hermes-agent/ permanent
}
}
handle_path /hermes-agent/* {
route {
abort @outside
reverse_proxy 127.0.0.1:8100 {
header_up X-Forwarded-Prefix /hermes-agent
}
}
}
@hermes_static path /assets/* /fonts/* /fonts-terminal/* /ds-assets/*
handle @hermes_static { … same route … }
abortinside the handler: At site level,abortruns afterhandle/handle_pathin Caddy's directive order, so it never fires there. For a short time the login page was public because of this.redir *:redir /hermes-agent/ permanentreads the path as a matcher and returns an empty 200.- Static paths: In v0.23.1 the dashboard rewrites only
index.htmlfor the prefix. Lazily loaded chunks come from/assets/without it, so the chat page stayed empty. Remove the@hermes_staticblock once Hermes fixes this. - No
encode: The chat stream and WebSockets (/api/ws,/api/pty) must not be buffered. - Access log: set
mode 0644, otherwise the deploy user cannot read it.
3. WireGuard access
The Mac's tunnel is a split tunnel (AllowedIPs = 10.0.0.0/24), so DNS sends the domain to Cloudflare. The result was a Cloudflare error 520, and later "Sign-in failed".1
- In
/etc/hostson the Mac:10.0.0.1 sandbox.altner.cloudand::ffff:10.0.0.1 sandbox.altner.cloud. The second line catches IPv6. - In Cloudflare,
sandboxgets its own A/AAAA records set to DNS only. A proxied name publishes an HTTPS/SVCB record with IP hints; Safari follows them and ignores/etc/hosts. The wildcard*.altner.cloudstays proxied.
4. Using it
- Desktop app: connection mode Remote gateway, URL
https://sandbox.altner.cloud/hermes-agent, sign in with the dashboard login, then Test.3 Connect via SSH expects a native install and does not work with Docker; Local gateway would start a second Hermes on the Mac. - Pasting in Safari: the chat intercepts Cmd+V and asks for clipboard access, which Safari refuses. Paste with right-click instead, or use Chrome.
- Deleting chats: in the dashboard under Sessions, or
docker exec hermes hermes sessions delete --yes <id>. - Cost: Haiku 5.5 costs $0.10 per million input tokens and $0.50 per million output tokens up to 100K prompt tokens, five times that above. Cache reads cost $0.01.
5. Voice input
docker exec -u hermes hermes hermes pm install pnpm. Without it the next step stops with "tools not on PATH".docker exec -u hermes hermes hermes pm install --extra stt-whisper, thendocker compose restart. The package is kept indata/installs.- In
config.yaml, setstt.local.model: smallandstt.language: de.
On 4 CPU cores without a GPU each clip took about 5 seconds, the text was poor, and the VAD filter cut up to 80% of some recordings. Voice input is therefore off (stt.enabled: false), which saves about 500 MB of RAM. The way back would be a Groq API key (whisper-large-v3-turbo).1
6. Isolation
The container sees only data/, is not privileged and has no Docker socket. Host services on 127.0.0.1 are unreachable. On the network, however, it reached the Mac through the tunnel (AirPlay on 5000/7000, Syncthing on 22000). A rule in Docker's DOCKER-USER chain closes that:1
iptables -I DOCKER-USER 1 -s 172.31.0.0/24 -d 10.0.0.0/24 \
-m conntrack --ctstate NEW,INVALID -m comment --comment hermes-wg-block \
-j REJECT --reject-with icmp-admin-prohibited
- Persistence:
/usr/local/sbin/hermes-wg-block.shsets the rule idempotently. The systemd unithermes-wg-block.serviceruns it withAfter=/Requires=/PartOf=docker.serviceandWantedBy=docker.service, so it comes back after every Docker or server restart. - Not
/etc/nftables.conf: that file starts withflush ruleset. Starting the nftables service would wipe all Docker rules. - Tested: the Mac's ports now give "no route to host", while internet, OpenRouter and the dashboard still work. The desktop app is unaffected because its connections end at Caddy on the host.
- Undo:
sudo systemctl disable --now hermes-wg-block.
Before going public
- Remove every
abort @outsideline. - Remove the hosts entries on the Mac.
- Consider extra authentication in front, such as Caddy basic auth or OIDC.
Only with my approval.
-
Self-hosting Hermes Agent on the VPS yaksha (raw/2026/2026-11-13/self-hosting-hermes-agent-on-the-vps-yaksha.md). ↩
-
Hermes Agent: Docker (https://hermes-agent.nousresearch.com/docs/user-guide/docker). ↩
-
Hermes Agent: multi-connection desktop (https://hermes-agent.nousresearch.com/docs/user-guide/multi-connection-desktop). ↩
Based on
-
Self-hosting Hermes Agent on the VPS yaksha
(
raw/2026/2026-11-13/self-hosting-hermes-agent-on-the-vps-yaksha.md) [chat] - Hermes Agent: Docker [docs-docker]
- Hermes Agent: multi-connection desktop [docs-desktop]
-
Explaining OpenAI's post on securing persistent agents
(
raw/2026/2026-11-15/explaining-openai-s-post-on-securing-persistent-agents.md) [chat-2026-11-15]
Topic
- AI Agents AI apps whose language model calls tools to get work done, such as Claude Code and Claude Desktop, and how to run them safely.
Uses
- Hermes Agent Open-source AI agent by Nous Research with a web dashboard, desktop app, tools, skills and memory. Runs on your own server, for example in Docker.
See also
- Securing a Hosted MCP Server Plan for a hosted MCP server for the knowledge base that claude.ai on the web and on mobile can use, while nobody else can.
- Securing a Persistent AI Agent How to let an AI agent work on its own without handing it the keys: OpenAI's five safeguards explained, and how I apply them to my own agents.