Use ChatGPT in Hermes Without an API Key: Complete Setup Guide

How to Run ChatGPT with Hermes Without an API Key

You can run GPT models inside Hermes Agent using nothing but your existing ChatGPT subscription. Hermes authenticates via ChatGPT device-code OAuth, stores credentials in ~/.hermes/auth.json, and can import existing Codex CLI credentials. That means no developer API key, no per-token billing dashboard, and no key rotation to manage. Keep in mind one hard limit: this flow needs a paid plan, and the ChatGPT Plus cost has held at $20 since launch.

This guide explains the mechanism, walks through installation, and shows the exact OAuth login flow. It also covers the smartest way to pay for AI subscriptions like ChatGPT, Claude, and Gemini without losing money to foreign transaction fees. Expect around 10 minutes of reading, and by the end you will have GPT running in a terminal agent with your subscription doing the heavy lifting.

Paying for ChatGPT, Claude, or Gemini in USD every month? Bleap charges 0% FX fees on your USD subscriptions and gives a flat 20% cashback on Claude, ChatGPT, and Gemini, with a self-custodial Mastercard and no subscription of its own. (The 20% cashback applies to Claude, ChatGPT, and Gemini only.) Get the Bleap card →

1. How OpenAI's OAuth Integration with Hermes Actually Works

The Mechanism Behind Subscription-Based Access

Hermes uses OpenAI's OAuth device code flow, the same authentication pattern behind tools like Slack and the GitHub CLI. Instead of generating an API key in the OpenAI developer dashboard, your existing ChatGPT subscription acts as the credential. The upstream Hermes Agent source code uses an OpenAI Codex OAuth device flow for OpenAI authentication, not a plain OPENAIAPIKEY environment variable, and the device flow is designed for users who have a Codex subscription and want to authenticate via the OpenAI website rather than managing a raw API key.

This routes requests through ChatGPT's consumer subscription infrastructure rather than the pay-per-token API tier.

Why This Is Different From API Key Authentication

An API key means a developer account plus per-token billing. OAuth login means your flat monthly subscription covers usage instead. The practical advantage is real: no surprise API bills, no token budget to babysit, and no keys to rotate. One caveat worth flagging up front: which ChatGPT plan tiers are eligible, and how Hermes usage counts against your plan's Codex limits, are not currently documented. Treat model access as a live snapshot rather than a fixed guarantee.

2. Prerequisites: What You Need Before You Start

Required Accounts and Subscriptions

• An active paid ChatGPT plan. ChatGPT pricing runs from $0 to $200 per month across five individual tiers: Free at $0, Go at $8, Plus at $20, and two Pro plans at $100 and $200. The free tier is not supported for this flow.
• An OpenAI account with a verified email address.
• A paid subscription is the minimum requirement because the OAuth device flow authenticates against your subscription, and free accounts do not have the model access this method exposes.

Required Software and System Compatibility

• Hermes Agent installed (covered in the next section).
• A supported operating system: macOS, Linux, or Windows.
• A modern terminal emulator such as bash, zsh, or PowerShell.
• An internet connection for the OAuth browser redirect.

Windows users should run installs from an elevated PowerShell session. On Linux, confirm your shell profile is sourcing the Hermes binary path.

3. Installing Hermes Agent: Two Methods

Method 1: Desktop Installer (Recommended for Beginners)

Head to the official Hermes desktop installer download page and grab the build for your platform.

1. Download the appropriate installer for your OS, .dmg for macOS, .exe for Windows, or an .AppImage or package for Linux.
2. Run the installer and follow the GUI prompts.
3. Confirm Hermes is available in your system PATH once installation finishes.

Verify the install with a quick version check:

hermes --version

Method 2: Terminal Installation (Recommended for Developers)

If you would rather stay in the shell, use a package manager or the install script.

• macOS and Linux: run the curl-based install script, or use brew install hermes-agent.
• Windows: winget install hermes-agent or the equivalent package.

On macOS and Linux you may need to grant execute permissions to the downloaded script and add the binary directory to your PATH. Then confirm with the same check:

hermes --version

Post-Installation Configuration

On first run, Hermes writes a config file to ~/.hermes/config.toml (or the platform equivalent). There are no API key fields to fill in for the subscription flow. There is no static API key; Hermes mints and auto-refreshes the token for you, including re-minting on a mid-session 401. OAuth handles the rest.

