DeepSeek Harness Tutorial: How to Install and Use It with the DeepSeek API

DeepSeek Harness is easy to misunderstand at first. It is not a new language model and it is not a local model runner. It is the software around a model: the part that lets an AI inspect files, run terminal commands, call tools, keep a session, and ask for permission before it changes something.

That distinction saves a lot of unnecessary setup. For the simplest installation, you do not need Ollama, LM Studio, downloaded model weights, or a powerful GPU. DeepSeek Harness runs on your computer, while the DeepSeek V4 model runs through DeepSeek's cloud API.

This DeepSeek Harness tutorial walks through the complete beginner setup: installing the Web UI, adding a DeepSeek API key, selecting V4 Flash, choosing sensible permissions, and testing the agent in a disposable Git repository.

Fact-check note (August 16, 2026): DeepSeek Harness is still a developer preview, and its maintainers warn that compatibility-breaking changes are expected. The latest published @deepseek-ai/dsh package checked for this guide is 0.1.0-rc.6. Review the official repository and npm package before recording a tutorial or adopting it for important work.

What is DeepSeek Harness?

A language model can accept text and generate a response. By itself, it cannot open your repository, edit a file, run a test, or show you a permission request.

A harness supplies that missing runtime:

Model + Harness = Agent

The model provides the reasoning. The harness decides which files and tools are available, how commands are executed, what is recorded in the session, and when human approval is required.

In the standard Web UI, a DeepSeek Harness agent can read and edit workspace files, run commands, maintain a plan, and delegate work to subagents. The official Web UI guide also confirms that operations covered by the active approval policy are shown to the user before they run.

This puts Harness in the same broad category as coding agents such as Claude Code and Codex, rather than a normal chat page. The unusual part is how much of the runtime can be replaced.

Why "everything is a plugin" matters

DeepSeek describes the project with one sentence: everything is a plugin.

The model adapter, tool registry, agent loop, session log, sandbox, approval policy, Web UI, and headless runner are assembled as plugins on top of Cordis. A running installation is a composition of those parts, not one fixed application.

For an everyday user, this simply means you can start with the supplied Web UI. For developers, it means you can replace a model provider, add a tool, intercept a tool call, use a different filesystem or sandbox, or build another interface without rewriting the whole agent.

A minimal plugin is just a TypeScript module with an apply function:

import type { Context } from '@deepseek-ai/cordis'

export function apply(ctx: Context) {
  console.log('My plugin is running')
}

You do not need to learn Cordis to follow this tutorial, but the plugin design is the main reason DeepSeek Harness is more than another finished coding assistant. The architecture guide is the best next read if you want to extend it.

Is DeepSeek Harness local?

Partly.

The Harness process, browser interface, project files, Git commands, tests, and file edits run on your computer. In the setup below, model inference runs on DeepSeek's servers.

Your computer                      DeepSeek cloud
-----------------------------      -----------------
DeepSeek Harness Web UI     --->   DeepSeek V4 model
Project files                       Model inference
Terminal and tests          <---   Text and tool calls
Local file edits

When the agent needs the model, Harness can send the system prompt, conversation history, tool definitions, relevant file contents, and tool results to the configured API endpoint. DeepSeek's adapter documentation describes that request in detail.

So the accurate description is: DeepSeek Harness runs locally, while DeepSeek V4 runs through the cloud API. A page served from 127.0.0.1 does not mean your repository content stays offline.

DeepSeek V4 Flash or V4 Pro?

The built-in DeepSeek provider currently advertises these models:

deepseek-v4-flash
deepseek-v4-pro

Both support thinking and non-thinking modes, tool calls, JSON output, and a one-million-token context window. DeepSeek positions Flash as the faster, less expensive option and Pro as the stronger choice for demanding work. You can compare the current details on the official models and pricing page.

Start with DeepSeek V4 Flash when you are learning the interface, fixing a small bug, or checking whether the installation works. Try DeepSeek V4 Pro when a large codebase or difficult investigation needs more reasoning and Flash has not been good enough.

For the first run in this guide, choose Flash.

What you need

Before starting, prepare:

