Complete Hermes OAuth on Remote Hosts

Some OAuth integrations redirect the browser to a loopback address. When Hermes runs on a remote host, the browser’s 127.0.0.1 is the laptop—not the server where Hermes is listening. Use Hermes’ paste-back flow when offered, or forward the exact callback port through SSH.

Official documentation: https://hermes-agent.nousresearch.com/docs/guides/oauth-over-ssh

Choose the correct flow

Remote MCP OAuth can often accept the full redirect URL or its code and state query directly in the terminal. This is the simplest interactive option. A local SSH forward is useful when the provider expects the browser to reach the listener normally: open a separate local terminal and forward the exact port printed by Hermes to the same loopback port on the remote host.

Do not tunnel providers that use device-code or paste-the-code authentication; follow the flow Hermes prints. Do not bind the listener publicly. OAuth providers validate an exact loopback redirect, and exposing a broad network listener weakens the design without fixing redirect matching.

Remote OAuth checklist

• Identify whether the provider uses loopback, device-code, or paste-the-code authentication.
• Copy the callback port from the current Hermes attempt.
• Prefer redirect paste-back for interactive MCP login when available.
• Otherwise open a separate plain SSH local forward.
• Keep the tunnel alive until Hermes confirms exchange success.
• Authenticate as the same OS user that runs the gateway or worker.
• Use ProxyJump for a bastion instead of exposing the callback.
• Close the temporary tunnel after verification.

Common pitfalls

• Forwarding a remembered default port instead of the port from the current attempt.
• Running Hermes in mosh and assuming mosh carries SSH local forwards.
• Pasting only the authorization code when the state parameter is also required.
• Adding an OAuth MCP server during a short config-reload window rather than using the dedicated login command.
• Authenticating as one Unix user while the gateway runs as another.
• Treating the browser’s loopback connection error as OAuth failure before checking for paste-back support.

Verification steps

1. Confirm the login command states the auth flow and exact loopback port.
2. For paste-back, copy the full redirect URL and confirm state validation succeeds.
3. For SSH forwarding, verify the local port is listening only for the tunnel lifetime.
4. Complete consent and wait for Hermes to report token exchange success.
5. List or test the integration from the same Hermes home and OS user as production.
6. Restart the target runtime and confirm the credential persists where expected.
7. Close the tunnel and verify no callback listener remains exposed.