4. Running the OAuth Authentication Command

The Exact Terminal Command to Initiate Login

Start the ChatGPT device-code login with:

hermes auth add openai-codex

You can also reach it interactively. Run hermes auth add openai-codex (or hermes model → ChatGPT or Codex Subscription) to start a fresh device-code login; the quarantine clears on the next successful exchange. The interactive picker is useful if you are not sure which provider label to select, since it walks you through the choice.

What Happens Immediately After Running the Command

Hermes generates a unique device code and prints it in the terminal alongside a verification URL. The terminal then enters a polling state, waiting for you to complete the browser-side approval. During this phase the terminal output typically shows the code, the URL, and a "waiting for authorisation" line that refreshes while it polls. Expect the approval window to stay open for several minutes, so there is no rush to switch to the browser instantly.

Want your monthly AI spend to actually pay you back? On ChatGPT, Claude, and Gemini, Bleap gives a flat 20% cashback in USDC plus 0% FX fees on the USD charge, with no monthly card fee. Get the Bleap card →

5. Approving the OAuth Request and Completing Login

Step-by-Step Browser Confirmation (Device Code Flow)

1. Open the printed URL in any browser. You do not need to be on the same device that ran the command.
2. Log in with your OpenAI account credentials if you are not already signed in.
3. Enter the device code shown in your terminal when prompted.
4. Review the permissions Hermes is requesting, which cover read access to your ChatGPT session.
5. Click Confirm or Allow to complete the authorisation.

What a Successful Login Looks Like

The terminal outputs a success message confirming the authenticated account, and the token is saved locally in the Hermes config directory. From that point, background refresh keeps you signed in. This mirrors how the same OAuth model behaves for other Hermes providers, where no API key is required, you log in once, and Hermes automatically refreshes your session in the background. You will not need to repeat the login until the stored token is revoked or fully expires.

Troubleshooting Common Login Errors

• Code expired: device codes are short-lived, so re-run the login command to generate a fresh code and URL.
• Account not eligible: a free ChatGPT account cannot complete this flow, which is expected behaviour.
• Browser redirect issues: disable pop-up blockers for the auth domain, and if a token seems stale, a fresh login is more reliable than another retry. Note the broader tip that OAuth-backed providers such as Nous Portal or OpenAI Codex may need a fresh login flow instead of another API key.

6. Selecting and Switching to a GPT Model in Hermes

Post-Authentication Model Configuration

Once authenticated, Hermes uses a baseline model, but you can set your preferred GPT model explicitly:

hermes config set model <model-name>

The models available to you depend on your subscription tier, and OpenAI's lineup moves quickly, so list what your account can actually reach before committing.

Available GPT Models via ChatGPT Subscription

As of 2026, OpenAI's flagship family is GPT-5.6. Hermes Agent can run on OpenAI's GPT family, GPT-5.6 Sol, Terra, Luna, and others, and GPT-5.6 Sol is the current flagship model.

Model availability shifts as OpenAI updates its tiers. In fact, GPT-5.6 is appearing in paid ChatGPT subscriptions, including Plus and Pro accounts, but rollout can vary by account, region, and plan. List everything your account can use with:

hermes models list

Switching Models Mid-Session

You can switch models inline during an active session. A common pattern is dropping to a faster, lighter model for simple queries, then jumping back to the flagship for heavy reasoning or long coding tasks. This keeps responses snappy without sacrificing quality where it counts.

7. Verifying the Setup Works Correctly

Running a Test Prompt

Confirm everything works with a single prompt:

hermes run "Explain OAuth device code flow in one paragraph"

A successful run displays the active model name, returns a generated response, and shows no API key errors. The first response after authentication can take a moment longer than subsequent ones as the session warms up.

Confirming Session and Subscription Details

Check your current auth state with:

hermes auth status

The output confirms your logged-in email, the active model, and token validity. As the docs note for the provider view, the Auth Providers section will show the current state of every provider.

What to Do If the Test Fails

• Re-run hermes auth add openai-codex if the session appears expired.
• Check internet connectivity and firewall rules.
• Inspect recent logs with hermes logs --tail 50 to pinpoint the failing layer.

8. Why Use GPT via Hermes Instead of a Local Model

Quality and Reasoning Capability

