Hermes Agent SuperGrok is the xai-oauth provider that lets you run Hermes on Grok by signing in with your SuperGrok or X Premium+ account instead of pasting an API key.
It takes five steps, and the whole thing runs from one command: hermes model.
I'll walk you through each step, the exact config it writes, and the one error that trips most people up.
If you want a second pair of eyes on your setup, book a free SEO strategy session with my team.
What You Need Before You Start
Four things, per the Hermes xAI Grok OAuth guide.
- Python 3.9 or newer.
- Hermes Agent already installed.
- An active SuperGrok subscription, or X Premium+ on the X account you sign in with.
- Any browser that can open the verification URL Hermes prints.
That last point matters more than it looks.
Hermes doesn't need a desktop session of its own to finish the login.
The browser doesn't have to be on the same machine as Hermes.
The login is a device-code flow, so you can approve it from your laptop while Hermes runs on a server.
Step 1: Open The Provider Picker With hermes model
Run this:
hermes modelScroll the provider list and select xAI Grok OAuth (SuperGrok / X Premium+).
That's the display name the docs use for the provider ID xai-oauth.
Don't pick the plain xAI entry yet.
That one is the API-key path, and you only need it if you hit the 403 covered below.
Step 2: Approve The Device Code At accounts.x.ai
Hermes now opens a browser, or prints a verification URL on accounts.x.ai.
Open it, sign in, type the code if xAI asks for it, and approve access.
Behind the scenes, Hermes asks xAI for a device code and keeps polling until you approve.
Once you do, it writes the tokens to ~/.hermes/auth.json.
The approval window is finite.
The guide says xAI sets the expiry on the device-code response, usually tens of minutes.
Approve it straight away and you won't see a timeout.
If you do miss it, nothing breaks.
Run the same command again and the flow starts fresh with a new code.
If you have X Premium+ rather than SuperGrok, the flow is identical.
The guide says xAI links the Premium+ status to your xAI session automatically.
🔥 Want the full Hermes Agent SuperGrok setup on video, click by click?
Inside the AI Profit Boardroom you get step-by-step video trainings, the installable Agent OS with Hermes already wired in, and four coaching calls a week with 3,400+ members building real automations.
→ Join the AI Profit Boardroom
Step 3: Pin grok-4.6 In config.yaml
The picker then shows the model list, with grok-4.6 pinned at the top.
Pick it and Hermes writes this block to ~/.hermes/config.yaml:
model:
default: grok-4.6
provider: xai-oauth
base_url: https://api.x.ai/v1Prefer to skip the menus on a fresh box?
Set the two values directly:
hermes config set model.default grok-4.6
hermes config set model.provider xai-oauthNeed Grok for one run only?
Pass --provider xai-oauth on the command line.
The aliases grok-oauth, x-ai-oauth and xai-grok-oauth all resolve to the same provider.
Step 4: Confirm The Login With hermes doctor
Run:
hermes doctorLook at the ◆ Auth Providers section.
It lists the state of every provider, including xai-oauth.
Then start a chat with plain hermes and send one message.
A reply means inference works, not just the login.
I'd use a real task for the test, such as asking Grok to list the files in your current folder through the terminal tool.
That proves the model, the provider and the tool calls in one go.
That difference is the whole story of the 403, so always send the test message.
Step 5: Switch On The xAI Tools You Want
Here's the part most setups skip.
The same OAuth bearer token powers every direct-to-xAI tool in Hermes: text-to-speech, image generation, video generation and transcription.
Open the tool picker:
hermes toolsSet each backend you want.
- Text-to-Speech to xAI TTS.
- Image Generation to xAI Grok Imagine (image).
- Video Generation to xAI Grok Imagine.
- X (Twitter) Search to xAI Grok OAuth (SuperGrok / X Premium+).
Two gotchas live in this menu.
First, the video_gen toolset is off by default.
Press space on 🎬 Video Generation to turn it on, or the agent may fall back to the bundled ComfyUI skill.
Second, x_search switches itself on the moment xAI credentials exist.
If you don't want the agent searching X, turn it off under 🐦 X (Twitter) Search.
One more check for voice.
The Hermes TTS page lists xAI TTS against XAI_API_KEY, so if speech fails on OAuth alone, add the key.
Logging In On A Server Or Container
SSH sessions, containers, Cloud Shell, Codespaces and EC2 Instance Connect can't pop a browser.
Use the headless flag:
hermes auth add xai-oauth --no-browserHermes prints the URL and the user code.
Open the URL on your laptop, approve it, and Hermes keeps polling until xAI says yes.
The OAuth guide says no SSH tunnel and no local callback listener are needed for xAI.
The web dashboard and the desktop app use the same device-code flow.
The HTTP 403 Fix: Move To XAI_API_KEY
This is the error you'll most likely meet.
The browser login succeeds, the tokens save, and then the first message comes back with HTTP 403.
The error text says the caller lacks permission for the operation.
Re-running hermes model won't change a thing.
Per the troubleshooting section, xAI limits OAuth API access by tier, so a paid in-app plan can still be refused.
It's tracked in hermes-agent issue #26847, where the reporter shows the Hermes side working and xAI's inference endpoint refusing the call.
The fix the docs give is the API-key path.
- Create an xAI API key.
- Add it to
~/.hermes/.envasXAI_API_KEY=xai-.... - Switch provider with
hermes config set model.provider xai, or pick xAI inhermes model.
The Hermes providers page lists that exact route: XAI_API_KEY in ~/.hermes/.env, provider xai.
Right now, that key-based route sits outside the tier check.
The only other option it offers is a subscription upgrade at x.ai/grok if you must stay on OAuth.
📞 Want my team to plan where Grok fits in your stack? Book a free SEO strategy session and we'll map which jobs go to Grok, which go to other models, and what to automate first. → Grab your free call with my team
Three Other Errors And The Command For Each
Keep this table next to your terminal.
| Symptom | What it means | Command that fixes it |
|---|---|---|
| HTTP 403 after the browser login worked | xAI's backend is gating OAuth access by tier | Set XAI_API_KEY in ~/.hermes/.env, then hermes config set model.provider xai |
| "re-authentication required" | The refresh token was revoked or went dead, so Hermes quarantined it | hermes auth add xai-oauth |
| Authorization timed out | You didn't approve the device code before it expired | hermes auth add xai-oauth or hermes model |
| "No xAI credentials found" | No xai-oauth entry and no API key on disk | hermes model and pick the xAI Grok OAuth provider |
The refresh logic is smarter than most.
Hermes refreshes before each session and again if a call returns 401.
You never schedule a refresh yourself.
When a refresh fails for good, it marks that token dead and stops retrying it, so you get one clear message instead of a loop of failures.
Which Grok Model To Pick From The List
The OAuth picker shows the full xAI catalog the docs list.
| Model ID | Type | Use it for |
|---|---|---|
grok-4.6 | Chat | The default, pinned to the top of the picker |
grok-build-0.1 | Chat | Coding work, per the docs' description |
grok-4.3 | Chat | The previous generation, with a 1M token context window since v0.14.0 |
grok-4.20-0309-reasoning | Chat | Reasoning-heavy tasks |
grok-4.20-multi-agent-0309 | Chat | The multi-agent variant |
grok-imagine-image-2.0 | Image | Typography and layout-aware images, about 10 to 20 seconds each |
grok-imagine-video-1.5-preview | Video | Image-to-video |
The chat list comes from the on-disk models.dev cache.
New xAI releases show up on their own once that cache refreshes.
I'd start on grok-4.6, then move coding jobs to grok-build-0.1 if it suits your work better.
One more thing if you're upgrading an old install.
The providers page says xAI retired grok-4*, grok-3, grok-code-fast-1 and grok-imagine-image-pro on 15 May 2026.
Run hermes migrate xai to see the rewrite, then add --apply to write it.
Managing And Removing The Login
You stay signed in until you log out or revoke access in your xAI account settings.
List the stored entries:
hermes auth list xai-oauthDrop one pool entry by index, ID or label:
hermes auth remove xai-oauth <index|id|label>Wipe every xAI OAuth credential at once:
hermes auth logout xai-oauthOne command, and every stored xAI OAuth row is gone.
Prompt Caching Comes Free With Any x.ai Endpoint
You don't configure this one.
When the base URL contains x.ai, Hermes sends an x-grok-conv-id header on every request.
That routes a conversation to the same server, so xAI can reuse the cached system prompt and history.
The result is lower latency on long, multi-turn sessions.
It also works the same whether you're on the OAuth provider or the API-key provider, because both hit api.x.ai.
The guide notes the transport reuses the codex_responses adapter, so reasoning, tool calls and streaming need no extra settings.
When This Landed In Hermes
The provider shipped in Hermes Agent v0.14.0, published on 16 May 2026.
The release notes list it first in the highlights, and the same release took grok-4.3 to a 1M token context window.
It added the note that X Premium+ also unlocks Grok OAuth, plus an xAI web search plugin that reuses your Grok login.
🔥 Stuck on the 403 or the tool picker?
Inside the AI Profit Boardroom you get the installable Agent OS, video walkthroughs for every Hermes provider, and four live coaching calls a week where 3,400+ members bring their exact errors.
→ Get inside the AI Profit Boardroom
My Five-Minute Checklist
Run these in order on any new machine.
hermes modeland pick xAI Grok OAuth.- Approve the code at accounts.x.ai.
hermes doctorand check Auth Providers.- Send one test message with
hermes. hermes toolsto set image, video, voice and X search.
If step four returns a 403, go straight to the XAI_API_KEY fix.
Want this running inside a full system with every other tool wired in? Join the AI Profit Boardroom and install the Agent OS on day one.
Also On Our Network
- 🌐 Whether a SuperGrok-powered Hermes agent earns its place in a small business
- 🌐 A seven-criteria scorecard rating Hermes on SuperGrok at 7.5 out of 10
- 🌐 Five prompts that make your agent connect SuperGrok to Hermes for you
- 🌐 Which Grok model to run on the SuperGrok login, by real GoldieBench scores
- 🌐 The complete Hermes Agent SuperGrok guide on the AI Profit Boardroom blog
FAQ: Hermes Agent SuperGrok
What command connects SuperGrok to Hermes Agent?
Run hermes model and select xAI Grok OAuth (SuperGrok / X Premium+). You can also start the login directly with hermes auth add xai-oauth.
Where does Hermes store the SuperGrok login?
In ~/.hermes/auth.json. Hermes refreshes the access token in the background, so you stay signed in until you log out or revoke access in your xAI account.
Do I need an SSH tunnel to log in on a server?
No. Run hermes auth add xai-oauth --no-browser, open the printed URL on your laptop and approve it. The OAuth guide says xAI's device-code flow needs no tunnel.
How do I turn on Grok video generation in Hermes?
Open hermes tools and press space on Video Generation. The video_gen toolset ships disabled, so the agent can't call video_generate until you enable it.
What does the 403 after a successful login mean?
It's a tier restriction on xAI's side, not a stale token. Put XAI_API_KEY in ~/.hermes/.env and switch to the xai provider.
📺 Video notes + links to the tools 👉
🎥 Learn how I make these videos 👉
🆓 Get a FREE AI Course + Community + 1,000 AI Agents 👉
About Julian
I'm Julian Goldie, an SEO entrepreneur, author and founder of the AI Profit Boardroom, which has 3,400+ members.
I help business owners scale with AI agents, automation and SEO.
- I've built a 7-figure SEO and link building agency, Goldie Agency, with a team of 70+ SEO experts.
- I've grown a YouTube channel to 400,000+ subscribers.
- I wrote "Link Building Mastery".
- My Udemy courses have taught over 29,000 students.
→ Get my best AI training inside the AI Profit Boardroom
Run hermes model now, and if you want my team to map out what to automate first, book a free strategy session and bring your Hermes Agent SuperGrok setup with you.
