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.

Article Created Updated Also in German: Hermes Agent auf einem VPS hinter WireGuard

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 a v; 0.23.1 gives "manifest unknown".
  • Command: gateway run with HERMES_DASHBOARD=1, PUID/PGID 1000 (the host user that owns data/).
  • Login: HERMES_DASHBOARD_BASIC_AUTH_USERNAME, …_PASSWORD and …_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, plus shm_size: 1g for browser tools and limits of 3 GB RAM and 2 CPUs.
  • Network: fixed subnet 172.31.0.0/24 with gateway 172.31.0.1. Through docker-proxy the dashboard sees this gateway as the sender, so data/config.yaml gets dashboard.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 … }
  • abort inside the handler: At site level, abort runs after handle/handle_path in 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/ permanent reads the path as a matcher and returns an empty 200.
  • Static paths: In v0.23.1 the dashboard rewrites only index.html for the prefix. Lazily loaded chunks come from /assets/ without it, so the chat page stayed empty. Remove the @hermes_static block 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

  1. In /etc/hosts on the Mac: 10.0.0.1 sandbox.altner.cloud and ::ffff:10.0.0.1 sandbox.altner.cloud. The second line catches IPv6.
  2. In Cloudflare, sandbox gets 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.cloud stays 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

  1. docker exec -u hermes hermes hermes pm install pnpm. Without it the next step stops with "tools not on PATH".
  2. docker exec -u hermes hermes hermes pm install --extra stt-whisper, then docker compose restart. The package is kept in data/installs.
  3. In config.yaml, set stt.local.model: small and stt.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.sh sets the rule idempotently. The systemd unit hermes-wg-block.service runs it with After=/Requires=/PartOf=docker.service and WantedBy=docker.service, so it comes back after every Docker or server restart.
  • Not /etc/nftables.conf: that file starts with flush 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 @outside line.
  • Remove the hosts entries on the Mac.
  • Consider extra authentication in front, such as Caddy basic auth or OIDC.

Only with my approval.

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]

More on this

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.

Show in the graph view