Flagship GPT models consistently outperform most locally-runnable open-weight models on reasoning, coding, and language tasks. GPT models are known for strong coding, broad general knowledge, and reliable tool-calling, qualities that make them effective for agentic workloads. You reach high-quality output without prompt-engineering workarounds.

Context Window and Memory

Cloud-hosted GPT models handle far larger context windows than most consumer hardware can manage locally. That means bigger codebases, longer documents, and multi-turn conversations without noticeable degradation partway through a session.

Hardware Requirements (or Lack Thereof)

Local models like Llama and Mistral need serious VRAM, often 8 GB minimum for small models and 24 GB or more for larger ones. With Hermes plus ChatGPT OAuth, the compute runs on OpenAI's infrastructure instead. That makes this setup ideal for integrated graphics, older laptops, or work machines with locked-down GPU drivers.

Reliability and Uptime

There are no model loading times, no quantisation trade-offs, and no thermal throttling. You get consistent availability instead of babysitting a local inference server.

When a Local Model Is Still the Better Choice

Local models still win in three cases: privacy-sensitive data that should never leave the device, genuine offline use, and extremely high usage volumes where per-request economics tip in favour of self-hosting. Usefully, Hermes supports both paths, so you are not locked in either direction.

Your AI stack costs real money every month. Make it earn some back. ChatGPT, Claude, and Gemini bill in USD, and a typical card adds 2-3% on every renewal. Bleap charges 0% FX fees and pays a flat 20% cashback on all three. Get the Bleap card →

FAQ: Running ChatGPT with Hermes Without an API Key

Do I need a ChatGPT Plus subscription to use Hermes with GPT models?

Yes, a paid ChatGPT Plus or Pro subscription is required. The OAuth device code flow authenticates against your subscription, and free-tier accounts cannot complete this flow. The ChatGPT Plus cost has held at $20 since launch, and the annual cost of ChatGPT Plus is $240, monthly billing only.

What is the Hermes terminal command to start the ChatGPT OAuth login?

Run hermes auth add openai-codex, or use hermes model and select the ChatGPT or Codex Subscription option. This starts the device code flow, printing a URL and a unique code that you confirm in a browser to complete authentication.

Which GPT models can I access through my ChatGPT subscription in Hermes?

That depends on your tier and current rollout. In 2026 the flagship family is GPT-5.6 Sol, Terra, and Luna. Run hermes models list after authentication to see exactly what your account can reach, since the rollout can still vary by account, region, and plan.

How is this different from using an OpenAI API key with Hermes?

An API key bills you per token via the OpenAI developer platform. OAuth login through your ChatGPT subscription uses your flat monthly plan instead. The API is a separate cost structure from ChatGPT subscriptions; you pay per million tokens processed, not per message or per month, and API access does not include a ChatGPT subscription and vice versa.

What should I do if the device code expires before I confirm it?

Device codes are short-lived. Simply re-run hermes auth add openai-codex to generate a fresh code and URL, then complete the browser confirmation promptly.

Can I use Hermes with a local model and switch to GPT when needed?

Yes. Hermes is provider agnostic and supports both local backends and cloud GPT models. Hermes Agent is provider agnostic; Nous Portal is one supported route, and OpenRouter, Ollama, direct providers, GitHub Copilot, Hugging Face, and OpenAI-compatible endpoints are also supported. Use hermes config set model <model-name> to switch at any time.

Conclusion: Use Your ChatGPT Subscription More Powerfully with Hermes

If you already pay for ChatGPT Plus or Pro, running it inside a terminal agent like Hermes unlocks value you are otherwise leaving on the table. The process is four steps: install Hermes, run the auth command, confirm in your browser, and select your GPT model. The payoff is no API key management, no per-token billing surprises, and no heavy local hardware. The one honest trade-off is that a paid subscription is non-negotiable for this workflow. From there, experiment with model switching, using a lighter model for speed and the flagship for heavy tasks.

One last practical tip for the bill itself. Your AI subscriptions renew in USD, and most cards quietly add 2-3% on every foreign charge. With Bleap you pay at the real rate with 0% FX fees, and on Claude, ChatGPT, and Gemini you earn a flat 20% cashback in USDC on every renewal, with no monthly card subscription. It is a self-custodial Mastercard you can use anywhere Mastercard is accepted, so the money your setup saves goes even further.