Hermes Agent and Codex Subscription: OAuth Setup, Quotas, and API

Integrating Hermes Agent enables developers to route requests to OpenAI models using a consumer ChatGPT or Codex subscription through the OAuth Device Code flow. This approach eliminates the requirement for static API keys, but introduces technical and financial ambiguities. A successfully completed authentication handshake verifies only the technical validity of the account credentials—it does not define or guarantee the underlying billing mechanics for subsequent requests.

Scope and Boundaries: Confirmed Facts, Documentation Gaps, and Verification

When using Hermes Agent with Codex accounts, system interactions fall into three distinct categories:

Category	Documentation Status	Technical Implementation and Scope of Control
Confirmed	Officially documented	Authorization through the Device Code flow. Local token storage in ~/.hermes/auth.json. Credential import from ~/.codex/auth.json (without requiring a standalone Codex CLI installation). Automatic quarantine of revoked tokens.
Undocumented	Not officially disclosed	Eligible subscription plans and quota consumption rules. Official documentation does not specify supported tiers or how limits are deducted.
Requires Verification	User responsibility	Cross-referencing provider dashboard metrics before and after running the agent, accounting for potential telemetry latency, and separating subscription billing from independent API keys.

Documentation from Nous Research covers only the network handshake protocol and session renewal mechanisms. Official sources do not detail which subscription tiers qualify or how usage quotas are deducted; developers must independently verify account metrics in their provider dashboard prior to executing production tasks. Any claims asserting that accessing Codex models through an agent is “free,” “unlimited,” or included without constraints in base consumer plans are technically unfounded.

Configuration Procedure and Session Management

The Hermes architecture strictly divides persistent environment setup from runtime model switching:

• hermes model — Executed directly in the terminal outside of any active agent session. This wizard handles initial provider registration, launches browser-based OAuth authorization, and saves core configuration parameters.
• /model — An in-session chat command. It functions exclusively to switch between already configured providers and models. Registering new providers or initiating OAuth flows from inside the interactive chat is not supported.

Initial provider setup begins in the terminal by choosing ChatGPT or Codex Subscription from the configuration menu:

hermes model

Selecting this option prompts the console to output a one-time verification URL alongside a unique alphanumeric device code. Open the link in a browser, sign in to your OpenAI account, and authorize the connection. Once confirmed, Hermes stores the returned access and refresh tokens locally in ~/.hermes/auth.json. If the machine already has active credentials from the Codex CLI, the agent automatically imports them from ~/.codex/auth.json, removing the need for a separate Codex CLI package installation.

Authentication Error Handling and Token Quarantine

If the authorization server returns a fatal authentication error (such as an HTTP 4xx response, an invalid_grant status, or revoked access permissions), Hermes halts retry loops to prevent terminal log spamming. The invalid refresh token is moved into a local quarantine state. On subsequent attempts to run the agent, the system outputs a typed notice prompting the user to re-authenticate.

To reset the quarantine status and complete the login flow again, run:

hermes auth add openai-codex

Alternatively, rerun the hermes model setup wizard and re-select the subscription provider. Successfully refreshing the credentials clears the quarantine flag automatically.

Dedicated API vs. Subscription Access

OAuth connections backed by a consumer subscription and direct API connections using static keys operate in completely separate financial and infrastructure environments:

1. Subscription: Tied directly to a consumer ChatGPT account. Official documentation does not specify supported subscription plans or explain how OAuth-driven requests decrement quota balances. You must inspect your account state and billing counters before initiating agent tasks.
2. API Key: Configured when selecting the openai-api provider (via OPENAI_API_KEY in ~/.hermes/.env) or third-party gateways. Operational expenses follow the selected provider’s pricing schedule and are not always restricted to raw token volume.

If an agent deployment requires granular, per-request billing transparency or access to alternative open-weights models, subscription routes can be supplemented or replaced with a dedicated gateway. For an example of an independent architecture, review the BetterToken documentation, which provides standard OpenAI-compatible endpoints, personal access keys, and dashboard-level usage tracking. Dedicated third-party API routing operates as an isolated channel: it does not convert an existing ChatGPT/Codex subscription, does not draw from subscription quotas, and does not guarantee identical model availability.

Verification Checklist and Troubleshooting

Because the precise mechanics governing quota deductions under consumer subscriptions are not published, establishing an empirical baseline prior to regular use is strongly recommended:

1. Account Parameters: Check and document your active subscription tier and available balance inside the provider’s web console (supported plan requirements remain undisclosed).
2. Timestamp and Baseline: Record initial usage counters alongside the exact start timestamp of your test run.
3. Minimal Prompt: Start an agent session and execute a brief, tool-free query (for example: Calculate 256 * 4).
4. Balance Reconciliation: Re-examine the provider’s billing interface after a reasonable delay, as telemetry reporting latency is unspecified. A usage counter that does not update instantaneously does not indicate the call was free.
5. Security Hygiene: Never share ~/.hermes/auth.json credentials with third parties or publish raw terminal session logs containing token fragments.

If Hermes returns an HTTP 403 error or reports insufficient permissions following a successful login, the underlying cause specific to Codex remains undocumented. Examine the response payload, confirm account eligibility and permission levels, verify the selected route and model ID, and consult official provider documentation or customer support. When needed, switching to a dedicated API provider with a personal access key offers an alternative path.