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

Variable	Default	Purpose
DSH_GROK_AUTH_PATH	${GROK_HOME:-~/.grok}/auth.json	Exact Grok auth file
DSH_GROK_VERSION_PATH	${GROK_HOME:-~/.grok}/version.json	Installed Grok version metadata
DSH_GROK_BIN	${GROK_HOME:-~/.grok}/bin/grok	Official CLI executable
DSH_GROK_AUTH_SCOPE	auto-detected	Exact auth.json scope for multiple-session files
DSH_GROK_CREDENTIAL_REF	GROK_BUILD_ACCESS_TOKEN	DSH credential reference
DSH_GROK_PROVIDER_ID	grok-build	DSH provider route ID
DSH_GROK_CLIENT_VERSION	version.json value; fallback 1.0.3	Proxy version header override
DSH_GROK_REFRESH_MARGIN_MS	300000	Refresh margin before expiry
DSH_GROK_SYNC_INTERVAL_MS	600000	Background synchronization interval

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.

License

MIT