DeepSeek Harness Tutorial: Build Your First Agent, End to End

By the end of this tutorial you will have a working DeepSeek Harness agent that edits code, runs shell commands, calls tools, and keeps a full audit log — all on your local machine^[1].

• Install the harness (one npm command)
• Connect a model provider (DeepSeek first)
• Run an agent task in the Web UI
• Add a community plugin and an MCP server
• Debug a run using the Trajectory view

The fastest path needs only Node.js^[1][2].

# One-line install + launch
npx @deepseek-ai/dsh web

# If you prefer building from source
git clone https://github.com/deepseek-ai/deepseek-harness.git
cd deepseek-harness
pnpm install
pnpm run build
pnpm dsh web

# The UI opens at http://127.0.0.1:3080

In the Web UI, go to Settings → Models. Add your DeepSeek API key — it is stored in $DSH_HOME/.credentials.yaml and becomes write-only after saving^[3].

dsh ships model-neutral: the default bundle points at DeepSeek, but you can add Anthropic, OpenAI, or any custom OpenAI-compatible endpoint. Custom providers need a Provider ID, baseURL, API protocol, credential, and model list; the UI can fetch available models from endpoints that support GET /models^[3].

Model changes apply on the next request — no restart needed.

• DeepSeek native: Settings → Models → paste API key
• Catalog providers (Anthropic/OpenAI): pick provider, enter key
• Custom endpoint: Provider ID + baseURL + protocol + models

Back in the UI, choose a workspace (your project folder), open a new session, and give the agent a real task^[4].

The agent will edit files, run shell commands, and report back. Everything it sees and does is recorded, so you can review the run in the Trajectory view afterwards^[5].

# In the Web UI session box, try:
"Read src/main.ts, explain what it does, and fix the two obvious bugs"

# Or from the terminal (one-shot):
dsh --profile headless "Read src/main.ts and list the bugs"

The default bundle ships four runtime presets, each a different plugin composition^[1][5].

Everything is a plugin, so extending the agent is a package install^[2][6].

Security first: installing a plugin runs third-party code with access to your files and keys. Test unknown plugins in a credential-free profile before promoting them^[6].

# Add a community plugin
dsh plugin --profile web add <package-name>

# Add the plugin market to browse
dsh plugin --profile web add dshmarket

# MCP arrives via plugins too — see the MCP guide
dsh plugin --profile web add dsh-plugin-setting-mcp

When a run misbehaves, open the Trajectory view for that session. It shows the append-only event log by source: system prompts, reasoning, tool calls and results, subagent scheduling, context injections^[5].

This turns 'the agent did something weird' into a reviewable transcript — the debugging story that closed-source agents cannot offer.

If the error is credential or model related, the troubleshooting guide covers the official error table (MISSING_CREDENTIAL, UNKNOWN_MODEL, image refusals).

• Find the exact prompt the model received
• Inspect each tool call and its result
• Check where context was injected or truncated
• Resume, fork, search, or replay from any event