I have been paying for SuperGrok for eight months. I also use Hermes Agent (an open-source AI agent runtime that you can self-host or run on your laptop) for most of my day-to-day work. Until recently I had two separate logins: a browser tab for Grok on x.com, and a separate XAI_API_KEY pasted into my shell for Hermes. It felt stupid. The same subscription was getting billed twice in different shapes.
Then I noticed Hermes ships an xAI OAuth (a protocol where you authorize a third-party app to act on your behalf without sharing your password) provider called xai-oauth that piggybacks on the SuperGrok and X Premium+ login. One browser approval, one set of tokens saved locally, and Hermes can use Grok for chat, text-to-speech, image generation, video generation, transcription, and X search. No separate API key, no separate billing, no separate session to manage.
This post is what I learned setting it up on macOS, on a remote Linux box, and inside a cloud shell where I could not forward ports.
What xai-oauth actually does
Under the hood, xai-oauth is not a new API. It speaks to the same https://api.x.ai/v1 endpoint Hermes already uses for the regular xAI provider, but it uses a refreshable OAuth token instead of a static API key. The provider id is xai-oauth, and the default model it pins near the top of the picker is grok-4.3.
Hermes reuses its codex_responses transport for this provider, so anything that works on the regular xAI transport (reasoning, tool calling, streaming, prompt caching) also works through OAuth. The only difference is the credential source: a browser login instead of an XAI_API_KEY environment variable.
The nice side effect is that the same OAuth entry covers Hermes’ direct xAI media tools. Once you are logged in via xai-oauth, you can pick xAI backends in hermes tools for text-to-speech, image generation, video generation, and transcription. X search is a separate entry but it lights up automatically when xAI credentials are present.
One caveat the docs flag, and I confirmed it once: xAI sometimes restricts OAuth API access by tier. If the browser login succeeds but inference returns HTTP 403 (a status code meaning the server understood the request but refuses to fulfill it), you are not holding the OAuth token wrong, you are hitting a subscription-entitlement wall. The fix is to switch back to the API-key provider or upgrade your Grok subscription.
Local setup, end to end
The local flow is short enough to fit on a sticky note.
- Run
hermes modeland pickxAI Grok OAuth (SuperGrok / X Premium+)from the provider list. Hermes opensaccounts.x.aiin your default browser. - Sign in with the X account that has SuperGrok or X Premium+ active. Approve the OAuth scopes. The browser redirects back to a local callback listener at
127.0.0.1:56121. - Pick a Grok model in the picker.
grok-4.3is the obvious starting point. - Quit the picker. Run
hermesas normal.
Hermes stores the tokens in ~/.hermes/auth.json and refreshes them before they expire. You do not have to repeat the browser login every session, and you do not have to copy long secrets around.
If you already know you want the OAuth provider and want to skip the picker, the direct command is hermes auth add xai-oauth. Same browser flow, same token storage, no menu navigation.
To make xAI OAuth your default for every session, set two config keys:
hermes config set model.default grok-4.3
hermes config set model.provider xai-oauth
Your ~/.hermes/config.yaml should then contain model.default, model.provider, and model.base_url pointing at https://api.x.ai/v1.
Remote server: the part that bit me
OAuth on a remote machine is where the simple flow falls apart, and where the docs earn their keep. Two separate problems show up, and they have different fixes.
The callback port. When you run hermes auth add xai-oauth on a remote box, Hermes starts a callback listener at 127.0.0.1:56121 on that machine. If you open the printed URL on your laptop, the browser tries to redirect to a port the laptop does not have open. The login looks like it succeeds in the browser tab, then Hermes just sits there waiting for a callback that never arrives.
The fix is SSH port forwarding (a way to tunnel a port from your laptop to the remote machine through the SSH connection):
ssh -N -L 56121:127.0.0.1:56121 user@remote-host
Run that in a second terminal on your laptop, leave it open, then run hermes auth add xai-oauth in your SSH session. The browser will reach the callback listener through the forwarded port and the login will complete. If you connect through a jump host, add -J jump-user@jump-host to the SSH command.
The no-browser console. If you are in Cloud Shell, Codespaces, EC2 Instance Connect, Gitpod, or any environment where the SSH forwarding recipe is not available, you cannot run the normal callback listener. Hermes has a --manual-paste mode for this case:
hermes auth add xai-oauth --manual-paste
Hermes skips the local listener and prints the authorization URL. You open it in any browser, sign in, and the redirect URL that would normally go to the local listener is what you copy and paste back into the SSH session. Hermes parses the URL, extracts the tokens, and saves them like any other login. It is one extra step but it works where nothing else does.
The five errors you will actually hit
Most of the setup time I spent on this was fixing the same handful of problems. Listing them here so the next person does not have to dig through the docs.
- Token expired or refresh failed. Refresh tokens rotate. If you have not used the OAuth entry in a long time, the refresh attempt can fail. The fix is
hermes auth add xai-oauthagain. Hermes will reuse the saved entry if it is still valid and only re-prompt when it is not. - Login timed out. The local callback listener is open for a limited window. Approve the browser prompt quickly. If you miss it, run the command again.
- State mismatch. Usually a proxy, a browser extension, or a redirect layer is intercepting the callback. Disable the extension, try a different network, or try
--manual-paste. - HTTP 403 after a successful login. The OAuth token is fine, the subscription is the problem. Switch to the API-key provider or upgrade your Grok plan.
- No xAI credentials found. Hermes has no
xai-oauthentry and noXAI_API_KEY. Runhermes model, pick the OAuth provider, and approve the browser prompt.
Run hermes doctor after the login. The Auth Providers section shows the xai-oauth status. A green status there is the most reliable signal that the next session will refresh correctly.
Trade-offs
The OAuth path is not free in time. The local setup is fast, but the remote setup is a five-minute recipe with two separate failure modes (forgotten SSH forward, missed callback window), and you will hit one of them the first time. The API-key path is the opposite shape: a single environment variable with your key in it, and you are done, no browser, no port forwarding, no remote-host dance. The trade-off is operational convenience versus setup cost. The OAuth path also has a second hidden cost: when the refresh token rotates, the next session needs network access to xAI’s token endpoint. If you are running Hermes in a fully air-gapped setup, OAuth will not work, and the API-key path is the only one that will.
The subscription tier also matters more than the docs suggest. I hit a 403 once during testing on a SuperGrok Basic plan, and the error message gave no hint that the tier was the problem. If you are paying for a lower SuperGrok tier or for X Premium with no Grok access, the OAuth login will succeed but inference will fail. The fix is to know your tier up front, not after the third failed login attempt. The OAuth provider mirrors what your subscription already includes, so the failure mode is a feature of the subscription tier, not a bug in the provider.
One last thing: the OAuth entry ties Hermes to your X account. If you ever want to revoke the connection, hermes auth logout xai-oauth clears the saved entry. But if X disables your account or revokes third-party access at the platform level, Hermes will silently fail on the next refresh and you will need to log in again from scratch. The keychain entry is the source of truth, not the X account session.
If you only use one of the two providers, the choice is obvious. Pure API-key users should keep the API key. Pure subscription users with SuperGrok or X Premium+ should switch to OAuth and stop paying twice. The mixed case (you have both an API key for production and a subscription for personal use) is where the OAuth path is most valuable: it lets the same Hermes installation use both backends without config drift between machines.
What I would tell past me
- Start with the model picker, not the manual command. The picker is one extra menu click but it surfaces the right provider name and model default. I wasted ten minutes guessing at config keys the first time.
- Forward port 56121 before you run the auth command, not after. The error message you get when the callback cannot reach the listener is generic. Forgetting the SSH forward is the single most common reason the remote flow looks broken.
- The OAuth token covers the media tools too. Once you log in, check
hermes toolsand look at the xAI backends for TTS, image, and video. The same login lights them up, and video generation is off by default so you have to enable it explicitly.
If you are already paying for SuperGrok or X Premium+ and you also use Hermes, the OAuth provider is a quieter, cleaner integration than juggling an XAI_API_KEY alongside the subscription. The local flow is a two-minute setup. The remote flow is a five-minute setup if you remember the callback port.