Understand Hermes Desktop Native PKCE Sign-In

When Hermes Desktop connects to a gated gateway, a modern gateway can broker a native OAuth flow through the system browser. The desktop creates a loopback listener and PKCE pair, the gateway completes upstream identity-provider authorization, and the desktop exchanges a short-lived one-time code for its own tokens.

Official documentation: https://hermes-agent.nousresearch.com/docs/guides/desktop-native-signin

Why the system browser matters

System-browser authorization preserves the user’s existing MFA, passkey, password-manager, and trusted-session experience. The desktop does not need to scrape a session cookie from an embedded webview. Its access and refresh tokens are stored through the operating system’s secure storage and used for API requests and WebSocket ticket minting.

The desktop discovers support from the gateway status response. If native PKCE is unavailable, older gateways may use an embedded fallback. If native flow is advertised but local loopback handling fails, the client may also fall back so access is not permanently blocked.

Operator checklist

• Use a gated gateway with a brokerable OAuth provider.
• Confirm the public status response advertises the expected auth flows.
• Complete consent in the real system browser.
• Allow the temporary loopback callback only for the sign-in window.
• Confirm the app stores tokens through OS secure storage.
• Test access-token refresh before relying on a long session.
• Verify terminal refresh failure clears state and requires fresh sign-in.
• Test sign-out for both native tokens and any legacy cookie state.

Common pitfalls

• Assuming every password-only or token-only gateway can advertise native PKCE.
• Blocking all loopback listeners and then diagnosing the identity provider instead of the local host.
• Treating the one-time callback code as a reusable desktop token.
• Keeping stale legacy cookies after testing the native path.
• Exposing native-auth bootstrap endpoints with more data than the flow requires.
• Claiming secure storage without testing the target operating system.

Verification steps

1. Read the gateway status and record the advertised auth-flow values.
2. Start sign-in and confirm the system browser—not an embedded password form—handles consent.
3. Verify the loopback code is single-use and short-lived.
4. Confirm authenticated REST calls and WebSocket tickets use the native token path.
5. Let the access token near expiry and verify refresh rotates credentials.
6. Revoke or invalidate the refresh token and confirm the desktop returns to sign-in.
7. Sign out and verify both native and legacy authentication state are cleared.