DeepSeek Harness Python SDK: DSH plugin programmatic use

DeepSeek Harness ships an official Python SDK: after pip install deepseek-harness-sdk, a DeepSeekHarness context manager drives a sdk-minimal profile from your Python code — configuration is composed from the profile, the home patch, and any patches you pass, and session logs land in $DSH_HOME/sessions as uncompressed JSONL (source).

Installing the DeepSeek Harness Python SDK

The prerequisites are Python 3.10+ and Git; run pip install deepseek-harness-sdk, and the install comes with a matching native runtime wheel and the dsh command, so normal SDK runs do not need system Node.js (source). Steps:

1. Check platform and version — Linux x64/arm64, macOS 14+ on arm64, or Windows x64, plus a DeepSeek-compatible API endpoint and credentials. Expected: satisfy these first so the native wheel matches.
2. Create an isolated environment — make and activate a virtualenv (Linux/macOS: python -m venv .venv then . .venv/bin/activate; Windows: py -3.10 -m venv .venv and activate). Expected: python -m pip install deepseek-harness-sdk installs into it.
3. Prepare an isolated workspace and home — use a disposable workspace and a separate dsh_home. Expected: the SDK uses only the home you pass and never reads ~/.dsh.
4. Export credentials — set DEEPSEEK_API_KEY; with a compatible proxy also set DEEPSEEK_BASE_URL. Expected: credentials enter the runtime from the environment.

Running a task with DeepSeekHarness

In code, use DeepSeekHarness as a context manager with provider, model, cwd, dsh_home, and profile, call harness.run(prompt, session_id=...), and read result.final_response (source). Minimal usage:

from pathlib import Path
from deepseek_harness import DeepSeekHarness

workspace = Path("/absolute/path/to/disposable-workspace").resolve()
dsh_home = Path("/absolute/path/to/example-dsh-home").resolve()
with DeepSeekHarness(
    provider="deepseek-official",
    model="deepseek-v4-flash",
    max_tokens=49_152,
    cwd=str(workspace),
    dsh_home=str(dsh_home),
    profile="sdk-minimal",
) as harness:
    result = harness.run(
        "Inspect the repository and fix the failing tests.",
        session_id="example-001",
    )

print(result.final_response)

Key points:

1. The process starts lazily — the SDK lazily starts an internal dsh --profile sdk-minimal process and reuses it until the context manager exits. Expected: the process is reclaimed after the with block.
2. No separate Python runtime — there is no standalone Python runtime bin or a full set of configuration options; everything still goes through profiles and patches. Expected: concepts stay unified in DeepSeek Harness's own configuration system.
3. New home to isolate, new session id for independent work — reuse the harness, home, and id only to continue the same persistent conversation. Expected: mixing them silently resumes the wrong session.

DSH plugins and the minimal profile: installing, patching, enabling str_replace_editor

Use dsh plugin to persist dependencies and bundle layers in that home; persist config changes in $DSH_HOME/profiles/sdk-minimal/cordis.patch.yml, or pass a patch from Python for one run (source). Three steps:

1. Initialize the profile — run dsh --profile sdk-minimal --dump-default-config >/dev/null. Expected: the bundled standalone profile is initialized.
2. Install a plugin bundle — use dsh plugin --profile sdk-minimal add file:/absolute/path/to/my-plugin-bundle, which forwards package management to pnpm and records every installed package that exports a dsh.bundle layer. Expected: pnpm is needed only for this management command, not to start an already-installed SDK. To find existing plugins, browse community ones on DSH Plugin Hub.
3. Enable str_replace_editor on demand — the bundled runtime includes it, but sdk-minimal does not mount it by default. Write an editor.patch.yml that uses insert to add the filesystem backend and editor back, then pass it via patches or persist it in cordis.patch.yml. Expected: after the next start, the model can use the tool beyond the persistent shell.

# editor.patch.yml
- insert:
    - id: fs-local
      name: '@deepseek-ai/dsh-fs-local'
      config:
        cwd: !!js process.cwd()
    - id: tool-str-replace-editor
      name: '@deepseek-ai/dsh-tool-str-replace-editor'

Note: another profile is valid only if it includes @deepseek-ai/dsh-sdk-app or another JSON-RPC server entry; a missing server entry, an unresolvable plugin, or an invalid patch fails at startup rather than falling back to another composition.

Understanding the sdk-minimal profile

sdk-minimal inserts a full config tree over an empty root without dsh-base, so tools added to the base profile later never appear implicitly (source). Its defaults:

The profile contains the SDK protocol, an environment-configured DeepSeek adapter, local execution, and persistence. Filesystem tools, settings, managed credentials, OTel telemetry, web tools, subagents, local instruction discovery, and compaction are all absent. It also pins danger-full-access, so the persistent shell can modify any path visible to the runtime — always use a disposable checkout or container.

Notes and common questions

1. ~/.dsh is never read: the SDK uses only the dsh_home you pass; that isolation is deliberate.
2. Permissions are broad: under danger-full-access the shell can write any visible path, so isolate the environment.
3. Session logs are uncompressed: JSONL under <dsh_home>/sessions; watch disk usage and privacy, as in Where DeepSeek Harness session history lives.
4. The Web UI is not in the SDK: for a browser app in a Python SDK deployment, run dsh web against an explicit DSH_HOME; web is a standalone CLI app and cannot serve a Python SDK client.
5. Changing models or adding self-hosted services: adjust providers and credentials, as in Configure DeepSeek Harness model providers.

Sources: Python SDK (official docs), dsh CLI README