DeepSeek Harness Tutorial: Run Your First Coding Agent Safely

Source-checked and tested: August 17, 2026. This tutorial was checked against DeepSeek Harness 0.1.0-rc.6, the official repository and user guides, and a local Web UI boot that returned HTTP 200. DeepSeek labels the project a developer preview and explicitly warns that breaking changes are expected.

DeepSeek Harness is the layer that turns a language model into an agent that can inspect a repository, edit files, run shell commands, keep a plan, delegate work, and record what happened. The model supplies reasoning and code. The harness supplies the workspace, tools, permissions, session history, and agent loop.

A viral post described the release as killing the coding-agent industry. That is a headline, not a demonstrated result. The important news is more practical: DeepSeek has released a serious, MIT-licensed agent harness whose model adapters, tools, session systems, presets, and even agent loop are composed as plugins.

The code is open source. The work is not automatically free. You still need a compatible model endpoint, and paid APIs can charge for the tokens the agent uses.

By the end of this tutorial, you will have the local Web UI running, a model connected, a disposable Git workspace selected, and one agent-created change that you have independently reviewed and tested.

What you need

• macOS, Linux, or Windows.
• Git.
• Node.js 22.19.0 or newer in the Node 22 line, or Node.js 24 or newer.
• A DeepSeek API key, or credentials for another supported provider.
• A disposable practice directory. Do not make your first agent run inside an important repository.

Check the two local tools first:

node --version
git --version

The commands below use the release candidate tested for this lesson. Pinning the version matters during developer preview because an unversioned npx @deepseek-ai/dsh web run can fetch a newer build with changed behavior.

1. Create a safe practice repository

Make a small repository whose contents you can afford to replace:

mkdir deepseek-harness-practice
cd deepseek-harness-practice
git init
npm init -y
git add package.json
git commit -m "Create practice baseline"

If Git asks for your name or email, configure those before making the baseline commit. The commit gives you a clean comparison point and a simple recovery path.

Confirm the starting state:

git status --short

The command should print nothing. If it lists files you did not expect, understand them before launching an agent.

2. Start the Web UI

Run the harness from the practice repository:

npx @deepseek-ai/dsh@0.1.0-rc.6 web

The first run downloads a large dependency graph and can take several minutes. Let that process finish. Starting a second npx run against the same cache can create a lock conflict.

When startup succeeds, the terminal prints a local address:

dsh web: http://127.0.0.1:3080

Open that URL in your browser. Keep the terminal running; pressing Ctrl-C stops the server.

If port 3080 is already occupied, choose another local port:

npx @deepseek-ai/dsh@0.1.0-rc.6 web --port 3081

The default bind address is 127.0.0.1. Keep it local. A coding agent can expose repository content and execute tools, so this Web UI should not be treated like a public website.

3. Connect a model

In the Web UI, open Settings → Models. Enter your DeepSeek API key in the DeepSeek card and save it.

The key is write-only in the interface. The official guide says the literal secret is stored in $DSH_HOME/.credentials.yaml; the browser receives a redacted descriptor after saving. Model changes apply to the next request without restarting the server.

You can also add catalog providers such as Anthropic or OpenAI, or define a custom OpenAI-compatible endpoint. Start with one provider. A multi-provider setup creates more ways to select the wrong model or credential before you have proved the basic loop.

4. Select the workspace and safest useful preset

Click Choose workspace, add the deepseek-harness-practice directory, and select it. A fresh Web UI will not enable the session composer until a workspace is selected.

Create a new session with these choices:

• Agent preset: Standard.
• Permission preset: workspace-write, which bundles the workspace-write sandbox with an ask-before-escalating approval policy.
• Model: the DeepSeek model you configured.

The permission choice is pinned to the session. Changing the default later affects new sessions, not one that is already open.

Do not choose danger-full-access for this exercise. That preset removes the harness file-write restriction and pairs it with a never-ask approval policy.

5. Begin with a read-only orientation task

Send this first:

Inspect this repository without changing any files.
Explain what is here, list the commands you would use to verify it,
and propose one small coding task suitable for a harness smoke test.

This checks four things without asking for a mutation:

1. the model route works;
2. the agent can see the selected workspace;
3. shell and file-reading tools work;
4. the agent can explain a plan before acting.

The repository contains only package.json, so the answer should be short. If the agent claims to see a larger application, stop and check which workspace you selected.

6. Run one controlled coding task

Now give the agent a narrow job with a testable finish line:

Create src/sum.js exporting a sum(a, b) function.
Add test/sum.test.js using Node's built-in test runner.
Update package.json so npm test runs the test.
Do not install dependencies.
Run the test, then report the changed files and the exact test result.

Approve only operations that match this contract. A request to write outside the practice directory, install a package, read unrelated secrets, or run an unexplained network command is out of scope.

The useful unit here is not the answer in chat. It is the combination of:

• a small diff;
• a passing test;
• no unexpected files;
• and an explanation that matches the actual repository.

7. Verify outside the agent conversation

Return to a separate terminal in the same practice repository and run:

git status --short
git diff --check
git diff
npm test

Inspect the code instead of trusting the agent’s summary. git diff --check catches whitespace errors; npm test proves the test command works from your own shell; git diff shows whether the change stayed within scope.

