Hermes HQ support

Hermes HQ is an iPhone app for your own Hermes agent. Chat with your bots, send photos, files and voice memos, approve what your agent wants to run, watch and take over a bot's browser, check scheduled jobs and tasks, and get notified when a reply is ready.

Hermes HQ is a client. It has no AI model and no server of its own. It connects to Hermes, open-source agent software from Nous Research, running on a computer you control (your "gateway"). Hermes HQ is an independent app, not made by Nous Research.

What you need

An iPhone with iOS 26 or later.
A computer running Hermes, recent enough for the app. If it is too old, the app says Update Hermes on Your Gateway.
A way to sign in to that computer from your phone: your Nous account (with the quick setup below), or a gateway username and password you choose yourself.

Set up your gateway

Open Hermes HQ and tap Get Started. It asks where Hermes runs and shows only the steps for that computer. If someone else runs Hermes for you, ask them for the address and how to sign in.

On a Mac (easiest): paste one command into Terminal on the Mac (the app can copy it or send it to the Mac):
```
curl -fsSL https://raw.githubusercontent.com/mrcharlesiv/hermes-hq/main/connect.sh | sh
```
It walks you through signing in to Nous and Tailscale, starts Hermes in the background if it isn't running, gives the Mac a secure HTTPS address through Tailscale Funnel with a gatekeeper in front of Hermes, and shows a QR code. Scan it with the iPhone's Camera, tap Open in Hermes HQ, then Sign in with Nous. The iPhone doesn't need Tailscale, and only the Nous account signed in on that Mac gets in. Keep the Mac on and awake. What the command does: github.com/mrcharlesiv/hermes-hq.
On Windows, Linux or a server: install Tailscale on that computer and the iPhone, then copy a message from the app and send it to Hermes. Hermes does the setup and tells you the address and username. The same steps by hand are below.
Someone gave you an address: tap I already have an address and sign in.

The steps by hand, with a username and password over Tailscale (the app shows them under "I'd rather do it myself", with a button to copy them):

Install Tailscale on the computer and on your iPhone, signed in to the same account. In the Tailscale admin console, turn on MagicDNS and HTTPS certificates.
On the computer, run tailscale serve --bg 9119. It prints your gateway address, like https://your-computer.your-tailnet.ts.net.
Add your username, a long password, a secret and that address to ~/.hermes/.env on the computer. The app's setup guide shows the exact four lines and how to make the secret.
Start the gateway with hermes dashboard --no-open and leave it running.
Check it: open the address in Safari on the iPhone and sign in.
In the app, enter the address, username and password, and tap Connect.

The app keeps your session in the iPhone's Keychain so it reconnects by itself. It never stores your password. Don't expose a password-only gateway directly to the public internet; keep it on Tailscale or your home network.

You can save several gateways and switch between them in Settings › Gateway.

Notifications

The app alerts you when a reply is ready or a bot needs your approval (with Approve once and Deny on the alert).

While the app is open or was just left, it alerts by itself.
When the app is closed, your gateway needs the free push plugin. The app offers to have one of your bots install it ("Ask "), or run this on the computer, then restart Hermes:
```
hermes plugins install mrcharlesiv/hermes-hq-plugins/hermes-hq-push --enable
```
Alerts are encrypted on your gateway with a key only your phone has. Apple's push service and our relay carry them but can't read them.
Turn Settings › Notifications › Show Previews off to see only who an alert is from.
Check iPhone Settings › Notifications › Hermes HQ too.

Common problems

"Couldn't connect", or nothing happens when I tap Connect. Open the gateway's address in Safari on the iPhone. If Safari can't open it either, the problem is the network or the computer, not the app. Check the computer is awake and Hermes is running. If you use Tailscale, check it's switched on in the iPhone's Tailscale app.

"This Nous account isn't allowed on this gateway." That gateway only lets in the Nous account it belongs to (the one signed in on its computer). Sign in with that account, or ask whoever runs the gateway.

The address is rejected. Use the full address, including https://. Plain http:// only works for addresses on your home network or Tailscale.

"Update Hermes on Your Gateway." On the computer, run hermes update (or update Hermes the way you installed it), then tap Check Again.

Wrong username or password. They're the ones in ~/.hermes/.env on the computer, not your AI provider account. After changing that file, restart Hermes.

No alerts when the app is closed. Install the push plugin (above) and restart Hermes, then open the app once with Settings › Notifications on. Alerts come from the gateway in use; switching gateways moves them.

The app reloaded. iOS sometimes reclaims memory from the part of the app that draws its screens. The app reloads it; your chats and drafts are kept, but a recording or playback in progress stops. If it happens often, send us Settings › About › Diagnostics.

A voice feature doesn't work. Dictation and spoken replies use your gateway's speech settings. Check Hermes' voice settings on the computer, and allow the microphone in iPhone Settings › Hermes HQ.

Watch Browser shows nothing. A bot's browser appears while the bot is using it. Your gateway needs the browser plugin: ask a bot to set it up, or follow the plugin instructions.

Send a bug report

In the app, open Settings › About › Diagnostics and tap Copy Diagnostics. Passwords, tokens and cookies are removed, but read it before you send it: it includes error messages.
Email it to support@gethermeshq.com, with what you did and what happened.

TestFlight testers can also take a screenshot and choose Share Beta Feedback, or send feedback from the TestFlight app.

Privacy

The app doesn't send your chats or files to us. See the privacy policy.

Contact

Email support@gethermeshq.com. We aim to reply within three business days.