grok-oauth-proxy

Grok OAuth Proxy is a small local server that lets you talk to xAI's Grok models from any tool that already understands the OpenAI API, without having to obtain or pay for an xAI API key directly. It does this by piggybacking on the browser-based OAuth login that another tool, Hermes Agent, has already completed on your machine. The proxy reads the OAuth tokens that Hermes saved in ~/.hermes/auth.json, copies them into its own permission-locked file, and uses them to call api.x.ai on your behalf.

It is written in Python with the FastAPI framework. To a client like LiteLLM, the OpenAI Python SDK, or a plain curl command, it looks like a normal OpenAI server at http://127.0.0.1:9996, exposing the usual /v1 routes including streaming chat completions. Behind the scenes it strips client credentials, injects a short-lived Bearer token, and forwards the request to xAI.

The project takes a fail-closed approach to safety. At startup it verifies that Hermes is installed, that the xai-oauth provider is present, and that an OAuth client id is available; if any of that is missing, it refuses to start rather than falling back to anonymous credentials. Token refreshes are handled in a background loop with prewarming before expiry, plus a watcher on the Hermes auth file so that re-logins are picked up automatically. There is a /health endpoint with an optional deep mode that pings upstream, a /metrics endpoint for Prometheus, and automatic retries on transient upstream failures for idempotent requests.

Installation is documented for two scenarios: a desktop Mac where Hermes already did the browser login, and a headless Linux server that imports an exported OAuth bundle from a desktop machine. systemd and launchd recipes are provided for keeping it running.

The full README is longer than what was shown.