DeepSeek Harness (dsh) is an open-source AI agent harness from DeepSeek AI built around one idea: everything is a plugin.
The model, tools, skills, sessions, storage, sandbox, agent loop, scheduling, and even the interface are assembled through the Cordis plugin system. A basic setup starts in the browser, where the agent can work with a selected project, run commands, edit files, maintain a plan, and request approval for protected operations.
The plugin model shapes the whole product. A DeepSeek Harness profile defines the pieces that make up an agent environment. Change the model provider, add a tool, install a skill, replace part of the runtime, or load another application layer, and the profile changes with it.
DeepSeek Harness supports several ways to use that runtime. The Web UI provides an interactive workspace, the CLI runs named profiles and headless jobs, and the Python SDK embeds the agent runtime inside Python applications. These entry points share the same underlying composition model.
Everything Is a Plugin
Most of the behavior inside DeepSeek Harness comes from plugins. Cordis loads those plugins, resolves their dependencies, and composes them into the active profile. The result is an agent environment whose major parts share one extension model.
| Plugin | What It Adds to the Agent |
|---|---|
| Models | DeepSeek, catalog providers, and custom model routes. |
| Tools | File editing, shell access, search, and other callable actions. |
| Skills | Reusable instructions and task-specific behavior. |
| Sessions | Conversation state, persistence, replay, and session history. |
| Sandbox & storage | Execution boundaries and persistent runtime data. |
| Agent loops & scheduling | How work runs, delegates, and returns to scheduled tasks. |
| UI | The application layer used to operate the configured agent. |
What You Can Do with DeepSeek Harness
- Work with a local project: Select a workspace and give the agent access to configured file, shell, search, planning, and workflow tools.
- Build reusable agent profiles: Combine plugin bundles and configuration into named runtime setups.
- Add community extensions: Install compatible packages discovered through the
dsh-pluginecosystem. - Choose the model route: Configure DeepSeek, supported catalog providers, or a custom compatible endpoint.
- Run interactive or headless sessions: Use the browser for hands-on work or execute a job from the CLI.
- Inspect session history: Resume, fork, search, replay, and review the recorded event stream through Trajectory.
- Embed the runtime in Python: Start tasks and preserve sessions through the
DeepSeekHarnessSDK class.
Start with the Web UI
This command starts the Web UI and prints its address. The default URL is http://127.0.0.1:3080.
npx @deepseek-ai/dsh webConnect a Model
Open Settings → Models and configure the model route. The built-in DeepSeek card accepts a DeepSeek API key. The same page also supports AI providers such as Anthropic and OpenAI, plus custom providers with a base URL, protocol, credential, and model list.
Choose the Workspace
Click Choose workspace, add the project directory, and select it. DeepSeek Harness uses the directory that launched dsh as the default filesystem location, and the composer becomes available after a workspace is selected.
Run the First Task
Summarize this repository and identify its main packages.Profiles Turn Plugins into Agent Setups
A profile is the practical container for a DeepSeek Harness configuration. It defines an ordered stack of plugin bundles and applies profile-specific configuration on top. This is how the plugin architecture becomes a reusable working environment.
The built-in web and headless profiles initialize from supplied templates on first use. Other profiles can be created and extended through the plugin command. A team can keep one profile focused on repository work, another on evaluation, and another on a custom tool stack.
| Command | What It Does |
|---|---|
dsh web | Starts the Web UI profile. |
dsh --profile <name> | Starts a named profile. |
dsh --profile headless "job" | Runs one persisted job, prints the final response, and exits. |
dsh plugin --profile <name> <pnpm args> | Manages out-of-tree plugin dependencies for a profile. |
Runtime Modes
DeepSeek includes several compositions for common types of agent work. Each mode changes the tools and orchestration available to the model.
| Mode | Best Fit |
|---|---|
| Standard | Repository work with file tools, shell access, planning, subagents, and workflows. |
| Code | Multi-step tool orchestration through generated TypeScript and the Code Mode SDK. |
| Minimal | Controlled model evaluation with persistent Bash and str_replace_editor. |
| Creator | Plugin experiments, runtime inspection, and custom agent compositions. |
Python SDK
The Python SDK exposes DeepSeek Harness as an application runtime. Python code can start an agent against a workspace, send tasks, choose session IDs, and preserve the session-owned shell state across related calls.
The current SDK requires Python 3.10 or newer, Git, a compatible model endpoint and credential, and an isolated workspace.
python -m pip install deepseek-harness-sdkPros
- One plugin model across the agent stack
- Community plugin discovery through
dsh-plugin - Reusable profiles for custom agent setups
- Web UI, headless CLI, and Python SDK
Cons
- Developer-preview stage
- More configuration than turnkey coding agents
- Model-provider inference costs apply
Alternatives & Related Resources
- 10 Best CLI AI Coding Agents: Open-Source & Commercial
- Reasonix: Free DeepSeek Coding Agent with Cache-First Cost Control
- CodeWhale (DeepSeek TUI): Free, Open-source Claude Code Alternative
- DeepSeek Timeline: Model Release Dates and Key Milestones
- Automate Anything: 10 Best & Open-source AI Agents
- How to use DeepSeek V4 Pro or Flash in Codex and cut API costs
FAQs
Can DeepSeek Harness use image-capable models?
Yes, when the configured model route declares image input support. A manually added custom model is treated as text-only until its configuration includes input: [text, image]. DeepSeek’s own chat-completions route is text-only.
Can I switch models inside an existing session?
Model selection becomes the default for new sessions. A session that has already sent a request keeps the model recorded in its session log, so changing the picker does not rewrite that session’s existing model history.
Can a custom provider ID be renamed later?
No. The Provider ID is permanent because saved sessions, model defaults, requests, and credential references use it. Renaming requires creating a new provider entry and removing the old one.
