Skip to main content
All posts
Guide

DeepSeek Harness FAQ: 30 Common Questions Answered

30 short, fact-checked answers about DeepSeek Harness (dsh) — installation, cost, security, MCP, plugins, Claude Code comparisons, and the Python SDK.

DeepSeek Harness (dsh) is DeepSeek AI's open-source, MIT-licensed agent harness, built around a single "everything is a plugin" extension mechanism. This page answers the 30 questions developers ask most often about installing, configuring, extending, and evaluating it — each answer sourced from dsh's own documentation, with a link to go deeper.

We've grouped the questions into six sections — basics, installation, configuration concepts, plugins, MCP/Claude Code/migration, and advanced/practical topics — so you can jump straight to the section closest to what you're trying to figure out, rather than scanning 30 questions in one flat list.

The basics

What is DeepSeek Harness?

DeepSeek Harness (dsh) is an open-source agent harness developed by DeepSeek AI, built on the Cordis plugin framework under the principle that every capability — tools, commands, skills, MCP bridges, model adapters — is implemented as the same kind of plugin. It's currently in developer preview. See What Is DeepSeek Harness? for the full introduction.

Is DeepSeek Harness free?

The harness itself is free and MIT-licensed. You still pay for whatever model API you connect it to (DeepSeek's own, or any other provider you configure), the same way you would with any other coding agent. See Is DeepSeek Harness Free? for how licensing and API costs actually break down.

Is DeepSeek Harness safe to install and run?

The harness code itself is open source and MIT-licensed, so it's inspectable. The bigger risk sits in the plugin ecosystem: installing a plugin means running its code on your machine, and there's no official marketplace vetting submissions — discovery happens through a GitHub topic, and a dsh.bundle manifest field is the only structured signal that a package is actually a plugin rather than an unrelated project. Read our plugin security checklist before installing anything from an unfamiliar author, especially anything that requires an allowBuilds permission grant at install time.

Is DeepSeek Harness stable enough for production?

No, not as of this writing. dsh is explicitly a developer preview with no SemVer promise and no GitHub Releases history — its own README states there will be compatibility-breaking changes. See our first-week developer reaction roundup for how the community is currently treating that status.

Is DeepSeek Harness the same thing as an agent framework or SDK?

Not exactly — a harness is broader. It's the whole runtime wrapped around a model: the tool loop, context management, permissions, session handling, and extension mechanism, not just an API for calling a model. See What Is an Agent Harness? for the general definition dsh is one example of.

Installation and setup

How do I install DeepSeek Harness?

The fastest path is running it directly from npm without cloning anything:

npx @deepseek-ai/dsh web

This starts the Web UI at http://127.0.0.1:3080. For platform-specific steps and known gotchas, see Installing DeepSeek Harness on macOS, Windows, and Linux and the general Quickstart.

What are the system requirements?

Node.js ^22.19.0 or >=24.0.0, and pnpm on your PATH for plugin installation (pnpm ≥10 specifically, due to how it handles build-script permissions on git dependencies). The Python SDK has separate, narrower platform requirements — see the Python SDK question below.

Does DeepSeek Harness run on Windows?

Yes, but with a few documented rough edges: a native directory-picker bug (workaround: switch to the directory-picker-browse backend), reports of Chinese-language path handling issues, and a Node/zlib version error if your Node install predates 22.15. See Installing on Windows for the specific fixes.

What models can I use with DeepSeek Harness?

DeepSeek's own models natively, plus a built-in provider directory for Anthropic, OpenAI, Bedrock, Vertex, Azure, and Codex-native authentication, plus any OpenAI-compatible custom endpoint. See Using OpenAI, Anthropic, or Any OpenAI-Compatible API with DeepSeek Harness for how to add a provider that isn't in the built-in list.

How do I set up my DeepSeek API key?

Through the Web UI's Settings → Models panel — paste your key into the DeepSeek card and save; no restart required. Keys are stored in $DSH_HOME/.credentials.yaml and the UI only ever shows a redacted reference back to you, never the plaintext. Full walkthrough: DeepSeek Harness API Key Setup.

Configuration concepts

Can I connect Claude or GPT models instead of DeepSeek's models?

Yes — either through the built-in Anthropic/OpenAI provider entries, or by adding a custom OpenAI-compatible provider if you're routing through a gateway. Note that DeepSeek's own native chat-completions route is text-only; if you need image input on a custom model, you have to explicitly declare input: [text, image] for it in settings.yaml. See API key and model setup.

What is a "profile" in DeepSeek Harness?

A profile is a named, runnable configuration under $DSH_HOME/profiles/<name> — it bundles together which plugins are active and your own overrides. web and headless are reserved names that auto-initialize from templates; any other profile name starts from just the base bundle. See Profiles and Bundles Explained.

What is a "bundle"?

A bundle is what a plugin package contributes — declared via a dsh.bundle field in its package.json, pointing at a YAML patch file that describes what it inserts into the Cordis plugin tree. Profiles are made of one or more bundles, layered in order. Same source: Profiles and Bundles Explained.

What is headless mode?

A one-shot, non-interactive way to run dsh: dsh --profile headless "task text" runs a task, prints the final response, and exits with code 0 on completion (1 otherwise). It has no listening port at all — no Web UI, no API proxy — which makes it well suited to scripting and CI. See DeepSeek Harness Headless Mode.

Is there a DeepSeek Harness CLI?

Yes — the dsh command itself is the CLI, with four entry modes (--profile <name>, --profile headless "task", dsh web, and dsh plugin). See Is There a DeepSeek CLI? and the full CLI cheat sheet.

Plugins

How do I install a plugin?

dsh plugin --profile <profile-name> add <specifier>

The command forwards its arguments directly to pnpm, so anything pnpm can install — an npm package name, github:owner/repo, a local path, or a tarball — works as the specifier. Full details: How to Install DeepSeek Harness Plugins.

Where do I find DeepSeek Harness plugins?

There's no official marketplace — dsh's only sanctioned discovery mechanism is the GitHub topic dsh-plugin. FindHarness indexes plugins primarily from the community-maintained awesome-dsh-plugin list plus additional discovery sources, verified against each package's dsh manifest field. Browse the full catalog at /plugins, or read How to Find DeepSeek Harness Plugins for a comparison of discovery sources.

How do I know if a plugin is safe before installing it?

Check whether the package actually declares a dsh.bundle field, read what its patch file inserts, check for a prepare script (which runs arbitrary code at install time if you grant allowBuilds), and pin to a specific commit if installing from GitHub rather than npm. The full ten-point process is in our plugin security checklist.

How do I write my own plugin?

A dsh plugin is a plain TS/JS module exporting an apply(ctx, config) function — there's no separate manifest file format. The simplest possible plugin:

import type { Context } from '@deepseek-ai/cordis'

export const name = 'my-plugin'

export function apply(ctx: Context) {
  // Register capabilities here.
}

See our plugin development primer for the full walkthrough, including tool registration and publishing.

How is dsh's plugin ecosystem organized by category?

FindHarness organizes indexed plugins into twelve categories — UI enhancements, themes, memory, tools & capabilities, workflow & automation, sessions & messages, notifications & integrations, MCP connectors, models & providers, development & runtime, skills, and just-for-fun. Browse them all at /plugins, or see our plugin categories map for representative picks in each one.

MCP, Claude Code, and migration

Does DeepSeek Harness support MCP servers?

Yes, as a first-class, fully documented feature — not an experimental placeholder. Each MCP server becomes one @deepseek-ai/dsh-mcp-client plugin instance, supporting both stdio and streamable-http transports with automatic reconnection (exponential backoff, up to a configurable number of consecutive failures before it gives up until the next reload). See How to Use MCP Servers with DeepSeek Harness.

Is dsh's MCP support the same as Claude Code's?

Close, but narrower. dsh names bridged tools mcp__<serverName>__<rawName>, the same server-qualified shape Claude Code uses — but dsh's MCP client bridges only Tools; Resources and Prompts are documented as deferred with no consumer yet. See DeepSeek Harness vs Claude Code for the full comparison.

What is the difference between DeepSeek Harness and Claude Code?

The headline difference is architectural: dsh collapses tools, commands, skills, hooks, and MCP bridges into one plugin mechanism, while Claude Code treats them as separate systems with their own file formats and ships an official marketplace. They aren't purely rivals either — dsh can delegate work to Claude Code as a subagent. Full breakdown: DeepSeek Harness vs Claude Code.

Can DeepSeek Harness use Claude Code as a subagent?

Yes — dsh-subagent-claude-code is an official subagent provider that drives Claude Code through its own Agent SDK, alongside providers for Codex, Agent Client Protocol, and in-process agents. See DeepSeek Harness Subagents and our migration guide if you're moving a Claude Code workflow over.

Can I reuse my Claude Code hooks.json in DeepSeek Harness?

Yes, through the official dsh-hooks-claude-code bridge plugin, which translates hook events into dsh's own extension-point listeners. A parallel dsh-hooks-codex bridge exists for Codex CLI hooks. See Hooks and Slash Commands in DeepSeek Harness.

Advanced and practical

Are Claude Code Skills compatible with DeepSeek Harness?

Not confirmed either way. dsh has its own Skill provider registry (ctx.skills), architecturally distinct from Claude Code's SKILL.md convention, and a community Discussion (#88) asking about compatibility hasn't been answered with an official yes in dsh's documentation. The community plugin dsh-skillport bridges existing SKILL.md libraries as a third-party workaround. Details in our migration guide.

Is there a Python SDK?

Yes — deepseek-harness-sdk on PyPI, requiring Python 3.10+ and limited to Linux x64/arm64 and macOS 14+ (arm64); it bundles its own runtime, so you don't need a separate Node.js install. There's also a TypeScript SDK, both built on the same underlying stdio JSON-RPC protocol. See DeepSeek Harness Python SDK.

What sandboxing or permission options does DeepSeek Harness have?

Three sandbox modes — read-only, workspace-write (the default for new sessions, confining writes to the workspace root and platform temp directories), and danger-full-access (no isolation at all) — backed by platform-specific enforcement (bwrap/Landlock on Linux, Seatbelt on macOS, an ACL-restricted token approach on Windows, plus an E2B cloud sandbox option for teams that want execution off the local machine entirely). These pair with approval policies into "permission presets," of which the default configuration ships exactly two. Full details: Permissions and Sandboxing in DeepSeek Harness.

Can I expose the Web UI to my network?

No — --host 0.0.0.0 is explicitly unsupported, and attempting it produces an error. The documented reasoning is direct: doing so "would expose remote code execution to the network," and the Web UI is designed for 127.0.0.1 only. If you need remote access, you're responsible for your own tunneling or port-forwarding setup, and even then, some workspace and file-picker functionality has been reported not to work fully through a forwarded connection — treat this as an unofficial, unsupported path rather than a documented feature.

Where do I report bugs, find official docs, or check the current version?

As of this writing the npm-published version is 0.1.0-rc.6, notably ahead of the version string in the repository's own master branch package.json (0.1.0-rc.5) — check npm view @deepseek-ai/dsh version for the ground truth, since there's no GitHub Releases page to rely on instead. GitHub Issues are disabled on the dsh repository; the official feedback channels are GitHub Discussions and a Discord community linked from the project README. There's also a VitePress-based, bilingual documentation site auto-built from the docs/ directory, though we link directly to files in the GitHub repository throughout our articles since the hosted documentation domain has shown rate-limiting behavior.

Next steps