DEV Community

Cover image for DeepSeek Harness Tutorial: Run Your First Coding Agent with DeepSeek V4
Vladislav Guzey
Vladislav Guzey

Posted on

DeepSeek Harness Tutorial: Run Your First Coding Agent with DeepSeek V4

#deepseek #ai #tutorial #agents

DeepSeek Harness is an open-source agent runtime from DeepSeek.

It is not a model. It is the application that connects a model to your project files, terminal, tools, permissions, and session history.

We will use the DeepSeek cloud API. You do not need Ollama, a local model, or a powerful GPU.

DeepSeek Harness is currently a developer preview. Commands and settings may change between versions.

What Runs Locally?

This tutorial uses the following setup:

Your computer:

  • DeepSeek Harness

  • Browser interface

  • Source code

  • Terminal commands

  • File changes

DeepSeek cloud:

  • DeepSeek V4 model

The Web UI is local, but repository context may be sent to the DeepSeek API when the model needs it.

Do not use a confidential repository for your first test.

Requirements

You need:

  • Git
  • Node.js 22.19 or later
  • npm and npx
  • A DeepSeek API key
  • API balance
  • A browser

The current repository supports Node.js ^22.19.0 or Node.js 24+.

Check your versions:

node --version
npm --version
npx --version
git --version
Enter fullscreen mode Exit fullscreen mode

For a new installation, Node.js 24 is a good choice.

With NVM:

nvm install 24
nvm use 24
nvm alias default 24
Enter fullscreen mode Exit fullscreen mode

Create a Demo Project

Create a disposable project:

mkdir deepseek-harness-demo
cd deepseek-harness-demo
git init
Enter fullscreen mode Exit fullscreen mode

Create calculator.js:

export function multiply(a, b) {
  return a + b;
}
Enter fullscreen mode Exit fullscreen mode

The function contains a bug. It adds the numbers instead of multiplying them.

Create calculator.test.js:

import test from "node:test";
import assert from "node:assert/strict";
import { multiply } from "./calculator.js";

test("multiply returns the product of two numbers", () => {
  assert.equal(multiply(3, 4), 12);
});
Enter fullscreen mode Exit fullscreen mode

Create package.json:

{
  "name": "deepseek-harness-demo",
  "private": true,
  "type": "module",
  "scripts": {
    "test": "node --test"
  }
}
Enter fullscreen mode Exit fullscreen mode

Run the test:

npm test
Enter fullscreen mode Exit fullscreen mode

It should fail.

Commit the initial state:

git add .
git commit -m "Add calculator with intentional bug"
Enter fullscreen mode Exit fullscreen mode

A Git commit makes it easy to inspect and undo the agent's changes.

Start DeepSeek Harness

Remain inside the project folder and run:

npx @deepseek-ai/dsh web
Enter fullscreen mode Exit fullscreen mode

The current official README uses this as the main Web UI command. The server normally starts on port 3080.

Open:

http://127.0.0.1:3080
Enter fullscreen mode Exit fullscreen mode

Keep the terminal process running.

When port 3080 is unavailable, choose another port:

npx @deepseek-ai/dsh web --port 3081
Enter fullscreen mode Exit fullscreen mode

Then open:

http://127.0.0.1:3081
Enter fullscreen mode Exit fullscreen mode

Add Your DeepSeek API Key

Inside the Web UI:

  1. Open Settings
  2. Open Models
  3. Find the DeepSeek provider
  4. Paste your API key
  5. Save

The built-in DeepSeek configuration does not require you to manually add a custom base URL.

Harness stores the key through its local credential system. The settings keep a credential reference, while the browser receives a redacted description instead of the saved secret.

Do not show this screen while recording a video.

Select a Model

Return to the main interface and choose:

DeepSeek-V4-Flash
Enter fullscreen mode Exit fullscreen mode

DeepSeek-V4-Flash

deepseek-v4-flash
Enter fullscreen mode Exit fullscreen mode

The official DeepSeek adapter currently advertises V4 Flash and V4 Pro by default.

Start with Flash. Use Pro later for more difficult tasks.

Create a new session after changing models. Existing sessions keep the model recorded in their own history.

Choose the Workspace

Click Choose workspace and select the demo project.

Run this command when you need the full path:

pwd
Enter fullscreen mode Exit fullscreen mode

A new Harness Web UI does not enable the message composer until you select a workspace.

Select Safe Permissions

Choose the permission preset that uses:

workspace-write
Enter fullscreen mode Exit fullscreen mode

and asks before sensitive operations.

Avoid this preset during your first run:

danger-full-access
Enter fullscreen mode Exit fullscreen mode

The default workspace-write preset combines workspace confinement with an approval policy of ask. The default danger-full-access preset combines broad access with never.

Use a disposable project even with the safer option.

Give the Agent a Clear Task

Paste this prompt:

Inspect this repository.

Run the tests using:

npm test

Find the root cause of the failing test and fix it.

Requirements:
- Do not install packages.
- Do not access files outside this workspace.
- Make only the smallest necessary change.
- Run the tests again after changing the code.
- Inspect the final Git diff.
- Do not claim success unless all tests pass.
- Summarize exactly what you changed.
Enter fullscreen mode Exit fullscreen mode

The expected workflow is:

Read the source file
Read the test
Run npm test
Find the incorrect + operator
Replace it with *
Run the test again
Inspect the Git diff
Return a summary

Approve only actions that you understand.

Verify the Result

Do not trust the agent's final message without checking it.

Run:

npm test
Enter fullscreen mode Exit fullscreen mode

Then inspect the code change:

git diff
Enter fullscreen mode Exit fullscreen mode

The expected diff is:

 export function multiply(a, b) {
-  return a + b;
+  return a * b;
 }
Enter fullscreen mode Exit fullscreen mode

Check the repository status:

git status
Enter fullscreen mode Exit fullscreen mode

Only the intended file should be changed.

How the Agent Loop Works

One model response is usually not enough for a coding task.

Harness may run several steps:

User prompt
    ↓
Model request
    ↓
Tool call
    ↓
Permission check
    ↓
Local tool execution
    ↓
Tool result
    ↓
Another model request
    ↓
Final response
Enter fullscreen mode Exit fullscreen mode

A step includes one model request and the tools called from that request. A turn can contain several steps.

The durable session log can store user messages, assistant output, tool calls, tool results, and execution boundaries. Harness reconstructs model history from this event stream.

This supports:

  • Session resume
  • Replay
  • Forking
  • Transcripts
  • Debugging
  • Persistence

It also helps you understand why the agent made a particular decision.

What to Try Next

After the small demo works, test a real but non-sensitive repository.

A useful prompt is:

Before changing files:
1. Read the relevant documentation.
2. Run the existing tests.
3. Explain the root cause.
4. Propose the smallest fix.

After I approve:
1. Apply the change.
2. Run the relevant tests.
3. Inspect the final diff.
4. Report remaining risks.
Enter fullscreen mode Exit fullscreen mode

Learn more about DeepSeek Harness on my website: https://proflead.dev/

Top comments (0)