Use Hermes Agent through Cloudflare Tunnel

At a glance

What it is

cloudflared makes outbound-only connections to Cloudflare, which serves a public hostname for you

You need

A Cloudflare account and a domain on Cloudflare

Herald sees

An https:// address, like any other

Sign-in

Hermes’ dashboard username and password

Cost

Cloudflare Tunnel is on every plan, including Free

If you still want a tunnel

A tunnel avoids opening router ports and gives you a stable HTTPS name that works without any app on the phone. The dashboard behind it can read your API keys and run commands, so only go ahead if you accept that its sign-in page is reachable by anyone.

Keep the password herald-setup generates, which is 20 random characters, rather than one you have used elsewhere. Hermes rate-limits sign-in attempts, and Herald reports a 429 as too many attempts.

Set up a tunnel for Herald

1. Create a tunnel

   In the Cloudflare dashboard, go to Networking › Tunnels and select Create Tunnel. Give it a name, choose the computer’s operating system and run the install command it shows on the computer that runs Hermes.

2. Add a published application route

   Under Routes, select Add route, then Published application. Pick a hostname such as hermes.example.com and set the Service URL to http://127.0.0.1:9119. Leave HTTP Host Header empty, so Hermes sees your hostname.

3. Run herald-setup with your hostname

   It writes the dashboard password, sets dashboard.public_url to that address, keeps Hermes on 127.0.0.1 and starts it. When it starts Hermes, it waits until the address answers through the tunnel before it prints the QR code.

   npx herald-setup --url https://hermes.example.com

4. Scan the QR code in Herald

   Tap Scan the QR code. The code carries the address and the new password.

What Herald needs from the tunnel

• Hermes at the root of the hostname. Herald keeps only the scheme, host and port of an address, so a path such as /hermes won’t work.
• WebSockets passed through. Herald’s chat runs over a WebSocket to /api/ws. Cloudflare Tunnel supports WebSockets; keep the WebSockets setting on in your zone’s Network settings.
• The Host header unchanged. Hermes only accepts the exact hostname in dashboard.public_url, as a guard against DNS rebinding.
• No login page or challenge in front. Herald can only answer Hermes’ own sign-in, so Cloudflare Access logins, email codes and bot challenges block it.
• cloudflared on the same computer. Hermes trusts forwarding headers from loopback automatically; a connector in another container or on another host must be listed in dashboard.trusted_proxies.

Why not a Quick Tunnel?

cloudflared tunnel --url http://127.0.0.1:9119 gives you a random trycloudflare.com address without an account. Cloudflare says Quick Tunnels are for testing, have no uptime guarantee and get a new hostname every time, and that anyone with the URL can reach your service.

With Herald, a new hostname means pairing again after every restart: Herald only retries other forms of the same host and addresses the connection used before. Cloudflare also notes that its email check for Quick Tunnels needs an interactive browser and doesn’t support non-interactive clients.

Cloudflare Tunnel or Tailscale?

Troubleshooting

• Cloudflare shows an error page. Hermes isn’t running, or the Service URL is wrong. On the computer, check that curl http://127.0.0.1:9119/api/health answers.
• Sign-in works but chats never load. The WebSocket is being blocked. Check the zone’s WebSockets setting and any firewall or bot rules on the hostname.
• Invalid Host header. The tunnel is rewriting the Host header, or dashboard.public_url doesn’t match the hostname. Run herald-setup again with the exact address.
• The password is refused, or Herald signs out. See dashboard sign-in problems and signed out with a 401.