• Node.js 22.19.0 or later in the Node 22 line, or Node.js 24 and above
• npm and npx
• Git
• A DeepSeek Platform account
• A DeepSeek API key with available balance
• A modern browser
• A disposable test project

Node.js 24 is the simplest choice for a new installation. Check your tools:

node --version
npm --version
npx --version
git --version

If you use NVM, install Node.js 24 with:

nvm install 24
nvm use 24
nvm alias default 24

Run the version checks again before continuing.

Step 1: Create a DeepSeek API key

Sign in to the DeepSeek Platform, open the API keys section, and create a key. The API reference confirms that requests use bearer-token authentication.

Treat the key like a password. Do not commit it, paste it into frontend code, include it in screenshots, or show the settings screen during a recording. A separate key used only for testing is easier to rotate if something goes wrong.

Make sure the account has API balance. A valid key can still fail on the first request if the account has no funds.

Step 2: Test the key (optional)

This quick check separates API problems from Harness configuration problems. On Linux or macOS, read the key without printing it:

read -s -p "Enter your DeepSeek API key: " DEEPSEEK_API_KEY
echo
export DEEPSEEK_API_KEY

Then send a small request:

curl https://api.deepseek.com/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $DEEPSEEK_API_KEY" \
  -d '{
    "model": "deepseek-v4-flash",
    "messages": [
      {
        "role": "user",
        "content": "Reply with exactly: API WORKS"
      }
    ],
    "stream": false
  }'

The response should contain API WORKS. The old deepseek-chat and deepseek-reasoner aliases were retired in July 2026, so use the V4 model IDs in new configurations. DeepSeek documents that change in its V4 release notes.

Remove the temporary shell variable when the test is complete:

unset DEEPSEEK_API_KEY

You will save the key through the Harness settings page later.

Step 3: Create a safe test project

Do not make your first agent experiment inside a production repository. Use a small project where the right answer is obvious and every change is easy to review.

mkdir deepseek-harness-demo
cd deepseek-harness-demo
git init

Create calculator.js with an intentional bug:

export function multiply(a, b) {
  return a + b;
}

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);
});

Create package.json:

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

Run the test:

npm test

It should fail because the function returns 7 instead of 12. Save the starting point:

git add .
git commit -m "Add calculator with intentional bug"

If Git asks for your name and email, configure them and repeat the commit.

Step 4: Start the DeepSeek Harness Web UI

Stay inside deepseek-harness-demo and run DeepSeek's official quick-start command:

npx @deepseek-ai/dsh web

The first run may ask whether npx can download the package. Approve it, then wait for the local URL. By default, the Web UI is served at:

http://127.0.0.1:3080

Open that address in your browser and keep the terminal process running.

If port 3080 is already in use, stop Harness with Ctrl+C and choose another port:

npx @deepseek-ai/dsh web --port 3081

A global installation is not required. The trade-off with an unpinned npx command is that a later run may download a newer preview release. For a repeatable test, use the version reviewed for this article:

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

DeepSeek's own CLI reference documents the Web UI alias, headless profile, and supported arguments.

Step 5: Add the DeepSeek provider

In the Web UI:

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

You do not need to create a custom provider for the normal DeepSeek API. Harness includes an official adapter and provider route.

The model configuration guide says the saved key is written to $DSH_HOME/.credentials.yaml, while the settings retain a credential reference. The browser receives a redacted description after saving rather than the literal stored secret. Model changes become available without restarting the server.

That is safer than putting a key in project code, but it does not make the key disposable. Protect the Harness home directory and rotate the key if it is ever exposed.

Step 6: Choose the workspace and model

Return to the main interface and click Choose workspace. Select the deepseek-harness-demo directory. If you need its absolute path, run pwd in the project terminal.

A fresh Web UI has no selected workspace, even though the Harness process uses its starting directory as the default filesystem location. The composer stays disabled until you select one.

Next, open the model picker and choose:

DeepSeek-V4-Flash

The model ID behind that label is deepseek-v4-flash. Start a new session after selecting it. A session that has already sent a request keeps the model recorded in its own log, so use a fresh session when comparing Flash and Pro.

Step 7: Choose permissions carefully

The standard permission selector bundles two different controls:

• Sandbox mode decides which file writes are allowed.
• Approval policy decides when Harness asks before an action.

The default presets are:

