Preface

When building agents with DeepSeek Harness, we often encounter tasks like batch rewriting copy, translating a batch of names into a target language, cleaning strings, or performing OCR on screenshots. These jobs are mechanical and repetitive with short outputs; if done only by online models, they consume real tokens.

On the other hand, many developers already load local models on their machines using Unsloth Desktop. The only remaining question is: how does the agent “reach” it? The answer from dsh-unsloth-hands is to register two tools into the harness’s tool registry, allowing the online model to delegate these types of tasks to the local model at the right moment.

What is it

dsh-unsloth-hands (Unsloth for DeepSeek Harness) is maintained by MicroHEROX, under the MIT license, current version 0.1.0. One-sentence positioning: a pure client-side tool plugin that allows the DeepSeek Harness online model to hand off repetitive text and visual (OCR) work to a locally running Unsloth Desktop.

Two design points determine its boundaries:

  • Pure client-side. The plugin does not start, own, or stop any processes; it only communicates with your running Unsloth Desktop via HTTP. Selecting models, downloading quantization packages, and setting context lengths are all done within Unsloth’s own interface.
  • Tools, not a backend. It does not replace the harness’s LLM provider—the online model remains the primary model, and the local model is only reached via tools; it also does not modify any files of DeepSeek Harness or Unsloth.

This approach aligns with the DSH “everything is a plugin” philosophy: capabilities are hooked into ctx.tools, and the main dialogue flow does not need to change.

Core Features

The plugin registers two model-facing tools, following the official dsh-tools contract (defineTool, canonical JSON values, pure render/presenters, exec.signal forwarding):

  1. unsloth_run: Runs a prompt against the local text model, suitable for batch rewriting, name translation, string processing, short summaries, and information extraction.

  2. unsloth_vision: Sends images to the local multimodal model for OCR, image analysis, and multi-image comparison, with structured report templates.

A few engineering details:

  • Authentication: Every request carries Authorization: Bearer sk-unsloth-…, with the key coming from the apiKey config or the UNSLOTH_API_KEY environment variable.
  • Fail-safe: Probes /v1/models before every call. When Unsloth Desktop is not running, it returns a clear actionable error instead of a generic network failure; key errors or missing keys return AUTH with a prompt.
  • Format: Non-streaming OpenAI-compatible chat-completions; images are sent as standard multimodal content arrays. Streaming responses are not supported; the tool call returns the complete answer at once.
  • Live Config: The llm-unsloth: section in the harness user settings documentation can override plugin configuration without restarting.

The vision tool has a built-in machine-verifiable report contract: analyze generates an 8-section report, ocr requires character-by-character precision, and compare outputs a 5-section comparison for multiple images; meanwhile, fidelity rules are set for the online model—verbatim rephrasing, no fabrication, and retaining uncertainty.

Installation and Enabling

Installation

This package is a standard harness bundle (declares dsh.bundle and accompanying cordis.patch.yml), usable with the official installation path:

dsh plugin --profile <name> add dsh-unsloth-hands        # from npm registry
dsh plugin --profile <name> add github:MicroHEROX/dsh-unsloth-hands   # straight from GitHub

When installing from GitHub, pnpm may require allowing the prepare build script in the profile’s pnpm-workspace.yaml first, then running add again:

allowBuilds:
  dsh-unsloth-hands: true

Installing from the npm registry does not require this step.

It can also be installed as a regular npm dependency in your harness project, then manually adding the plugin line:

npm install dsh-unsloth-hands

- insert:
    - id: unsloth-tool
      name: 'dsh-unsloth-hands'

Configuration

Do three things in order:

  1. Start Unsloth Desktop and load the model. Model download and loading are done within Unsloth’s interface; the plugin connects to the currently loaded model, so you don’t need to write the model name in the plugin.
  2. Create an API key: avatar → Settings → API → Create, copy the sk-unsloth-… value (only shown once).
  3. Insert the plugin line into the profile’s cordis.patch.yml and write the configuration:
- insert:
    - id: unsloth-tool
      name: 'dsh-unsloth-hands'
      config:
        baseURL: 'http://127.0.0.1:8888'              # Unsloth's default port
        apiKey: 'sk-unsloth-xxxx...'                   # From Unsloth Settings → API

You can also use the environment variable UNSLOTH_API_KEY instead of apiKey.

If already installed via dsh plugin add, the bundle automatically inserts the unsloth-tool line, and you only need to override the configuration in cordis.patch.yml:

- id: unsloth-tool
  config:
    apiKey: 'sk-unsloth-xxxx...'

See docs/api.md §1.2 for the full configuration reference (all 10 fields and default values).

How to Use the Two Tools

unsloth_run: Text

Parameters:

  • prompt (string, required): Instructions or text to send as a user message
  • system (string, optional): System instructions
  • temperature (number, optional): Sampling temperature, 0–2
  • max_tokens (integer, optional): Output limit, defaults to maxTokens in config
  • stop (string[], optional): Stop sequences

Returns: { text, reasoning?, model, usage, elapsedMs }.

unsloth_vision: Images and OCR

Parameters:

  • mode (analyze / ocr / compare, default analyze): Built-in prompt templates
  • prompt (string, optional): Custom instructions, overrides template
  • image_paths (string[], optional): Local images, supports png/jpg/jpeg/webp/gif/bmp, single image ≤ 20 MB
  • image_urls (string[], optional): data:image/... or http(s):// URLs
  • temperature (number, optional): Suggested around 0.2 for OCR
  • max_tokens, stop: Same as above

Returns: { text, reasoning?, model, images, usage, elapsedMs }.

Image sources are parsed in order: explicit image_paths + image_urls → the most recently attached images in the current session (read via harness attachment service) → explicit error. The compare mode sends 2–4 images in a single request for joint reasoning.

Applicable Scenarios and Considerations

Who is it for:

  • DSH users who already run Unsloth Desktop locally and have loaded GGUF/safetensors models, and want their agents to call them.
  • Workflows involving repetitive text processing (rewriting, translation, extraction) or screenshot OCR and multi-image comparison needs.
  • Visual functions requiring multimodal models, such as Qwen3-VL or Gemma vision GGUFs.

Environment Requirements: Node.js ≥ 20; DeepSeek Harness installed (npx @deepseek-ai/dsh web or source code checkout), version 0.1.0-rc series; Unsloth Desktop running, with a loaded model and an API key created.

A few notes:

  • The plugin does not take over the model lifecycle. If the service isn’t started or the model isn’t loaded, the tool will only error out; it won’t start or download anything for you, nor will it package or host GGUF model files.
  • Streaming is not supported. The tool call returns the complete answer at once; long outputs require waiting for the full result.
  • It is not an offline mode. The online primary model remains the primary model; the local model only participates when invoked by a tool.

Security Reminder: Like all third-party plugins, dsh-unsloth-hands runs with the current dsh process’s permissions. Although its design only involves HTTP communication and doesn’t touch any processes, it is still recommended to check the source code and license before installing. This project is under the MIT license, and the source code is publicly available on GitHub.

Conclusion

dsh-unsloth-hands solves a specific problem: it doesn’t modify the deployment of the primary model, doesn’t add management overhead to Unsloth, and just adds two tools to turn “the local model is there” into a capability directly usable by agents. If you are already using Unsloth Desktop, installation and configuration are just a few commands.

  • GitHub: https://github.com/MicroHEROX/dsh-unsloth-hands
  • Community Directory Page: https://www.skillhub.cn/plugins/MicroHEROX/dsh-unsloth-hands

The community directory is an independent site with no official affiliation to DeepSeek or Fantom.