DeepSeek Harness (dsh)

What is DeepSeek Harness (dsh)?

DeepSeek Harness (dsh) is an open-source agent runtime and framework developed by DeepSeek AI. It is built on the Cordis plugin kernel, where every component—from AI models and tools to sessions, sandboxes, and the agent loop itself—is a replaceable plugin. dsh is not a new AI model; rather, it is the "harness" that equips a model with a workspace, tools, permissions, memory, and a structured execution environment to complete tasks.

Key Features of DeepSeek Harness

DeepSeek Harness distinguishes itself through its modular, plugin-first architecture designed for flexibility and ownership.

• Everything is a Plugin: The core principle of dsh. Capabilities like model adapters, tool registries, session logging, sandboxing, and even the user interface are implemented as plugins. This allows any layer of the agent system to be swapped or extended without modifying a monolithic core.

• Composable Runtimes: Users can assemble their agent runtime by stacking "bundles" of plugins and applying configuration "patches." dsh ships with several predefined agent "presets" (Standard, Code, Minimal, Creator) that share the same plugin core but expose different capabilities.

• Fully Local Execution: dsh runs on your local machine (defaulting to http://127.0.0.1:3080), not on a remote server. This gives users full control over their data and execution environment.

• Append-Only Session Log: Every action—model prompts, reasoning, tool calls, results—is recorded in an immutable session log. This enables powerful features like step-by-step inspection ("Trajectory" view), replay, forking runs from any point, and resuming work.

• Extensive Plugin Ecosystem: A vibrant community has rapidly developed hundreds of plugins (categorized under dsh-plugin on GitHub) that add new tools, user interfaces, browser control, alternative agent loops, and sandboxing solutions.

• Developer-Focused & MIT Licensed: As a developer preview project with an MIT license, dsh is aimed at teams and developers who want to own, customize, and build upon their agent infrastructure rather than use a closed, hosted service.

How to Use DeepSeek Harness

Using DeepSeek Harness involves local setup, configuration, and leveraging its plugin system to tailor the agent to your needs.

1. Quick Installation & Startup

• Prerequisites: Ensure you have Node.js (v22.19+ or v24+) installed.

• Start the Web UI: Run npx @deepseek-ai/dsh web in your terminal. This command downloads and starts the dsh Web UI, which will be accessible at http://127.0.0.1:3080.

• Initial Configuration:

  • Open the Web UI and navigate to ### Settings > Models.
  • Add a DeepSeek API key (or credentials for another supported provider like Anthropic or OpenAI).
  • Select a ### workspace directory (a local folder for the agent to operate within). The session composer will be unavailable until a workspace is chosen.

2. Running from Source (For Development)

• Clone the repository: git clone https://github.com/deepseek-ai/deepseek-harness
• Install dependencies: pnpm install
• Build the project: pnpm run build
• Run the local build: pnpm dsh web

3. Extending with Plugins

• The power of dsh lies in its extensibility. You can install community plugins directly into a profile.
• Example: To install a Terminal UI plugin, run dsh plugin add dsh-cc-tui.
• Plugins can be managed and inspected via the Web UI's plugin settings panel.

4. Understanding Runtime Modes

• Standard Mode: The full-featured coding agent with file editing, shell, search, skills, and subagents.

• Code Mode: Exposes tools via a TypeScript SDK, allowing the model to orchestrate complex multi-step operations in a single program.

• Minimal Mode: A stripped-down environment with only a persistent bash and a file editor, ideal for benchmarking AI models.

• Creator Mode: Standard Mode plus runtime inspection tools, designed for authoring new agent presets and testing plugin combinations.

Price of DeepSeek Harness

DeepSeek Harness itself is ### completely free and open-source under the MIT license. There are no subscription fees or licensing costs for the software.

• Costs to Consider:

  • Model API Costs: You must provide your own API keys for the AI models (e.g., DeepSeek, OpenAI's GPT-4, Anthropic's Claude). You will incur charges based on the usage and pricing of your chosen model provider.

  • Infrastructure: Since it runs locally, your "infrastructure" is your own computer. There are no server hosting fees.

  • Development Time: As a developer-preview framework, tailoring dsh to specific production needs requires technical investment.

Helpful Tips for Using DeepSeek Harness

• Start with the Web UI Preset: The web profile is the easiest way to start. It auto-initializes with a sensible default configuration.

• Inspect Your Configuration: Use dsh web --dump-config to print the exact plugin tree your instance boots with. This is invaluable for debugging and understanding how to patch it.

• Leverage the Trajectory View: After a run, use the Trajectory tab to inspect every step of the agent's work. This transparency is key to understanding failures and optimizing prompts.

• Manage Workspaces Carefully: The agent operates within the directory you select. Ensure it has the necessary permissions and contains the context (code, files) needed for the task.

• Be Mindful of Plugin Sources: Community plugins are not audited by DeepSeek AI. Review the source code of any plugin before installing it, especially if it requests filesystem or network access.

• Expect Changes: The project is in "developer preview." While stable for experimentation, breaking changes to core APIs and plugins are expected before a 1.0 release.

Frequently Asked Questions (FAQ)

Is DeepSeek Harness a new AI model from DeepSeek?

No. DeepSeek Harness (dsh) is not a model. It is a framework—a "harness"—that provides an environment for existing AI models (like DeepSeek's own models, or Claude, or GPT-4) to use tools and complete tasks.

What's the difference between the official "DeepSeek Harness" and the Python "deepseek-harness"?

They are two completely unrelated projects with coincidentally similar names. The official dsh (this article's subject) is a TypeScript/Node.js agent runtime from DeepSeek AI. The Python deepseek-harness is an independent community-built client library for the DeepSeek V4 API.

Can I use models other than DeepSeek's with dsh?

Yes. dsh supports multiple "model adapters" via plugins. It includes support for DeepSeek, OpenAI, Anthropic, and other providers that offer an OpenAI-compatible API endpoint.

Is it safe to run dsh? Does it access my files?

dsh runs locally and only accesses files within the workspace directory you explicitly select. Sandboxing plugins can further restrict permissions. However, as with any software that executes code, you should only run it in workspaces with trusted content and be cautious with plugins from unvetted sources.

Why would I choose dsh over a hosted agent like Claude Code?

Choose dsh if you prioritize data privacy (everything stays local), need deep customization of the agent's capabilities, want to own and modify the runtime, or are building an internal platform. Choose a hosted agent for a more turnkey, stable, and managed experience with less setup overhead.

How do I contribute a plugin?

Develop your plugin following the Cordis/dsh conventions, publish it to npm or GitHub, and tag it with the dsh-plugin topic on GitHub to make it discoverable by the community.

What does "developer preview" mean?

It means the software is publicly available for development and testing, but its APIs are not yet stable. Breaking changes may occur in future releases. It is not recommended for critical production deployments that cannot tolerate such changes.