Introduction

DeepSeek Harness provides a plugin-based architecture that allows developers to access different LLM services through routing. Although the official Grok CLI supports OAuth login via a SuperGrok or X Premium subscription, this login state is not directly integrated into Harness’s routing system. For developers who need to use Grok 4.x models (such as grok-4), it is usually necessary to maintain a separate API key, which is decoupled from the subscription mechanism of the official CLI.

The dsh-grok-auth plugin solves this problem. It reuses the authentication file maintained by the official Grok CLI, ~/.grok/auth.json, and bridges xAI’s subscription OAuth login state into Harness’s xai LLM route.

What It Is

This is a self-contained DeepSeek Harness plugin maintained by Gyanano. It does not generate a new API key; instead, it reuses the login flow and credentials of the official Grok CLI. Once activated, the plugin adds a Grok Auth card to the Harness settings for managing login state and viewing usage, while automatically registering the xai LLM route.

Core Features

Shared Grok Login State

The plugin uses a Host-level authentication coordinator. It manages tokens (which expire after approximately six hours) through version-bound authentication file snapshots, an in-memory cache, and proactive refresh mechanisms. To avoid conflicts with the official CLI’s lock file, the plugin uses auth.json.dsh.lock for inter-process locking. During refresh, the plugin validates the lineage of the refresh token, ensures the atomicity of write operations, and sets the file permissions to 0600.

Dual Login Flows

  • Browser login: Calls the official grok login command directly, allowing the CLI to complete the full PKCE flow and write the authentication file.
  • Device code login: Runs the RFC 8628 flow inside the Host, using the same public client ID as the CLI and supporting Headless environments.

xai LLM Route

The xai route wraps the installed pi-ai xai directory provider (api.x.ai/v1). It injects the subscription OAuth access token as a Bearer credential into every request, while the request wire protocol, tool calls, and streaming are all managed by the provider.

Live Model Discovery

The installed pi-ai directory is a static snapshot. When liveModels is enabled, the plugin overlays the account’s live GET api.x.ai/v1/models list. It synthesizes unlisted models from curated templates (such as grok-4.6) and re-declares the route when the model list changes. Media models (such as grok-imagine-*) are skipped.

Weekly Usage

The settings card attempts to retrieve a weekly credit snapshot from the Grok proxy backend (cli-chat-proxy.grok.com/v1/billing?format=credits). If retrieval fails, it simply displays a dash and does not block login or requests.

Installation and Enablement

It is recommended to install the prebuilt release package. This package includes prebuilt Host and browser bundles and does not require build permissions during installation.

dsh plugin --profile web add https://github.com/Gyanano/dsh-grok-auth/releases/latest/download/dsh-grok-auth-latest.tgz

After installation, restart dsh web, open the settings page, and select Grok Auth from the plugin list.

Typical Usage

After installation, a new llm-grok-auth line is added to the Harness Host configuration. All configuration options are optional:

  1. Control route registration: Set llmEnabled: false to enable only the shared login state coordinator, without registering the xai LLM route.
  2. Customize the authentication file path: Override the default $GROK_HOME/auth.json using authJsonPath.
  3. Customize the API endpoint: Override the directory’s default api.x.ai/v1 using baseUrl.
  4. Enable live models: Keep liveModels: true to overlay the account’s live model list.

Use Cases and Notes

Use case: You need to use Grok models in Harness, want to reuse your X Premium subscription quota, and do not want to maintain an additional API key.

Important limitations and security:
- Security: Token values never enter the browser, settings, logs, or session events. Only Host-side requests receive the authorization header.
- Locking: The official CLI does not participate in the plugin’s write lock. The plugin uses a “fail-closed recovery” strategy (validating lineage and adopting the new state) rather than absolute cross-client serialization.
- OAuth client: The public OAuth client ID belongs to the official Grok CLI, and xAI has not committed to keeping it available to third parties long-term.
- Official warning: This plugin is an unofficial channel and is intended for personal development use only. Account-based subscription surfaces (auth.x.ai) are unsupported, can be revoked, and may be rate-limited or changed.

License: Based on the available text, the license field is not explicitly defined (only a LICENSE file is mentioned). Please check the source code to confirm.