DeepSeek Harness for Beginners — What It Is, How to Run It

On August 13, 2026, a new GitHub repository appeared and collected 22,000 stars in 90 minutes — the fastest-growing open-source project ever recorded. Two days later it sits at roughly 97,000 stars.

The project: DeepSeek Harness, an open-source framework for running AI agents, released as a developer preview by DeepSeek (the company behind the popular open-source AI models). MIT licensed, free to use, and it runs on your own computer.

But what does an "agent harness" actually do? Why do people care? And can you — a beginner — use it today?

By the end of this guide you'll know what Harness is, why it's getting this much attention, and how to run it on your machine.

The Missing Piece Between Models and Agents

You've probably seen AI agents in action: coding assistants that edit files, researchers that browse the web, bots that book tickets. They feel autonomous. But here's the open secret — an AI model is not an agent by itself.

A model (like DeepSeek, Claude, or GPT) is a brilliant engine: you send it text, it sends text back. It cannot click anything. It cannot remember what it did five steps ago. It cannot decide "this tool failed, try another one."

Something has to sit around the model and handle all of that. That something is the harness:

• Call the model with the right context
• Give it tools (search the web, run commands, edit files)
• Execute the tool calls the model requests
• Feed the results back
• Loop until the task is done
• Keep a record of everything that happened

If the model is the engine, the harness is the rest of the car. And until now, the rest of the car was mostly built privately — locked inside products like Claude Code, Cursor, or OpenAI Codex.

DeepSeek's move is to make the car open source. Their one-line framing:

Model + Harness = Agent

What Makes DeepSeek Harness Different

Plenty of agent frameworks exist. Harness has one idea that stands out: everything is a plugin.

In Harness, the tools, the skills, the model connection, the session system, the scheduling — even the web UI itself — are plugins. Built on a tiny core called Cordis, which does almost nothing except load and unload plugins and manage their dependencies.

The closest comparison is VS Code: the editor itself is a shell, and nearly everything you see — syntax highlighting, Git integration, themes — is an extension. Harness applies that philosophy to AI agents.

What this means in practice:

• You can swap the brain. Plug in a DeepSeek model, a Claude model, or a local model — the harness doesn't care.
• You can add tools without touching the source code. Write a plugin, drop it in, done.
• You can see everything. Every system prompt, every chain-of-thought, every tool call and its result is written to an append-only log you can inspect, replay, or fork.

For beginners, the last point matters most: nothing is hidden inside a black box. You can open the hood of an agent and read exactly what it did and why.

Install It in Under 5 Minutes

Step 1 — Install Node.js. Harness runs on JavaScript, so you need Node.js first (we tested with v22). Pick your system:

• Windows: download the installer from nodejs.org, double-click, accept the defaults. After it finishes, open PowerShell and check: powershell node --version
• macOS: if you have Homebrew, run brew install node. Otherwise use the installer from nodejs.org. Check with node --version in Terminal.
• Linux (Ubuntu/Debian): bash sudo apt update && sudo apt install -y nodejs npm Then check with node --version.

Step 2 — Run Harness. One command, identical on all three systems:

npx @deepseek-ai/dsh web

npx downloads the package and starts the web interface. Point your browser at http://127.0.0.1:3080 and you're in. (On Windows, run this in PowerShell, not the old Command Prompt.)

If you prefer installing it permanently:

npm install -g @deepseek-ai/dsh
dsh web

The Other Mode: Plain CLI

Harness also runs without a browser. The headless mode takes a task, prints the answer, and exits — perfect for quick jobs and shell scripts:

# From the folder you want the agent to work in:
cd ~/dsh-playground
dsh --profile headless "Create a file named test.txt containing 'hello'"

Output:

Done. `test.txt` was created with exactly the text `hello`.

The agent's filesystem access is scoped to the folder you launched it from — that's the sandbox at work. This is the mode to use on a server without a browser.

(You may see a tui example in the dsh --help text — as of version 0.1 there is no TUI mode shipped yet, only web and headless. The example assumes a TUI plugin profile is installed.)

Running From Source (Optional)

git clone https://github.com/deepseek-ai/deepseek-harness.git
cd deepseek-harness
pnpm install
pnpm run build
pnpm dsh web

Step 3 — Configure your API key (next section), then start the web UI again.

Everyday Start (After Setup)

Once installed and configured, starting Harness every day is just:

dsh web          # browser UI at http://127.0.0.1:3080

Or, for one-shot tasks from a terminal:

dsh --profile headless "your task"

If you skipped the permanent install, replace dsh with npx @deepseek-ai/dsh in both commands.

Get an API Key (The Part Everyone Forgets)