• workspace-write: file writes are limited to the workspace and platform temporary area; approval policy is ask.
• danger-full-access: filesystem confinement is bypassed; approval policy is never.

Choose workspace-write for this tutorial. Do not use danger-full-access for a first run.

There is an important limitation here. According to the current sandbox documentation, the sandbox mode governs filesystem effects only. The CLI reference says reads, network access, and process visibility are not confined by the standard workspace-write preset. It should not be treated as a complete security boundary.

Approval and sandboxing are also not interchangeable. An approval dialog asks whether an action may run; a sandbox limits what that action can reach. "Ask" does not guarantee isolation, and "never ask" does not make an action safe.

Use a disposable repository, remove secrets from it, and read every request until you understand how Harness behaves on your operating system.

Step 8: Run your first coding task

Create a new session and send this prompt:

Inspect this repository.

Run the existing tests using:

npm test

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

Requirements:
- Do not install any 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 before finishing.
- Do not claim success unless all tests pass.
- Summarize exactly what you changed.

This is a much better first task than "fix my project." It supplies the test command, the boundaries, and a clear definition of success.

Harness may ask before it runs commands or modifies files. For this demo, actions such as ls, reading the three project files, npm test, and git diff make sense. Stop and inspect the request if it tries to install software, use sudo, read another project, inspect environment variables, delete files, or connect to an unrelated service.

The expected code change is only:

-  return a + b;
+  return a * b;

Step 9: Verify the result yourself

Do not treat the agent's final paragraph as proof. Return to the terminal and run:

npm test
git diff
git status --short

The test should pass, and only calculator.js should be modified.

This habit matters more than the choice between Flash and Pro. Models can misread command output, overlook another failure, or announce success too early. Trust the test result and the diff, not the confidence of the final message.

What happens during a Harness run?

One user prompt can produce several API requests. DeepSeek Harness calls one model request plus its associated tool calls a step. A turn can contain zero or more steps.

Your prompt
    |
Harness assembles instructions, history, and tools
    |
DeepSeek V4 requests a tool or returns text
    |
Harness checks policy and runs the local tool
    |
The result is written to the session log
    |
The next model step receives the updated history

Turn boundaries, user messages, assistant output, tool calls, and tool results are durable session events. That event stream supports resume, replay, forks, transcripts, and debugging. The architecture follows a useful rule: anything shown to the model must be reconstructable from the session log.

For agent evaluation, this trajectory is often more informative than the final code. It reveals which files the model read, which tool it chose, how it handled a failed command, and whether it actually ran the tests.

Privacy and API-key safety

The Web UI is local; the selected cloud model is not. A DeepSeek model request may include:

• Harness instructions and tool schemas
• Conversation history
• Relevant source files
• Terminal output and error logs
• Tool results
• Context added by plugins
• Model and reasoning configuration

Do not connect a confidential repository until you know whether your employer or client allows its contents to be processed by an external model provider. Check for credentials, customer data, private business logic, contractual restrictions, and data-residency requirements first.

For the API key itself:

• Create a separate test key.
• Never paste it into a prompt.
• Do not commit $DSH_HOME or credential files.
• Keep personal and production keys separate.
• Monitor unexpected usage.
• Revoke an exposed key; deleting a screenshot or Git commit is not enough.

Session telemetry is local by default in the current shipped profile. If you explicitly enable full telemetry, DeepSeek warns that exported events can include message text, tool arguments, tool results, and workspace paths. Review that configuration before turning it on.

How much does DeepSeek Harness cost?

The Harness source code uses the MIT license, but DeepSeek API usage is billed separately. Cost depends on the chosen model, input and output tokens, cache hits, number of agent steps, session length, and the amount of source code or tool output added to context.

An agent task that appears to be one prompt can make several requests. Each round may send tool schemas, conversation history, files, test failures, and previous tool results again.

To keep early experiments inexpensive:

• Start with V4 Flash.
• Open the smallest useful workspace.
• Give the task a concrete stopping condition.
• Avoid pasting large logs when a focused excerpt is enough.
• Stop a run that repeats the same failed action.
• Review usage after each experiment.

