Introduction

The design philosophy of DeepSeek Harness (DSH) is “everything is a plugin.” For developers, integrating diverse model capabilities into local or private environments is a common requirement. The dsh-llm-grok plugin addresses how to connect X.AI’s Grok subscription quota to DSH as a unified LLM provider, allowing developers to directly use Grok’s reasoning and multimodal capabilities within the DSH ecosystem.

Plugin Overview

This plugin is maintained by user clarkzhao and is released under the MIT open-source license. The project currently has 1 star on GitHub.

The core function of the plugin is to integrate the Grok subscription quota into DSH as an LLM provider.

Core Features

  • Native multimodal support: Supports user-pasted images and images in tool-result messages, sent together with /chat/completions. Images are not first OCR’d into text and then passed to a text model, nor are they treated as a separate image-recognition tool.
  • Supported models: Supports Grok 4.6, 4.5, 4.7, and 4.7-build-fast.
  • Reasoning strength: Supports low / medium / high / xhigh reasoning-strength settings.
  • Network proxy: Uses the local HTTP proxy, with the default configuration set to Clash’s 127.0.0.1:7890.

Installation

Before installation, ensure DSH is already installed. Run the following command to add the plugin to the specified profile (default: web):

dsh plugin --profile web add dsh-llm-grok

If dsh is not installed globally, you can use npx:

npx @deepseek-ai/dsh plugin --profile web add dsh-llm-grok

After installation, the bundle is written to llm-grok and registers the grok provider. If a grok provider with the same name was previously added in llm-pi-ai, remove it first to avoid routing conflicts.

Configuration and Credentials

The plugin does not read ~/.grok/auth.json, and it does not automatically renew tokens. It only resolves the DSH credential reference GROK_SESSION_TOKEN.

The access token from the Grok CLI is valid for approximately 6 hours. Once it expires, it causes a 401 error, so it must be manually synced into DSH.

Credential Sync Steps

  1. Obtain the token: Run grok login in the terminal to write the token to ~/.grok/auth.json.
  2. Write it to DSH: Run the sync script to write the token into DSH’s credentials file (default: ~/.dsh/.credentials.yaml):
    python3 scripts/sync-grok-credential.py
  1. Automated sync (recommended): To handle the 6-hour expiry cycle, you can install a launchd task via the script to sync automatically every 5 minutes:
    chmod +x scripts/install-launchd.sh
    ./scripts/install-launchd.sh

Environment Variable Configuration

You can also set the environment variable GROK_SESSION_TOKEN before starting the DSH process. The environment variable has higher priority than the credentials file: if it exists at startup, syncing from the file cannot overwrite its value. You must run unset GROK_SESSION_TOKEN and restart.

Credentials File Format

The sync script writes credentials into a YAML file with the following format:

version: 1
refs:
  GROK_SESSION_TOKEN: <token>

Note: Do not add a flat GROK_SESSION_TOKEN: key at the top level of a file that already contains version: 1, otherwise it may cause dsh web to fail to start.

Limitations and Notes

  • No automatic renewal: The plugin does not handle token refresh; it relies on external scripts or environment variables.
  • API implementation: It only uses the chat-completions endpoint and does not implement the Responses API used by default in the official CLI.
  • Image handling: Session logs store only attachment references (sha256:); pixel data is read from ctx.attachments only when sending requests.
  • Error handling: If the attachment service is missing or an image appears in a system / assistant message, an UNSUPPORTED_CONTENT error is returned.
  • No lazy refresh: There is no refresh_token lazy-refresh mechanism (option B is not implemented).
  • Permissions: The plugin runs with the permissions of the current DSH process. It is recommended to review the source code and license before installation.

Summary

dsh-llm-grok provides a viable path for integrating Grok subscription access into DSH, and its native multimodal support is especially convenient for certain scenarios. Be aware of the manual token sync mechanism when using it.