AI models can generate code, explain repositories, and suggest fixes. But a model alone cannot safely inspect your project, execute commands, remember a long-running task, or coordinate multiple tools.
That surrounding infrastructure is called an agent harness.
DeepSeek Harness also called dsh is DeepSeek’s open-source implementation of that infrastructure. It provides the runtime that connects a model to files, tools, sessions, sandboxes, approval policies, workflows, and a user interface.
Here is the breakdown:
This article explains what DeepSeek Harness is, what makes it interesting, how to try it, and—just as importantly—when it may be the wrong tool.
DeepSeek Harness is currently a developer preview. Expect breaking changes, unfinished edges, and rapidly evolving APIs.
The short version
DeepSeek Harness is not:
- A new DeepSeek model
- A model-training framework
- A replacement for Node.js, Python, or your IDE
- A guarantee that an AI-generated change is correct or safe
It is an agent runtime.
A useful mental model is:
AI agent = model + harness
The model provides reasoning and language capabilities. The harness gives that model a controlled way to interact with the outside world.
Your request
↓
DeepSeek Harness
├── builds the model context
├── exposes approved tools
├── manages the workspace
├── executes tool calls
├── records the session
├── applies approval and sandbox policies
└── returns results through the UI
↓
Configured AI model
The model decides what it wants to do. The harness decides how that action is represented, executed, recorded, and controlled.
Why do agents need a harness?
Suppose you ask a regular chat model:
Find the authentication bug in this repository, fix it, and run the tests.
The model needs more than intelligence to complete that request. It needs a way to:
- Discover the repository structure
- Read the relevant files
- Search for related code
- Edit the implementation
- Execute the test suite
- Inspect failures
- Make another change
- Preserve a record of what happened
A harness supplies these capabilities.
Without one, you have a model that can tell you what code might work. With one, you have an agent that can potentially inspect and modify a real environment subject to the permissions you give it.
That last part matters. A harness makes a model more useful, but it also makes the model more capable of causing damage. Workspace boundaries, approvals, sandboxes, and human review remain essential.
What makes DeepSeek Harness different?
The main design principle is:
Everything is a plugin.
Models, tools, skills, sessions, storage, sandboxes, agent loops, scheduling, and even the UI are provided through plugins.
At the center is Cordis, a plugin kernel responsible for mounting plugins, resolving their dependencies, and letting them communicate through services and events.
This has an important practical consequence: capabilities can be replaced or recomposed without maintaining a permanent fork of the harness.
For example, a developer could theoretically swap:
- One model provider for another
- A local shell backend for a remote sandbox
- The default storage implementation for a custom store
- One approval policy for a stricter policy
- The standard agent loop for a specialized workflow
- The browser UI for another client
This architecture is most valuable when you want to build or study agent infrastructure, not merely chat with an AI model.
DeepSeek Harness does not require a DeepSeek model
The name can be misleading.
DeepSeek Harness includes direct support for configuring DeepSeek, but it can also work with other catalog providers and custom OpenAI-compatible endpoints. The model and the harness are separate layers.
That means you can evaluate questions such as:
- How does the same model behave with different tools?
- How do two models perform inside the same agent environment?
- What happens when the sandbox or approval policy changes?
- Can an internal model endpoint be connected to a reusable agent runtime?
For custom providers, you supply details such as the provider ID, base URL, API protocol, credentials, and model list.
Be aware that “OpenAI-compatible” does not always mean perfectly compatible. Different gateways may use different roles, token-limit fields, reasoning formats, or image capabilities. DeepSeek Harness exposes compatibility settings for these cases, but connecting an unusual endpoint may require experimentation.
Every run is traceable
DeepSeek Harness uses an append-only session log.
The log records the model-visible history of a run, including prompts, messages, tool calls, tool results, context injections, and agent activity. Features such as resuming, forking, searching, replaying, and inspecting a trajectory are built from this event stream.
This is useful for debugging questions like:
- Why did the agent edit this file?
- Which tool result changed its direction?
- What context did the model receive?
- Where did a multi-step task begin to fail?
- Did the problem come from the model, a tool, or the harness configuration?
Traceability is especially helpful when developing an agent system. Looking only at the final answer often hides the real failure.
It also has a privacy implication: session logs may contain code, prompts, tool output, file contents, or other sensitive context. Treat stored trajectories as potentially sensitive data.
The four runtime modes
DeepSeek Harness provides several modes for different kinds of work.
| Mode | What it provides | Best suited for |
|---|---|---|
| Standard | File editing, shell access, search, skills, planning, goals, subagents, and workflows | General agent-assisted development |
| Code | Standard capabilities exposed through a code-based orchestration SDK | Multi-step tool orchestration |
| Minimal | A persistent shell and file editor | Benchmarking models with minimal harness influence |
| Creator | Runtime inspection and plugin experimentation in addition to standard capabilities | Building presets and extending the harness |
Standard mode
Start here if you want to understand the normal user experience.
It provides the familiar capabilities expected from a coding agent: reading files, editing code, searching, running commands, planning work, and delegating subtasks.
Code mode
Code mode lets the model combine several tool operations in a generated TypeScript program.
This can reduce the overhead of repeatedly moving between the model and individual tools. It is useful for complex orchestration, but it also increases the importance of execution controls and careful review.
Minimal mode
Minimal mode intentionally removes most of the surrounding machinery.
It is useful when comparing models or studying how much the harness itself influences performance. It is less convenient for everyday development because many higher-level capabilities are absent by design.
Creator mode
Creator mode is for developers experimenting with the harness itself.
Use it to inspect the runtime, test plugins, and compose custom presets. If your goal is simply to fix an application bug, Creator mode is probably unnecessary.
When should you use DeepSeek Harness?
DeepSeek Harness is a strong candidate in the following situations.
1. You are building an agent platform
If your product needs interchangeable tools, model providers, storage systems, sandboxes, or agent loops, the plugin architecture gives you an existing composition model to study or extend.
2. You need inspectable agent runs
The session event stream and trajectory view make it easier to reconstruct what an agent saw and did. This is valuable for debugging, evaluations, and failure analysis.
3. You want to compare models inside the same environment
Model comparisons are difficult when each model uses a different set of prompts, tools, and execution rules. A configurable harness helps keep more of the environment consistent.
4. You are experimenting with custom tools or policies
Because tools and execution policies are extension points, the project is relevant when testing a custom capability, approval flow, sandbox backend, or internal integration.
5. You want an open-source base you can inspect
DeepSeek Harness is released under the MIT license. You can examine the implementation, modify it, and build on it within the terms of that license.
Remember that MIT-licensed does not mean zero operating cost. A configured model provider may charge for API usage, and remote infrastructure can introduce additional costs.
When should you not use it?
A new open-source agent system can be exciting, but it is not automatically the right choice.
1. You only need a simple model call
If your application sends a prompt and receives an answer, a model SDK may be enough. Adding a full harness introduces plugins, sessions, configuration, storage, and operational complexity you may not need.
2. You need a stable production API today
The project is explicitly marked as a developer preview and warns that compatibility-breaking changes will occur.
That makes it suitable for learning, prototyping, and experimentation. Production adoption requires version pinning, migration planning, testing, and a willingness to follow upstream changes.
3. You cannot isolate the working environment
An agent that can edit files and execute commands should not receive unrestricted access to a sensitive machine.
If you cannot provide a narrow workspace, suitable approval policies, secret isolation, and preferably a disposable environment, do not use it for autonomous changes.
4. Your workflow requires deterministic results
An agent loop combines model decisions with changing context and tool output. Even with the same request, the exact path may vary.
Use conventional scripts, tests, and workflow engines when deterministic execution is the primary requirement.
5. Your team does not need harness customization
If a mature coding assistant already meets your needs, adopting an extensible agent runtime may create maintenance work without delivering meaningful value.
6. You plan to trust the output without review
A traceable agent can still make incorrect changes. Logs help explain a decision; they do not make that decision correct.
Treat generated code like a contribution from an unfamiliar developer: review the diff, run tests, inspect security-sensitive changes, and verify the behavior.
How to try DeepSeek Harness
The fastest path is through its local Web UI.
Step 1: Check Node.js
The repository currently declares support for Node.js ^22.19.0 or >=24.0.0.
node --version
Because the project is changing quickly, verify the current requirement in the repository before installing.
Step 2: Start the Web UI
npx @deepseek-ai/dsh web
By default, this starts a local server at:
http://127.0.0.1:3080
Run the command from the project directory you want to work with. The process uses its starting directory as the default filesystem location, although you still need to select a workspace in the UI.
Step 3: Configure a model
Open:
Settings → Models
You can enter a DeepSeek API key, add another supported provider, or configure a custom provider.
Credentials are stored separately from normal settings, and the UI receives a redacted credential descriptor after saving rather than the literal key.
You still need to protect the machine and the harness home directory. Never commit credential files to a repository.
Step 4: Choose a workspace
Select Choose workspace, add the relevant project directory, and select it.
Use the smallest practical directory. Do not select an entire home folder or a directory containing unrelated secrets and projects.
Step 5: Begin with a read-only task
A good first request is:
Summarize this repository. Identify its main packages, test commands,
and likely entry points. Do not modify any files.
This lets you evaluate how the agent explores the project before allowing it to make changes.
A reasonable next task is:
Find one small, well-contained issue in this repository.
Explain the proposed fix and wait for approval before editing files.
Only after you understand the permission flow should you try a full implementation task.
Step 6: Inspect the trajectory
Do not judge the harness only by the final response.
Inspect:
- What context was sent to the model
- Which tools were called
- Which files were accessed
- Whether commands required approval
- How tool output affected later decisions
- Whether the agent repeated unnecessary work
This is where a traceable harness becomes more useful than a simple chat interface.
A safer evaluation workflow
For early experiments, use a disposable branch, worktree, container, or test repository.
A practical workflow looks like this:
- Create an isolated copy of a small project.
- Remove production credentials and customer data.
- Start DeepSeek Harness from that directory.
- Select only that directory as the workspace.
- Use a read-only repository-summary task first.
- Ask for a plan before permitting edits.
- Review every requested command.
- Inspect the resulting diff manually.
- Run the project’s tests yourself.
- Review the trajectory for surprising behavior.
Do not let a successful demo convince you to skip these controls on the next run.
Building from source
If your goal is to inspect or modify the harness itself, clone the repository and build it with its configured package manager:
git clone https://github.com/deepseek-ai/deepseek-harness.git
cd deepseek-harness
pnpm install
pnpm run build
pnpm dsh web
Use this route when you want to:
- Read the architecture alongside the implementation
- Develop or modify plugins
- Test changes to the runtime
- Contribute upstream
- Pin your work to a specific commit
For a first evaluation, the npx command is simpler.
What to evaluate before adopting it
A successful installation only proves that the harness starts. Before using it for real work, evaluate the following.
Model quality
Does your chosen model use tools reliably? Can it recover from failed commands? Does it stop when it lacks information?
Permission behavior
Which actions require approval? Are writes and command execution constrained appropriately?
Workspace isolation
Can the agent access files outside the intended project? Are secrets, SSH keys, cloud credentials, and production configuration isolated?
Trace quality
Can you reconstruct why a change happened? Does the log contain enough information to debug failures without exposing more sensitive data than necessary?
Plugin trust
A plugin can add substantial capabilities. Review its source, dependencies, permissions, maintenance status, and network behavior before installing it.
Upgrade cost
Since the project is in preview, test upgrades against pinned configurations and plugins. Do not assume a newer release will preserve every API or behavior.
Cost
The harness is open source, but model requests, hosted sandboxes, storage, and other providers may not be free. Measure token usage and infrastructure costs with realistic tasks.
Final perspective
DeepSeek Harness is best understood as infrastructure for constructing and studying agents.
Its value does not come from making a model magically correct. It comes from giving developers a composable way to connect models with tools, sessions, workspaces, policies, storage, orchestration, and observability.
Use it when you need that control or want to experiment with agent architecture.
Avoid it when a simple API call is enough, when stability is more important than extensibility, or when you cannot safely isolate what the agent can access.
Most importantly, keep the model and the harness conceptually separate:
The model decides.
The harness enables, constrains, executes, and records.
The developer remains responsible for the system.
Top comments (0)