AI Guides › Workbench
By Nigel Guy · 8 min read
The usual mistake with a new free coding agent is to start it in the folder you care about most and tell it to "fix everything". It feels low-risk because the software is free and the window looks like a chat. It is not a chat: DeepSeek Harness can read and edit files and run commands on your computer, and its own safety notice says it has not been security-audited.
The rule: treat DeepSeek Harness as a developer preview you test on a copy, not a replacement you point at real work. Start it read-only in spirit, check what it proposes, and widen its access only once you have seen how it behaves.
| Word | Plain meaning |
|---|---|
| Harness | The program that wraps an AI model so it can use tools: read files, run commands, keep a plan. The model does the thinking; the harness does the doing. |
dsh |
The command name for DeepSeek Harness. |
Node.js / npx |
The free runtime dsh is built on; npx comes with it and runs a package without a separate install. |
| Plugin | Nearly every part (file tools, shell, web interface, model connections) is a plugin, so each can be swapped. |
| Workspace | The folder you allow the agent to work in. |
| API key | A password-like string that lets dsh use, and bill, your model provider account. |
Claude Code is Anthropic's agent and is built around Anthropic's models and plans. DeepSeek Harness is an open-source (MIT-licensed) harness published by DeepSeek on GitHub. Three practical differences:
dsh web starts a local web page rather than a terminal chat.anthropic, openai, moonshotai for Kimi and zai for GLM) or any OpenAI- or Anthropic-compatible endpoint. Providers that sign in with OAuth, such as Codex, are not supported there yet.Is it a plugin for Claude Code, Cursor or Codex? No. It is a separate application. It has an ACP mode (dsh --profile acp) for clients that speak the Agent Client Protocol, and a Python SDK, but nothing you install inside those tools.
| Option | What it does | Cost at time of writing | Best for | Catch |
|---|---|---|---|---|
npx @deepseek-ai/dsh web with a DeepSeek API key |
Starts the web interface at http://127.0.0.1:3080 |
Harness is free. DeepSeek API is pay-as-you-go in US dollars: deepseek-flash lists $0.15 (about £0.11 at time of writing) per million input tokens on a cache miss and $0.60 (about £0.45) per million output tokens off-peak, with peak hours costing double; check the £ price at checkout |
First proper trial | You need to top up a DeepSeek account; agent sessions use more tokens than a chat |
dsh web with another provider's key |
Same interface, different model | Whatever that provider charges | Comparing models on the same task | You pay that provider's rates; some gateways need extra config |
ollama launch dsh |
Ollama installs and starts dsh for you |
Free for local models; Ollama's cloud models and web search need an Ollama account | Keeping work on your own machine | Local models need a capable computer and are usually weaker at tool use |
dsh --profile headless "job" |
Runs one task, prints the answer, exits | As per your model | Repeating a known task | Nothing to watch mid-run; not a beginner starting point |
Pound figures are rough conversions; check the pricing page before topping up.
In Terminal (Mac) or PowerShell (Windows), run:
node --version
You need version 22.19 or later, or 24 and above, according to the project's package.json. Otherwise install the current LTS version from nodejs.org and check again in a new window.
Copy a small project somewhere disposable and move into it, for example cd ~/dsh-practice. dsh treats the folder you start it from as its default location.
npx @deepseek-ai/dsh web
It downloads the package and opens http://127.0.0.1:3080 in your browser (add --no-open to stop that). Leave the terminal open; closing it stops the agent.
In the web page go to Settings → Models, paste your DeepSeek API key into the DeepSeek card and save. No restart is needed; the key is stored in ~/.dsh/.credentials.yaml by default. For another provider, choose Add model provider.
Click Choose workspace, add your practice folder and select it. You cannot type a message until you do. The component docs describe a Permissions selector (also reachable with the /permission command) whose shipped presets are workspace-write, which asks before actions that need approval, and danger-full-access, which never asks. Stay on the asking option.
A first task should only read. This prompt makes the agent describe the project and stop:
You are helping someone who is new to this codebase and new to coding agents.
Goal: explain what is in the current workspace folder without changing anything.
Steps:
1. List the files and folders at the top level, then open the files that look most important (README, package or config files, the main entry point).
2. Explain in plain English what this project appears to do and who it is for.
3. Name the main parts and what each one is responsible for, in a short table.
4. List anything you could not work out, and what file or information would answer it.
Constraints:
- Read only. Do not create, edit, move or delete files, and do not run install, build or network commands.
- If you would need to run a command to answer, describe the command and stop to ask me first.
- Where you are guessing, say "likely" and give the evidence.
Context about me: [WHAT_YOU_KNOW_ABOUT_THE_PROJECT, or "nothing"]
Before you answer, check that every claim points to a file you actually opened.
Fill in what you already know about the project, or write "nothing".
If that answer is accurate, try one small change, reading each approval request before accepting:
Make one small, reversible change in this workspace: [THE_CHANGE, e.g. "fix the typo in the README heading"].
Before editing, tell me which file(s) you will touch and show the exact change you plan. Wait for my go-ahead.
After editing, show what changed and how I can undo it.
Do not touch any file not named in your plan. If the change turns out larger than one or two files, stop and explain why instead of continuing.
Replace [THE_CHANGE] with one specific edit.
| Symptom | Likely fix |
|---|---|
node: command not found or npx not found |
Node.js is not installed or the terminal was opened before installing. Reinstall from nodejs.org and open a new window. |
| The composer will not let you type | No workspace selected, or no model. Choose a workspace; if it says Select model, pick one. |
MISSING_CREDENTIAL |
The key was not saved. Re-enter it in Settings → Models. |
UNKNOWN_MODEL |
Pick a configured model, or add the model ID to your custom provider. |
| Port 3080 already in use | Stop the other program, or start with npx @deepseek-ai/dsh web --port 3090. |
| It did something you did not want | Stop the terminal process (Ctrl+C), restore from your copy, and switch back to an asking permission preset. |
npx plus a DeepSeek key, on a practice folder.dsh-plugin GitHub topic until you have read their code; the safety notice names untrusted plugins as a risk.127.0.0.1..env files in the workspace.