DeepSeek-Harness Python SDK: Run the Agent Programmatically

deepseek-harness-sdk is DeepSeek-Harness's official Python package for driving the dsh agent programmatically, without installing Node.js yourself — it bundles a packaged runtime internally. Install it with pip install deepseek-harness-sdk, then drive a session through the DeepSeekHarness class instead of the Web UI or CLI.

Requirements and platform support

python -m pip install deepseek-harness-sdk

The SDK requires Python 3.10+. Platform support, per the official docs, is narrower than the Node.js CLI's:

Platform	Supported
Linux x64	Yes
Linux arm64	Yes
macOS 14+ (arm64)	Yes
Windows	Not documented as supported
Older macOS (Intel, or macOS <14)	Not documented as supported

If you need dsh on Windows, use the regular npm-based CLI path — see installing DeepSeek-Harness on macOS, Windows, and Linux — rather than the Python SDK.

A minimal example

from deepseek_harness import DeepSeekHarness

with DeepSeekHarness(
    provider="deepseek-official",
    model="deepseek-v4-flash",
    max_tokens=49_152,
    cwd=str(workspace),
    session_root=str(sessions),
    cordis=str(config),
) as harness:
    result = harness.run(
        "Inspect the repository and fix the failing tests.",
        session_id="example-001",
    )

print(result.final_response)

DeepSeekHarness is a context manager: entering it boots the bundled runtime, .run() submits a task to a session (creating it if session_id doesn't already exist), and the block exit tears the runtime down. cwd sets the workspace root the same way it works for the CLI, session_root controls where session state is persisted, and cordis points at a config file — the same cordis.patch.yml layering concepts from the configuration guide apply here.

Why a Python package bundles a Node.js-built runtime

dsh's actual agent loop, tool execution, and plugin system are implemented in TypeScript and run on the same runtime the CLI uses — the Python SDK doesn't reimplement any of that in Python. Instead, it packages a prebuilt copy of the dsh runtime alongside the Python bindings, so pip install gives you a working agent without a separate npm install -g step or a system Node.js version to manage. That tradeoff is also why the platform matrix above is narrower than the CLI's: the SDK has to ship a working prebuilt runtime for each supported OS/architecture combination, and as of August 2026 that list is Linux x64, Linux arm64, and macOS 14+ on arm64 — Windows support depends on that matrix growing, not on anything Python-specific.

Reading the constructor parameters

The DeepSeekHarness constructor in the example above takes a handful of parameters worth understanding individually, since they map directly onto concepts covered elsewhere in this guide series:

Parameter	What it controls
provider / model	Which model provider and model ID to route requests to — the same provider IDs you'd configure in $DSH_HOME/settings.yaml via Settings → Models
max_tokens	The output token ceiling for a single model response
cwd	The workspace root the agent treats as its filesystem boundary under workspace-write, or its unrestricted starting point under danger-full-access
session_root	Where session state gets persisted to disk — analogous to the profile-scoped session storage the CLI and Web UI use
cordis	Path to a config file layered the same way --patch layers apply to the CLI (see the configuration guide)

Because cordis accepts an arbitrary config file path, everything documented about patch layering, plugin bundles, and MCP server configuration applies identically whether you're launching through the CLI or driving a session through the Python SDK — the SDK doesn't have a separate, reduced configuration surface.

What's actually running underneath

The Python SDK isn't a separate reimplementation of dsh — it's a Python-language binding over the same stdio JSON-RPC protocol (@deepseek-ai/dsh-sdk-protocol) that the official TypeScript SDK (dsh-sdk-client, dsh-sdk-server) uses. Both SDKs drive a dsh runtime as a child process and exchange JSON-RPC messages over stdio — the Python package just ships that runtime pre-bundled so you don't need a separate Node.js install to make the child process work.

This is a different integration surface from ACP (Agent Client Protocol), dsh's other JSON-RPC-over-stdio interface. ACP (dsh-acp) is explicitly "automation-only," built for external GUI clients and orchestration systems that want to drive dsh generically; the SDKs (Python and TypeScript) are the path for embedding dsh's agent loop directly inside your own application code with a typed, language-native API. There is no publicly documented HTTP REST API for third-party integration — stdio JSON-RPC via SDK or ACP is the supported route.

The danger-full-access warning

The official example above pairs the SDK with danger-full-access — no sandboxing at all. The docs are explicit about what that means and where it's appropriate:

…should only be run in a one-off checkout or a container.

That's not a suggestion to ignore. danger-full-access disables the read-only/workspace-write sandbox boundary entirely — the agent's Bash and filesystem access is no longer confined to a workspace root or platform temp directory. If you're driving the SDK against a real, persistent checkout on your machine, use dsh's workspace-write permission preset instead (the same default new sessions get in the Web UI and CLI) — see our permissions and sandbox guide for the full breakdown of what each sandbox mode actually restricts.

SDK vs headless CLI vs ACP: when to use which

Interface	Best for
Headless CLI (dsh --profile headless "task")	One-shot shell scripts, CI steps — no code to write, just a process exit code
Python or TypeScript SDK	Embedding the agent loop inside your own application, with structured programmatic control over sessions and results
ACP (dsh-acp)	Building or integrating an external GUI/editor client that wants to drive dsh generically, not tied to a specific language runtime

If your use case is "run one task and read the final answer from a script," headless mode is simpler and doesn't require writing any SDK code. Reach for the SDK when you need multiple sessions, structured result objects, or tighter control over the agent's lifecycle from inside a larger Python (or TypeScript) program.

FAQ

Does the Python SDK need Node.js installed?

No — it bundles a packaged dsh runtime, described in the docs as needing "no system Node.js."

Can I use the Python SDK on Windows?

It's not documented as a supported platform; official support covers Linux x64/arm64 and macOS 14+ on arm64 only, as of August 2026.

Is the Python SDK feature-equivalent to the TypeScript SDK?

Both drive the same underlying stdio JSON-RPC protocol (dsh-sdk-protocol), so they're two language bindings over one wire protocol rather than two separate implementations — but check current package docs for any Python-specific API gaps.

Should I run the SDK example's danger-full-access config as-is?

Only in a disposable checkout or container, per the official warning. For anything touching a real working directory you care about, use workspace-write instead.

How is the SDK different from ACP?

The SDK is for embedding dsh's agent loop directly in your Python or TypeScript code. ACP is a separate, "automation-only" protocol aimed at external GUI/editor clients driving dsh generically, not at in-process embedding.

Next steps

For scripted, no-code automation instead of an SDK integration, see DeepSeek-Harness headless mode. Before running any SDK code against a real project, read permissions and sandboxing to pick the right permission preset. For the full command surface the SDK sits alongside, see the CLI reference.