Two ways Hermes lets Herald in
| Mode | When it applies | What Herald sends |
|---|---|---|
| Token | Hermes is bound to loopback and reached as 127.0.0.1 or localhost, as in a simulator | The HERMES_DASHBOARD_SESSION_TOKEN value |
| Gated | Hermes is reached through any other name: a Wi-Fi address, a Tailscale name or a proxy | The dashboard username and password, then a one-time ticket per connection |
Herald reads which mode applies from Hermes itself, so you can’t force one from the app.
Likely causes
| What you see | Likely cause |
|---|---|
| “Invalid username or password” | The password changed, or a typo |
| “Too many attempts — wait a minute and try again” | Hermes is limiting sign-in attempts |
| “Sign-in failed (HTTP …)” | Hermes refused the sign-in for another reason; check that a username and password provider is set up |
| Hermes won’t start on a Wi-Fi address | A non-loopback bind needs an auth provider, and Hermes fails closed without one |
| HTTP 400 “Invalid Host header” | A loopback-only Hermes was reached by a non-loopback name |
| A session token works on the Mac but not the phone | Phones always arrive with a non-loopback name, so token mode can’t work for them |
Fix it
- Let the helper set it up
Run
npx herald-setup. It writes a username and an scrypt-hashed password underdashboard.basic_auth, setsdashboard.public_urlwhen needed and prints a QR code that carries the new credentials. - Need a new password? Reset it
Run
npx herald-setup --reset-passwordand scan the new QR code. - Or set it by hand
From your hermes-agent install directory, with its virtual environment active, hash a password. Then add it to
~/.hermes/config.yamlwith the address your phone uses.python -c "from plugins.dashboard_auth.basic import hash_password; print(hash_password('your-password'))" # ~/.hermes/config.yaml dashboard: public_url: https://<machine>.<tailnet>.ts.net basic_auth: username: you password_hash: 'scrypt$…' - Sign in again in Herald
Open Settings › Connections, tap the connection and enter the username and password.
Dashboards that only use OAuth
Hermes can also sign people in with Nous Portal OAuth, set up with hermes dashboard register, or with your own OpenID Connect provider. Herald signs in only with the username and password provider. If your dashboard offers OAuth alone, add dashboard.basic_auth alongside it so Herald can sign in.
Questions
Is this the same login as the web dashboard?
Yes. The username and password npx herald-setup prints are your Hermes dashboard login too.
Where is the password stored?
On the computer, as an scrypt hash in config.yaml. On the phone, in the iOS Keychain or Android’s Keystore-backed encrypted storage.
Does --insecure switch the login off?
No. Since Hermes’s June 2026 hardening, --insecure is ignored and a non-loopback bind always needs an auth provider.