DeepSeek provides automatic context caching for matching prefixes, which can lower repeated-input cost. Cache reuse is not guaranteed; changes to the model, prompt, tool schemas, or earlier history can break the reusable prefix. Check the live pricing page instead of copying an old price table.

Common DeepSeek Harness problems

Node.js is too old

Run node --version. Install Node.js 24 if your version does not meet the current requirement.

npx is not found

Install Node.js with npm included, open a new terminal, and check npm --version and npx --version again.

The Web UI does not open

Confirm that the terminal process is still running and use the address it printed. If needed, try another port:

npx @deepseek-ai/dsh web --port 3081

The message box is disabled

Choose a workspace. New Web UI sessions do not enable the composer until one is selected.

DeepSeek models do not appear

Open Settings -> Models, confirm that the API key was saved, return to the model picker, and create a new session.

Authentication or balance errors

DeepSeek's error-code guide lists the common cases:

• 401: the API key is missing, wrong, or invalid.
• 402: the account has insufficient balance.
• 429: requests are arriving too quickly or exceed the account limit.
• 500: the provider encountered a server error; wait briefly and retry.
• 503: the service is overloaded; wait and retry.

The agent edited the wrong file

Stop the run and check the selected workspace. For a less obvious task, request investigation before editing:

Investigate the problem and explain your proposed fix.
Do not modify files until I approve the plan.

The agent says it finished, but tests still fail

Run the tests yourself, then paste the actual failure into the same session:

The task is not complete. I ran npm test and it still fails.

Here is the output:

[paste output]

Investigate the remaining failure. Do not make unrelated changes.

Beyond the Web UI

The Web UI is the easiest starting point, but it is not the only interface.

The CLI includes a headless profile that runs one persisted session, prints the final response, and exits:

npx @deepseek-ai/dsh --profile headless "Summarize this workspace"

That is useful for scripts, CI experiments, and benchmarks. DeepSeek also publishes a Python SDK guide. Its example can launch a bundled runtime, reuse sessions, and write JSONL logs containing model requests and tool calls.

Read the security note before copying the SDK example: its documented minimal composition uses danger-full-access, so DeepSeek recommends an isolated workspace or container.

Harness can also use catalog providers such as OpenAI and Anthropic, custom company gateways, and self-hosted OpenAI-compatible endpoints. Authentication varies by provider, and a model that works well in chat may still behave poorly with a particular set of tools. Test tool calling, context handling, and error recovery before relying on a new provider.

Frequently asked questions

Is DeepSeek Harness a model?

No. It is an agent runtime that connects a model to tools, files, commands, permissions, sessions, and interfaces.

Do I need a local DeepSeek model, Ollama, or a GPU?

No, not for this setup. DeepSeek V4 inference runs through the cloud API.

Is DeepSeek Harness free?

The project is available under the MIT license. Cloud API usage is billed separately.

Does my code remain on my computer?

The files remain on your computer, but relevant content can be included in requests to the selected cloud model.

Which permission should I use first?

Use workspace-write with the ask approval policy, in a disposable repository with no secrets. Remember that this preset limits writes; it does not confine reads or network access.

Which model should I choose first?

Start with deepseek-v4-flash. Move to deepseek-v4-pro when the task justifies the extra cost and reasoning.

Can I build a custom plugin?

Yes. Plugins can register services, typed events, tools, UI contributions, and other capabilities through Cordis.

Is it ready for production?

DeepSeek currently labels Harness a developer preview and warns about breaking changes. Test it carefully, pin reviewed versions, and complete your own security review before production use.

Final thoughts

DeepSeek Harness is interesting because it makes the boundary between a model and an agent easy to see. The model reasons; the Harness assembles context, exposes tools, applies permissions, runs commands, and records what happened.

For a first test, keep the setup deliberately boring:

Interface:   DeepSeek Harness Web UI
Command:     npx @deepseek-ai/dsh@0.1.0-rc.6 web
Provider:    Official DeepSeek API
Model:       deepseek-v4-flash
Permissions: workspace-write + ask
Workspace:   Disposable Git repository
Task:        One small failing test

Watch every requested action, inspect the diff, and run the tests yourself. Once that workflow feels predictable, you can explore plugins, headless jobs, provider swaps, session replay, and larger repositories without treating the agent as a black box.