If everything is correct, create a checkpoint:

git add package.json src/sum.js test/sum.test.js
git commit -m "Verify first DeepSeek Harness task"

If it is wrong, do not ask the agent to hide the evidence. Describe the failed command and expected behavior, let it attempt a focused correction, and rerun the same checks yourself.

8. Give the agent durable project instructions

DeepSeek Harness loads applicable AGENTS.md or CLAUDE.md files for every profile. Add a small AGENTS.md at the repository root when the same rules should apply to later sessions:

# Project instructions

- Do not install dependencies without approval.
- Keep changes inside this repository.
- Run `npm test` before reporting completion.
- Report changed files, test results, and remaining risks.

Commit those instructions so reviewers can see when and why the agent’s operating rules changed. Keep them concrete. A large manifesto consumes context but may still fail to tell the agent what command proves the task is done.

What the four agent presets are for

The Web UI ships four compositions. They share the same host, but expose different model-facing capabilities.

Preset	What it exposes	Use it when
Standard	File editing, shell, file and web search, Skills, plans, goals, subagents, and workflows	You want the normal coding-agent experience
PTC / Code mode	Standard capabilities presented through a Code Mode SDK so the model can compose multi-step operations in TypeScript	Tool-call overhead is becoming the bottleneck and you can inspect the generated program
Minimal	Persistent Bash and str_replace_editor only	You are testing the model with a deliberately small harness or reproducing a benchmark setup
Create / Cordis mode	Standard capabilities plus runtime inspection, plugin experiments, and preset-authoring guidance	You are ready to build or modify harness compositions

Start with Standard. Minimal is useful for controlled comparisons, not because fewer tools automatically make a better everyday agent. Create mode is for harness development; it lets the agent inspect and experiment with the plugin tree, so use it only in a disposable environment.

See the plugin architecture without changing it

The phrase “everything is a plugin” is structural, not just branding. The Web app, model adapters, tools, credentials, session persistence, sandbox policy, approval flow, and presets are assembled through Cordis configuration.

You can inspect the shipped Web profile without booting it:

npx @deepseek-ai/dsh@0.1.0-rc.6 web --dump-default-config

Do this before installing community plugins. A plugin is executable code loaded into the harness process. Review its repository, package ownership, version, install scripts, and contributed configuration before adding it.

The CLI can install plugin bundles into a named profile:

npx @deepseek-ai/dsh@0.1.0-rc.6 \
  plugin --profile <profile-name> add <package-or-git-spec>

That is an extension mechanism, not a beginner setup step. The standard preset already contains enough capability to learn the agent loop safely.

Optional: run one headless task

After the Web setup works, the same package can run a single persisted task without opening a browser:

npx @deepseek-ai/dsh@0.1.0-rc.6 \
  --profile headless \
  "Inspect this repository, run npm test, and report whether it passes. Do not edit files."

The headless profile prints the final answer and exits. A completed turn exits with status 0; other final reasons exit with status 1. It is useful for supervised scripts, but it is not automatically safe CI. The task still has model cost, filesystem access, network visibility, and session output that may contain repository details.

For a programmatic integration, DeepSeek also publishes deepseek-harness-sdk for Python 3.10 or newer. Its official minimal example uses danger-full-access and explicitly recommends a disposable checkout or container, so treat that path as an advanced integration rather than the next click in this tutorial.

Troubleshooting

npx appears to hang on the first run

The initial package installation is large. Leave one process running and wait. Do not launch duplicate npx installs against the same cache. If the process eventually reports a registry or lock error, stop any duplicate installs and retry once from a clean terminal.

Node reports an unsupported engine

The current repository requires Node ^22.19.0 || >=24.0.0. Upgrade Node, open a new terminal, and confirm node --version before retrying.

The browser cannot connect

Read the URL printed by the process instead of assuming port 3080. If needed, rerun with --port 3081. Keep the terminal process alive while using the UI.

The composer is disabled

Select both a model and a workspace. A fresh UI intentionally starts without an active workspace.

MISSING_CREDENTIAL or HTTP 401

Save the provider key again in Settings → Models. For a custom provider, confirm the base URL, protocol, and credential. A custom OpenAI-compatible endpoint may not support model discovery, so enter its model ID manually if GET /models fails.

The agent can read more than expected

workspace-write is a file-mutation boundary, not a complete privacy sandbox. Stop the session and move the task into a container or VM with only the required files and credentials available.

The honest verdict

DeepSeek Harness is more than a thin API wrapper. It already provides a usable local Web UI, multiple agent compositions, model-provider configuration, approvals, workspaces, durable sessions, subagents, workflows, a headless runner, and SDK access. Its Cordis composition also gives developers a credible route to replace or reconfigure major parts of the agent.

It is not yet a drop-in reason to cancel every mature coding-agent product. The release is a developer preview, its interfaces can break, its first install is substantial, and the safety boundary still depends on the selected workspace, permission preset, local machine, installed plugins, and model behavior. The right first test is therefore small and boring: one disposable repository, one bounded change, one independent verification pass.

Sources

• DeepSeek Harness official repository
• Official Web UI guide
• Official model-provider guide
• Official CLI behavior reference
• Official Python SDK guide
• Archive’s original DeepSeek Harness post