The harness is the car, but it needs fuel. To do anything useful, it has to call an AI model — and that means an API key.

DeepSeek's platform is the natural choice:

1. Go to platform.deepseek.com and sign up (email or Google account)
2. Top up a small amount — DeepSeek's API is pay-as-you-go and famously cheap; a few dollars lasts a long time for experiments
3. Open API Keys in the sidebar and click Create new API key
4. Copy the key — like all API keys, it is shown only once

Feed the Key to Harness

Two ways, pick whichever fits your style:

Option 1 — In the web UI (easiest). Open Settings → Models in the web interface. It lists the supported providers — click Edit next to DeepSeek, paste your key, and save. The model works immediately, no restart needed.

Option 2 — Environment variable. Harness also reads a variable called DEEPSEEK_API_KEY. This is the way for CLI mode, and the web UI picks it up too. Set it in the same terminal where you'll run dsh:

• Linux / macOS (Terminal): bash export DEEPSEEK_API_KEY="sk-your-key-here"
• Windows (PowerShell): powershell $env:DEEPSEEK_API_KEY = "sk-your-key-here"

Now start the web UI again (npx @deepseek-ai/dsh web) — the key is picked up automatically when the agent calls the model.

Why an environment variable? It keeps the key out of your code and config files. If you later want the key to survive reboots, add the export line to your shell profile (.bashrc on Linux/macOS) or use setx on Windows — but for a first test, setting it in the terminal is enough.

Treat the key like a password:

• Never paste it into code you might share or commit to GitHub
• If it ever leaks, revoke it from the platform and create a new one (30 seconds)

Because of the plugin architecture, Harness isn't locked to DeepSeek models. If you already have an API key from another provider that speaks the OpenAI-compatible format, you can point Harness at that endpoint instead — a good option if you want to compare how different models drive the same harness.

The Full Checklist to Your First Agent

Putting this whole section together, the complete path is:

1. ✅ Node.js installed (node --version prints a version)
2. ✅ npx @deepseek-ai/dsh web starts without errors
3. ✅ Browser opens http://127.0.0.1:3080
4. ✅ API key created at platform.deepseek.com
5. ✅ Key configured — via Settings → Models in the web UI, or the DEEPSEEK_API_KEY variable
6. ✅ A workspace selected — click Choose workspace and pick (or add) the folder you want the agent to work in. The send box stays locked until one is selected
7. ✅ Send your first task — it should answer within seconds

The Four Built-In Modes

Harness ships with four preset configurations, from fully loaded to bare-bones:

Start with Standard. Explore the others once you know what you need.

Honest Limitations (Read Before You Get Excited)

Harness broke star records, but stars measure excitement, not maturity:

• It's days old. Version 0.1, developer preview, breaking changes guaranteed. Code you write against it today may need fixes next month.
• It's not a consumer product. No polished onboarding wizard. You configure, you read docs, you debug. That's the point of "developer preview."
• The model does the thinking. Harness doesn't make a weaker model smart — it gives a model hands. Results depend heavily on the model you plug in.
• Competition is strong. Claude Code, Cursor, and OpenAI Codex are mature products with years of polish. Harness is betting on openness and customization instead.

If you want a stable, guided experience today, our guide to writing code with AI covers the established tools. Harness is for the curious — people who want to look inside the engine room.

How It Compares

The honest summary: Harness won't replace the polished tools tomorrow. Its bet is that openness wins in the long run — and for a beginner, it's the cheapest way to understand what an agent actually does under the hood.

What to Try First

Once it's running, three beginner-friendly experiments:

1. Run a simple task. Ask the agent to create a folder, write a small Python file, and run it — then read the log to see every step it took.
2. Inspect the trajectory. Open the session log and find where the model called a tool, what it returned, and what the model decided next. Understanding this loop is the whole game.
3. Try a different model. If you have another provider's key, swap the plugin and run the same task — the difference in behavior teaches you more about models than any benchmark chart.

If you're new to the whole idea of agents, start with our beginner's guide to AI agents — it explains the concepts this article builds on. Wondering which model to feed your harness? Our ChatGPT vs Claude comparison helps, and the same logic applies to DeepSeek models. And if the command line above looks intimidating, Linux Terminal Basics gets you comfortable in ten minutes.

The star counter is already rolling. Whether Harness becomes the standard or a fascinating footnote, one thing is certain: the days when agents lived only inside black boxes are ending.

All code in this article was tested and runs successfully on Ubuntu 20.04 with Node.js v22.22.3 — verified with a real DeepSeek API key (headless agent task, file-creation tool use, Web UI on port 3080), August 2026.