dsh-grok-build-auth-bridge

Reuse the official Grok Build CLI subscription login in DeepSeek Harness (DSH).

This package is a Host Cordis bundle. It reads Grok Build's local session, delegates refresh-token handling to the official grok binary, synchronizes only the short-lived access token into DSH's credential service, and provisions a pi-ai route for the Grok Build subscription proxy.

It does not contain, upload, or commit any token.

Requirements

• Node.js 22.19 or later
• DSH with the dsh-llm-pi-ai adapter
• The official Grok Build CLI installed and logged in:

grok update
grok login
grok models

The login must produce ${GROK_HOME:-~/.grok}/auth.json.

Install

Run this on each device after logging in with Grok Build:

npx --yes github:shaomingbo/dsh-grok-build-auth-bridge#v0.1.0

The installer adds the package and its Cordis bundle to ~/.dsh/profiles/web/package.json, then runs pnpm install. Restart dsh web afterward.

The plugin creates this model route through DSH settings without replacing existing providers:

• Provider: grok-build
• Model: grok-4.6
• Protocol: OpenAI Responses
• Endpoint: https://cli-chat-proxy.grok.com/v1

How it works

At startup, every ten minutes, and immediately before a grok-build LLM stream:

1. read ${GROK_HOME:-~/.grok}/auth.json; 2. select the first-party xAI OAuth session, excluding plain API-key entries; 3. check expires_at, JWT expiry, or Grok's 30-day fallback lifetime; 4. when near expiry, run the official grok models command and let Grok perform its own locked, race-safe OAuth refresh; 5. re-read the refreshed session and store only its access token as GROK_BUILD_ACCESS_TOKEN in DSH.

Using the official CLI for refresh preserves Grok Build's file-locking, team-principal parameters, refresh-token rotation handling, and sleep/suspend safeguards. The bridge never writes ~/.grok/auth.json itself.

The route sends the subscription proxy headers required by the official client, including X-XAI-Token-Auth, model override, client mode, and the locally installed Grok version from ~/.grok/version.json.

Environment overrides

If you override the provider ID or credential reference after the route has already been created, update or remove the old route in DSH's Models settings.

Security notes

• ~/.grok/auth.json contains a refresh token. The bridge refuses to read it on Unix if group or other users have access; use chmod 600 ~/.grok/auth.json.
• Only the short-lived access token is copied to $DSH_HOME/.credentials.yaml through the normal DSH credential service.
• The plugin never logs credential values or sends the refresh token anywhere.
• If GROK_BUILD_ACCESS_TOKEN is exported in the parent environment, it shadows DSH's writable credential store. Unset it before starting DSH.

Current model scope

The proxy requires x-grok-model-override at the provider-header level, while DSH provider headers are shared by every model on that route. Version 0.1.0 therefore exposes one verified route, grok-4.6. Additional Grok models can be added as separate provider routes in later releases.

Development

npm install
npm test
npm run check

The primary-source research behind the bridge is in [docs/research.md](docs/research.md).

License

MIT