docs(README): link community fix for xAI OAuth callback failure on WSL2#27305
Closed
jett22JOE wants to merge 1 commit into
Closed
docs(README): link community fix for xAI OAuth callback failure on WSL2#27305jett22JOE wants to merge 1 commit into
jett22JOE wants to merge 1 commit into
Conversation
After native xAI SuperGrok OAuth shipped (~2026-05-15), WSL2 users running `hermes auth add xai-oauth --type oauth` hit a silent failure: the loopback callback at 127.0.0.1:<ephemeral>/callback is blocked by the default Hyper-V Firewall policy (`DefaultInboundAction = Block` on the WSL VM), so the redirect from accounts.x.ai is dropped and xAI shows its "Could not establish connection" fallback with the auth code as plain text. Since `hermes auth add xai-oauth` has no `--code` flag in v0.14.0, the code is orphaned and the user is stuck. This affects mirrored-networking WSL2 (now the Microsoft default) on otherwise-working installs, and also affects users of xAI's own Grok Build CLI since both share the same loopback OAuth flow (Hermes impersonates the Grok-CLI client_id `b1a00492-...`). Adds a one-paragraph callout under the existing Windows/WSL2 blockquote in the Quick Install section pointing at a community- maintained fix repo: jettoptx/hermes-xai-oauth-wsl. The fix repo provides both a wrapper script (no admin needed) and a one-shot `New-NetFirewallHyperVRule` for the permanent fix. I'm happy to follow up with a code PR that adds a `--code` flag to `hermes_cli/auth.py` so the wrapper becomes unnecessary — wanted to get the docs unblock landed first since users are hitting this today. Co-Authored-By: Hedgehog Multimodal <joe@jettoptics.ai>
This comment was marked as spam.
This comment was marked as spam.
5 tasks
Contributor
|
Closing per community-link-policy — we don't link contributor-owned forks/repos from the main README. The real fix is to add a |
Author
|
<3 you guys
…-JOE
On Mon, May 18, 2026 at 9:00 PM Teknium ***@***.***> wrote:
*teknium1* left a comment (NousResearch/hermes-agent#27305)
<#27305?email_source=notifications&email_token=BDMSJJUVPPOBPSGCERMDKDD43PE5HA5CNFSNUABFM5UWIORPF5TWS5BNNB2WEL2JONZXKZKDN5WW2ZLOOQXTINBYGQYDGMZWGMZ2M4TFMFZW63VGMF2XI2DPOKSWK5TFNZ2LK4DSL5RW63LNMVXHIX3POBSW4X3DNRUWG2Y#issuecomment-4484033633>
Closing per community-link-policy — we don't link contributor-owned
forks/repos from the main README. The real fix is to add a --paste-code/
--manual-paste path in hermes_cli/auth.py so the orphaned code from xAI's
fallback page can be fed back into the listener. That work is being merged
via the salvage of #26929
<#26929> — thanks for
surfacing the WSL2 Hyper-V firewall root cause.
—
Reply to this email directly, view it on GitHub
<#27305?email_source=notifications&email_token=BDMSJJUVPPOBPSGCERMDKDD43PE5HA5CNFSNUABFM5UWIORPF5TWS5BNNB2WEL2JONZXKZKDN5WW2ZLOOQXTINBYGQYDGMZWGMZ2M4TFMFZW63VGMF2XI2DPOKSWK5TFNZ2LK4DSL5RW63LNMVXHIX3POBSW4X3DNRUWG2Y#issuecomment-4484033633>,
or unsubscribe
<https://github.com/notifications/unsubscribe-auth/BDMSJJXWHQVZX77PJKW4D4343PE5HAVCNFSM6AAAAACZBEHYY2VHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHM2DIOBUGAZTGNRTGM>
.
You are receiving this because you authored the thread.Message ID:
***@***.***>
|
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
4 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds a one-paragraph callout in the
## Quick Installsection's Windows/WSL2 blockquote pointing at a community-maintained fix repo for thehermes auth add xai-oauth --type oauthcallback failure on WSL2: jettoptx/hermes-xai-oauth-wsl.Single insertion, two lines, no other changes.
Why
After xAI shipped native SuperGrok OAuth (~2026-05-15), every WSL2 user trying to log in via Hermes hits this:
hermes auth add xai-oauth --type oauthopens an HTTP listener on127.0.0.1:<ephemeral-port>/callbackinside WSL.accounts.x.ai.302 Foundredirect to the loopback URL is silently dropped by the Hyper-V Firewall's default policy on the WSL VM (DefaultInboundAction = Block), which ships enabled with mirrored networking — Microsoft's current default.v0.14.0) has no--codeflag onhermes auth add. The code is orphaned. The listener times out.Verify the firewall block on any affected machine:
The same flow breaks xAI's own Grok Build CLI, since Hermes impersonates the Grok-CLI
client_id(b1a00492-073a-47ea-816f-4c329264a828) and both share the loopback redirect path.What the linked repo provides
scripts/hermes-xai-oauth-wsl.sh— wrapper that starts the Hermes listener, prints the URL, prompts for the code from xAI's fallback page, andcurls the callback URL from inside WSL (same kernel as the listener, so the firewall is irrelevant). No admin required.docs/permanent-fix.ps1— elevated PowerShell that punches a one-timeNew-NetFirewallHyperVRulefor the ephemeral TCP range, after which plainhermes auth add xai-oauth --type oauthworks directly.Why a docs link rather than a code PR
A real fix would add a
--codeflag tohermes_cli/auth.py(_xai_oauth_loopback_loginaround line 5315) so the wrapper becomes unnecessary. I'm happy to follow up with that PR if you want it — wanted to land the unblock for users today first, since the docs link is zero-risk and the code change touches an auth path that probably warrants its own review cycle.If you'd prefer to vendor the script or write your own callout instead of linking out, also happy to defer — the point is that something in the README acknowledges this trap for WSL2 users.
Test plan
Falls under priority 2 (cross-platform compatibility — WSL2) in CONTRIBUTING.md.