Hermes Agent OAuth login stuck or expired

What you see

• A 're-authentication required' message in the middle of a session, or a startup warning naming hermes auth add <provider>.
• A subscription login (Nous Portal, Anthropic, Codex, xAI) that worked yesterday and now fails on every request.
• An MCP server's browser login that ends on a 'cannot connect' page at 127.0.0.1, or times out while waiting for the callback.
• Logging in from the terminal worked, but the gateway or cron jobs still behave as if you never did.

Likely causes

Hermes refreshes OAuth tokens by itself and retries after a transient 401. A login only becomes dead when the refresh token itself is rejected for good: you changed your password, revoked access, the session expired, or another program using the same login rotated the token first. Hermes then logs one warning naming the fix and takes the credential out of rotation. It doesn't keep retrying on a timer, so the problem stays put until you sign in again.

Loopback OAuth flows, used by remote MCP servers and some plugins, redirect your browser to 127.0.0.1 on the machine running the browser. If Hermes is on a server, that listener isn't on your laptop. Finally, tokens are stored under the Hermes home of the user and profile that ran the login, so a gateway running as another user or profile won't see them.

Check this first

• hermes auth status <provider> shows the stored login state, and hermes auth list shows every credential in the pool.
• hermes status lists the providers that have credentials, along with gateway state.
• For Nous Portal, hermes portal info shows whether you're logged in and which provider is actually active.
• For a named profile, run the same commands with -p <profile>. Each profile has its own credential home.
• Look at the startup output. A benched credential prints its remaining cooldown, and a dead one prints the re-login command.

Fix

For a dead subscription login, sign in again with hermes auth add <provider>, for example hermes auth add nous, hermes auth add anthropic --type oauth or hermes auth add openai-codex. For Nous Portal, hermes portal or re-selecting it in hermes model works too. Any quarantine on the old token clears after a successful login. If a credential is only cooling down after a rate-limit or billing error, hermes auth reset <provider> clears the cooldown, and hermes auth refresh <provider> proves a grant is still alive and returns it to rotation.

For an MCP server on a remote host, run hermes mcp login <server> in a fresh terminal. Don't add the server by editing config.yaml inside a running session: the automatic reload only waits 30 seconds, which isn't long enough for a browser login. When the browser lands on the failed 127.0.0.1 page, copy the full address-bar URL and paste it at the Hermes prompt. Alternatively, open a tunnel from your laptop with ssh -N -L <port>:127.0.0.1:<port> user@host, using the port Hermes printed. If the server supports it, hermes mcp login <server> --flow device skips the callback entirely.

• Device-code and paste-the-code logins (Nous Portal, xAI Grok OAuth, Anthropic, and Codex by default) don't need a tunnel at all.
• Codex in an always-on setup: if every Codex entry is dead, sign in again in that same home, for example hermes -p <profile> auth add openai-codex. Don't wait for it to fix itself.

If it still fails

If the login succeeds but the gateway still fails, sign in as the same operating-system user the gateway service runs as, for example sudo -u hermes -i, so the tokens land in that user's ~/.hermes. Restart the gateway afterwards with hermes gateway restart.

For an MCP login that looks successful but whose tool calls later time out, the provider may not support automatic client registration (Google Drive and Atlassian are the documented examples). Create your own OAuth client in the provider's console, add it to the server's config, and run hermes mcp login again. If a tunnel fails with 'Address already in use', something on your laptop is already holding that port. Find it with lsof -iTCP:<port> -sTCP:LISTEN, stop it, and reopen the tunnel.

Related guides

• Hermes Agent rate limits and provider errors
• Hermes Agent MCP tool missing or failing
• Hermes Agent bot not responding in your chat app
• Hermes Agent profiles: separate agents for separate jobs

Spotted something wrong or out of date? Tell us on X at @HermesWatcher↗ (opens in a new tab) and we will fix it.

New Hermes Agent updates every day on X. Follow @HermesWatcher