When you hand DeepSeek Harness a local model and a folder of real files, the first question is not which flag to type. It is what the agent will do to those files. We asked a 1.7B model to sum one column of a CSV, and on our first run, in the default write mode, it answered correctly after it had replaced the header with the total. This DeepSeek Harness cheat sheet starts from that run, so the read-only switch sits next to the commands that need it.
You get the dsh launcher flags, headless runs with JSON and session resume, permission modes, Web UI slash commands, the patch files that move dsh between Ollama, llama.cpp and vLLM, and the errors each step threw. This November 2026 update re-tests the install, the Ollama route and the errors on Ubuntu 24.04 against dsh 0.2.2-rc.1, npm’s latest, with qwen3:1.7b on CPU. The DeepSeek Harness Ubuntu install guide covers the first launch, and the DeepSeek Harness Ollama setup explains the local route.
Using the DeepSeek Harness cheat sheet
The tables are the reference and the source of the PDF. The launcher, headless, Web UI flag and path rows were checked on 0.2.2-rc.1, either by running them on our test VM or by reading the help text that build printed. The slash commands, the less common environment variables, the Web UI screens and the llama.cpp run come from our first pass on 0.2.1-rc.5 earlier this month, and every timing is a CPU timing. <profile> stands for web, headless or a profile you made yourself. Put launcher flags before the task text, because dsh hands everything after the first unknown token to the booted app and you would otherwise send your flag to the agent as part of the prompt.
Launcher and profiles
| Command | What it does |
|---|---|
dsh --version | Print the launcher version (-V also works) |
dsh web | Boot the web profile, same as dsh --profile web |
dsh headless "task" | Answer one task, print it, exit |
dsh --profile <name> | Boot any profile under ~/.dsh/profiles |
dsh ci --from-default-profile headless | Create or reset a custom profile from a shipped template |
dsh <profile> --patch ./extra.yml | Apply one more overlay after your patches (repeatable) |
dsh <profile> --dump-config | Print the composed plugin tree and exit |
dsh <profile> --dump-default-config | Same tree without your patches |
dsh <profile> --dump-config-schema | JSON Schema for profile entries and patches |
dsh <profile> --help | The booted app’s own flags |
dsh plugin --profile <name> add <pkg> | Install a plugin bundle into a profile (needs pnpm) |
Headless runs
| Command | What it does |
|---|---|
dsh headless "run the tests" | Answer on stdout, diagnostics on stderr |
echo "task" | dsh headless | Read the task from stdin (a lone - does the same) |
dsh headless --json "task" | Newline-delimited run events instead of the final message |
dsh headless --session-id <id> "task" | Continue a saved session (an unknown id is an error) |
dsh headless --permission-mode read-only "task" | Pick the permission preset for this run (new in 0.2.2) |
DSH_PERMISSION_MODE=read-only dsh headless "task" | Same preset from the environment, works on every build |
dsh headless --approval-policy never "task" | Approval after the preset: ask or never |
dsh headless --add-dir /repo/.git "task" | Allow one more absolute directory under workspace-write (repeatable) |
dsh headless --patch ~/local-routes.yml --patch ~/use-vllm.yml "task" | Swap server and model for one run |
Web UI flags
| Command | What it does |
|---|---|
dsh web --no-open | Serve on 127.0.0.1:3080 without opening a browser |
dsh web --port 8080 | Listen on another port (0 lets the OS pick) |
dsh web --host 10.0.1.50 | Bind one local address (wildcards are rejected) |
--public-url https://app.example/ --trusted-host app.example | Run behind a reverse proxy |
--tls-cert chain.pem --tls-key key.pem | Serve HTTPS with an existing certificate |
ssh -L 3080:127.0.0.1:3080 [email protected] | Reach a remote box’s UI from your laptop |
Web UI slash commands
| Command | What it does |
|---|---|
/goal | Set or view the goal for a long-running task |
/plan | Enter or leave plan mode (advisory, tools stay callable) |
/feedback | Record feedback about this session |
/compact | Compact older conversation history |
/permission | Switch the permission preset |
/model | Select the model for this conversation |
/export | Download the session log as a ZIP |
@file | Reference a file or an earlier session |
Files and paths
| Path | What it holds |
|---|---|
~/.dsh/cordis.patch.yml | Home patch, read by every profile, wins over profile patches |
~/.dsh/profiles/<name>/cordis.patch.yml | Per-profile patch (the Web UI saves its edits here) |
~/.dsh/profiles/<name>/package.json | The bundle list a profile boots |
~/.dsh/sessions/<workspace>/ | One directory per session, log in session.v4.jsonl.zstd |
~/.dsh/.credentials.yaml | Keys saved from the Web UI Models page (web profile) |
~/.dsh/logs/ | Startup failure reports |
AGENTS.md | Workspace instructions (CLAUDE.md also loads), 64 KiB budget |
Environment variables
| Variable | Effect |
|---|---|
DSH_PERMISSION_MODE | read-only, workspace-write (default) or danger-full-access |
DSH_HOME | Move the whole ~/.dsh tree |
DSH_TELEMETRY_MODE=DISABLED | Turn off OpenTelemetry session upload |
DSH_TOOLS_MODE | native or ptc tool presentation |
DEEPSEEK_API_KEY | Key for the bundled deepseek-official route |
OLLAMA_API_KEY | Whatever your route’s apiKeyEnv names; any value works for Ollama |
OLLAMA_CONTEXT_LENGTH=16384 | Server side: the context Ollama actually serves |
Local model switches
| Patch key | What it sets |
|---|---|
baseURL: http://127.0.0.1:11434/v1 | Ollama’s OpenAI-compatible endpoint |
baseURL: http://127.0.0.1:8080/v1 | llama-server started with --port 8080 |
baseURL: http://127.0.0.1:8000/v1 | vLLM’s default port |
api: openai-completions | Protocol for all three servers |
apiKeyEnv: OLLAMA_API_KEY | Env var that must be set, or the route has no key |
contextWindow: 16384 | Must match what the server serves |
reasoning: "off" | Default effort Off for the route |
id: agent-default-model | Row that picks the provider and model for new sessions |
The permission presets deserve their own line because they are the one setting that changes what the agent may do, not how it talks. read-only and workspace-write both keep approval at ask. danger-full-access turns the sandbox off and sets approval to never. A headless run has nobody to ask, so in practice ask means “refuse” there, and the permission section below shows you a real refusal.
Installing dsh and checking the build
dsh is a Node package, and 0.2.2-rc.1 is the first release candidate that declares a Node floor: node >=24.9.0. The other two npm tags, 0.2.2-rc.2 on next and 0.2.2-alpha.3 on alpha, declare the same floor. Ubuntu 24.04’s archive ships Node 18, so take Node 24 from NodeSource: download its setup script, then run it. The apt line after it also pulls jq and zstd for reading session logs and bubblewrap, the sandbox backend dsh prefers on Linux:
curl -fsSL https://deb.nodesource.com/setup_24.x -o nodesource_setup.sh
sudo -E bash nodesource_setup.sh
sudo apt-get install -y nodejs jq zstd bubblewrap
sudo npm install -g @deepseek-ai/dsh@latest
Our first attempt on the refresh VM reused the Node 22 line this page used to print. npm installed the package anyway and only warned about it, which is easy to miss in a long scroll:
npm warn EBADENGINE Unsupported engine {
npm warn EBADENGINE package: '@deepseek-ai/[email protected]',
npm warn EBADENGINE required: { node: '>=24.9.0' },
npm warn EBADENGINE current: { node: 'v22.23.5', npm: '10.9.9' }
npm warn EBADENGINE }
added 656 packages in 1m
npm only warns with EBADENGINE here, it doesn’t refuse, and the install exits 0, so a provisioning script sees success. dsh even started on Node 22 and printed its version, so nothing forces you to notice. Don’t stay there. The floor is the maintainers telling you which runtime they test against, and a developer preview that fails on an unsupported runtime will fail in ways nobody upstream reproduces. Switching to Node 24 and running the same npm install again cleared the warning, and npm closed with “removed 2 packages, and changed 654 packages in 26s”. The npm that came with Node 24 also listed five dsh dependencies with install scripts under an install-scripts warning, and dsh ran normally after it on our VM. npm 12 blocks dependency install scripts by default, and three on that list build or fetch native pieces (node-pty, koffi and dsh’s own spawn helper), so on npm 12 pass the allow list npm printed:
sudo npm install -g --allow-scripts=@deepseek-ai/dsh-subprocess-local,koffi,node-pty,@google/genai,protobufjs @deepseek-ai/dsh@latest
We didn’t need that line on our VM, but it is the one npm itself suggests, and it keeps the install reproducible once your npm moves to 12. Our dsh getting-started guide runs the same Node 24 setup and carries on to the first launch.
Check the build you got, then compare it with the npm tags. The project is a developer preview and says it will break compatibility between release candidates, so the version belongs in your notes next to any config you write:
dsh --version
npm view @deepseek-ai/dsh dist-tags
On our Node 24 recheck, latest pointed at 0.2.2-rc.1 and next had already moved on to 0.2.2-rc.2, which we haven’t tested yet. The alpha tag, which sat ahead of the release candidate on our first pass, now trails it.
0.2.2-rc.1
{ alpha: '0.2.2-alpha.3', next: '0.2.2-rc.2', latest: '0.2.2-rc.1' }
Stay on latest for anything a team depends on. Running dsh with no profile only prints error: --profile <name> is required, which is the launcher telling you it’s a profile loader first and an agent second.
Pointing dsh at a local Ollama model
A fresh dsh only knows the deepseek-official route, so the first headless run on a box without a DeepSeek key fails straight away. Declaring an Ollama route without apiKeyEnv fixes that error and replaces it with a second one. On 0.2.2-rc.1 there is a third, for a route that names apiKeyEnv when the variable isn’t exported. All three are worth recognising because they look alike:

Ollama ignores the key, but dsh won’t send a request on a route that has no key at all. Exporting OLLAMA_API_KEY=ollama on its own doesn’t help either: we tried it on 0.2.2-rc.1 against the route without apiKeyEnv and got the same PI_AI_ERROR, because dsh only reads the variable a route names. Install Ollama with the official script and pull a small model first, since a CPU box can’t carry much more than 2B parameters at a usable speed:
curl -fsSL https://ollama.com/install.sh | sh
ollama pull qwen3:1.7b
Next, give Ollama a context length that fits the agent. dsh’s first request on our VM was about 5,600 tokens of system prompt and tool schemas before the task even started, so a small default context clips the prompt. Open a drop-in for the service:
sudo systemctl edit ollama.service
Add the variable under a service section, then save and close the editor. systemd keeps the drop-in separate from the packaged unit, so an Ollama upgrade won’t overwrite it.
[Service]
Environment="OLLAMA_CONTEXT_LENGTH=16384"
Now write the route into the home patch, the one file every profile reads. Profile patches exist too, but a route in ~/.dsh/profiles/web/cordis.patch.yml only reaches the Web UI, so headless runs would still fail:
mkdir -p ~/.dsh
vim ~/.dsh/cordis.patch.yml
This is the exact file our lab ran with. The contextWindow matches the drop-in above, and the second entry makes the route the default for new sessions:
- id: llm-pi-ai
config:
providers:
ollama:
displayName: Ollama
apiKeyEnv: OLLAMA_API_KEY
api: openai-completions
baseURL: http://127.0.0.1:11434/v1
models:
- id: qwen3:1.7b
name: Qwen3 1.7B
contextWindow: 16384
maxTokens: 4096
- id: agent-default-model
config:
provider: ollama
model: qwen3:1.7b
Export the variable the route names, restart Ollama so the drop-in takes effect, and confirm both sides agree. Put the export in ~/.bashrc once it works, because on 0.2.2-rc.1 a new shell without it stops every run with MISSING_CREDENTIAL: llm-pi-ai: no credential for provider route "ollama":
export OLLAMA_API_KEY=ollama
sudo systemctl daemon-reload && sudo systemctl restart ollama
ollama run qwen3:1.7b hi >/dev/null
ollama ps
dsh headless --dump-config | grep -B1 -A13 "id: llm-pi-ai"
Read two things in the output: the CONTEXT column from ollama ps, and the comment line above the route, which names the file that supplied it. If the comment does not mention ~/.dsh/cordis.patch.yml, dsh is not reading your patch.

Ollama reports 16384 and the route declares 16384, so nothing gets truncated silently. The model loaded at 3.4 GB and ran 100% on CPU, which is why every timing below is measured in minutes, not seconds. Even dsh headless "say hi" took 2m13s on the 8 vCPU refresh VM, most of it spent on a reasoning block before the one-word answer.
Running one-shot tasks with dsh headless
The headless profile answers one task and exits, which makes it the mode for cron jobs, CI steps and shell scripts. It boots the same base bundle as the Web UI, including the sandbox and the default workspace-write preset. That default is what produced the surprise from the intro. Create the same three-line test file if you want to repeat it:
mkdir -p ~/demo
printf 'name,qty\nwidget,3\nbolt,12\n' > ~/demo/parts.csv
The task only asked for a total, run from inside that folder so it becomes the workspace:
cd ~/demo
time dsh headless "Read parts.csv and tell me the total quantity."
On our first pass, on 0.2.1-rc.5, the answer was right and took 3m11s. The session log told a different story, so we pulled the tool calls out of the newest session file with zstd and jq:
LATEST=$(ls -t ~/.dsh/sessions/*/*/session.v4.jsonl.zstd | head -1)
zstd -dc "$LATEST" | jq -c 'select(.type=="tool/call").data | {step, name, arguments}'
cat parts.csv
Step 2 shows the model calling grep for “qty” and then edit to replace it with “15”, and the last command confirms the header is gone:

Nothing in the final answer hinted at the edit, which is the part that should worry a small team. The sandbox did its job, since the write stayed inside the workspace, but the workspace is exactly where your data lives. Treat workspace-write as the mode for tasks that are supposed to change files, keep the workspace under Git so git diff catches this, and use read-only for questions.
The same prompt on 0.2.2-rc.1 went wrong in a different way. After 2m34s the model reported that parts.csv was missing from /home/mary/demo, because its reasoning planned a read of part.csv, and the file came through untouched. Neither run is the harness misbehaving; both are a 1.7B model guessing at tool arguments. That’s the reason to judge a small local model by its tool calls in the session log, never by how confident the final sentence sounds.
Headless sessions can be continued, and --json turns the run into events a script can parse. The session id is the name of the session’s directory, so grab it from the newest log and ask a follow-up:
SID=$(basename "$(dirname "$LATEST")")
dsh headless --session-id "$SID" --json "Which part has the larger quantity? One line."
Each line is one event. The final event carries the answer, and the step_end usage shows why a follow-up is cheap.

Out of 5,083 total tokens, 4,866 came from the prompt cache, and the whole turn finished in under 7 seconds against minutes for a cold run. For scripts, filter on the final event with jq -r 'select(.type=="final").text' and you get the answer alone. The capture above is from 0.2.1-rc.5. On 0.2.2-rc.1 the same resume also emits a thinking event holding the model’s reasoning before the text event, and its final event now repeats the sessionId, so a filter that keys on the event type keeps working while one that counts lines does not. That resumed turn used 4,901 tokens, 4,654 of them from cache.
Locking runs down with permission modes
0.2.2-rc.1 gives headless runs a --permission-mode <preset> flag, which its help describes as selecting a configured preset for this task, including on resume. On 0.2.1-rc.5 the same flag failed with error: unknown option, so a script that has to run on both builds should keep using the DSH_PERMISSION_MODE environment variable, which the sandbox and approval plugins read at boot. Next to it, rc.1 adds --approval-policy ask|never and a repeatable --add-dir for one extra absolute directory under workspace-write. In the Web UI, the /permission command does the same job. These are the three presets 0.2.1-rc.5 shipped, and rc.1’s --permission-mode read-only run accepted the same name:
read-only: reads anywhere, no writes, approval askworkspace-write: writes inside the workspace and temp dirs, approval ask (the default)danger-full-access: no sandbox, approval never
We restored the header (the printf line above rewrites the file) and ran the same question in read-only mode. This run also had reasoning turned off, covered in the next section, so both changes count toward the faster time:
time DSH_PERMISSION_MODE=read-only dsh headless "Read parts.csv and tell me the total quantity."
On rc.5 you get the same answer, no edit this time, and 1m01s instead of 3m11s. The rc.1 recheck ran with reasoning still on: 3m29s, a correct read of the file, the total of 15 reached inside the reasoning text, and a CSV left exactly as it was. The catch for scripts is that the run printed only dsh: reasoning: blocks and no answer line after them, yet the exit code was still 0. A cron job that trusts the exit code would have recorded a missing answer as a success, so check that the answer is there as well.

To see what read-only does when a task does need a write, we asked for a new line appended to the CSV. The model tried the write, the sandbox refused it, and the escalation path asked for approval. Headless has no one to approve, so the run ended after 2m51s with the model reporting the refusal instead of crashing. These two tool results recorded the reason (two lines between them are trimmed).
Error: [sandbox: file access denied under read-only mode]
Error: sandbox escalation to "workspace-write" requires approval, but no approval channel is available
That’s the behaviour you want from a scheduled job: it fails closed and leaves the file alone. The same log also showed several invalid escalation errors before that, from the small model filling in the escalation fields wrong, which cost turns but nothing else.
Trading speed for accuracy with reasoning effort
Qwen3 thinks before it answers, and on a CPU those thinking tokens are most of the wall time. The first headless run printed three dsh: reasoning: blocks before its one-line answer. Add reasoning: "off" to the provider and map the efforts the model supports, and the route defaults to Off while the Web UI offers High in its picker. This is the patch the read-only run used:
- id: llm-pi-ai
config:
providers:
ollama:
displayName: Ollama
apiKeyEnv: OLLAMA_API_KEY
api: openai-completions
baseURL: http://127.0.0.1:11434/v1
reasoning: "off"
compat:
supportsDeveloperRole: false
maxTokensField: max_tokens
models:
- id: qwen3:1.7b
name: Qwen3 1.7B
contextWindow: 16384
maxTokens: 4096
reasoningEfforts:
"off": none
high: high
- id: agent-default-model
config:
provider: ollama
model: qwen3:1.7b
The two compat keys tell dsh to send a plain system role and use max_tokens, which is what OpenAI-compatible local servers expect. Each reasoningEfforts entry maps a picker label to the value dsh sends as the reasoning effort, so Off sends none; the upstream providers guide also shows an empty Off that sends nothing. We only tested the none mapping, and Ollama accepted it. Off is not free, though. In the Web UI, with the session in Read Only mode and effort Off, the same 1.7B model read the file and answered 3, the number of lines, not the total:

Switching the picker to High and asking it to check again produced 15, with the header row correctly left out of the sum. The price shows in the footer, where the session’s average speed fell from 19 tok/s to 5.7 tok/s:

So the rule we’d keep for a model this small: Off for lookups you can verify at a glance, High for anything you’d act on without checking. A larger model on a GPU narrows the gap, and the Ollama models by VRAM table shows which ones fit your card.
Driving the Web UI and its slash commands
The Web UI binds to loopback by default, port 3080, and on rc.5 the startup line carries a session token in the URL. Start it from the folder you want as the workspace, because the invoking directory becomes the default workspace root:
cd ~/demo
dsh web --no-open
It prints one line and stays in the foreground. Copy the whole URL, token included (ours is redacted here).
dsh web: http://127.0.0.1:3080/?token=REDACTED-SESSION-TOKEN
On a remote VM, forward the port with ssh -L 3080:127.0.0.1:3080 instead of binding a public address, since this process can write to your source tree. Type / in the message box and the command menu opens. The two entries that change how the agent behaves are marked:

- 1/plan
- 2/permission
/plan asks the agent to explore and present a plan for your approval before it implements anything, but it is an instruction, not a lock: upstream documents that every tool stays callable in plan mode. Pair it with /permission set to Read Only when the plan must not touch files. /permission is the Web UI’s version of DSH_PERMISSION_MODE, so you can start a session read-only and widen it only when a step needs to write. /compact earns its keep on a 16K context, where a long session fills up fast. /export downloads the session log as a ZIP, which is what you attach to a bug report.
Model routes show up under the account menu (the ··· More button at the bottom of the sidebar), then Settings, then Models. A route from your patch file appears with a Custom badge, and the dot beside each provider tells you whether dsh found a key for it:

- 1Ollama route from cordis.patch.yml
- 2No DeepSeek key
Mark 1 is the Ollama route from cordis.patch.yml, and mark 2 is the red dot that means No DeepSeek key. Red on DeepSeek is expected on a box without that key. Red on your own route means the variable named in apiKeyEnv wasn’t set in the shell that started dsh web, so stop the server, export it and start again.
Be careful with the Edit button on a route that came from the home patch. The Web UI saves its changes to the web profile’s patch, the home patch is applied after it, and a patch replaces a row’s whole config, so your home-patch llm-pi-ai row silently wins over anything you change there. Edit routes in ~/.dsh/cordis.patch.yml instead.
Switching between Ollama, llama.cpp and vLLM
Keep Ollama in the home patch and put the other servers in a separate overlay, then pick per run with --patch. Overlays apply after every other layer, and a patch replaces a row’s whole config rather than merging into it, so the overlay has to carry every provider it uses. Ours declared llama-server on port 8080 and vLLM on 8000 and made llama.cpp the default:
vim ~/local-routes.yml
Add both providers and the default row, then save the file.
- id: llm-pi-ai
config:
providers:
llamacpp:
displayName: llama.cpp
apiKeyEnv: LLAMACPP_API_KEY
api: openai-completions
baseURL: http://127.0.0.1:8080/v1
compat:
supportsDeveloperRole: false
maxTokensField: max_tokens
models:
- id: ggml-org/Qwen3-1.7B-GGUF
name: Qwen3 1.7B (llama.cpp)
contextWindow: 16384
maxTokens: 4096
vllm:
displayName: vLLM
apiKeyEnv: VLLM_API_KEY
api: openai-completions
baseURL: http://127.0.0.1:8000/v1
compat:
supportsDeveloperRole: false
maxTokensField: max_tokens
models:
- id: Qwen/Qwen3-4B-Instruct-2507
name: Qwen3 4B Instruct (vLLM)
contextWindow: 32768
maxTokens: 8192
- id: agent-default-model
config:
provider: llamacpp
model: ggml-org/Qwen3-1.7B-GGUF
A second, four-line overlay moves only the default to vLLM, so one extra --patch flips the server without editing anything:
vim ~/use-vllm.yml
It holds just the default-model row. Because it applies after local-routes.yml, its row wins, and the provider list from the first overlay stays in place.
- id: agent-default-model
config:
provider: vllm
model: Qwen/Qwen3-4B-Instruct-2507
For llama.cpp we used the prebuilt Ubuntu CPU binaries from build b12032, and our llama.cpp cheat sheet covers the rest of the llama-server flags. Download and unpack them in your home directory:
cd ~
# https://github.com/ggml-org/llama.cpp/releases
curl -sLO https://github.com/ggml-org/llama.cpp/releases/download/b12032/llama-b12032-bin-ubuntu-x64.tar.gz
tar -xzf llama-b12032-bin-ubuntu-x64.tar.gz
Start the server and let -hf fetch the GGUF. The first start downloads the model, so poll /health until it answers before asking for the model list. The id dsh needs is whatever /v1/models returns, character for character:
~/llama-b12032/llama-server -hf ggml-org/Qwen3-1.7B-GGUF --port 8080 -c 16384 > ~/llama-server.log 2>&1 &
until curl -sf http://127.0.0.1:8080/health >/dev/null; do sleep 2; done
curl -s http://127.0.0.1:8080/v1/models | jq -r ".data[].id"
export LLAMACPP_API_KEY=none VLLM_API_KEY=none
The id came back as ggml-org/Qwen3-1.7B-GGUF, matching the overlay. We then checked that the overlay composed, asked llama.cpp in read-only mode how many lines parts.csv has, and tried the vLLM default with no vLLM server running, since this CPU box can’t host one:

The dump comment lists both files, home patch first and overlay second, and the llama.cpp run gave the correct line count, 3, in 2m0s. llama-server’s log put the cost in plain numbers. The first request was 5,649 prompt tokens and took 48.7 seconds to process at 116 tok/s, while the follow-up step needed only 67 new tokens because the prefix was cached. The vLLM line shows what an unreachable endpoint looks like, TRANSPORT: Connection error, which on a GPU host usually means vLLM is still loading weights. Serving vLLM itself, with the tool-call parser flags dsh needs, is covered in the local model guide’s vLLM section.
Making a custom profile for scripts
A custom profile gives a job its own patch file, so a CI route or a stricter preset never leaks into your interactive sessions. You can copy any of the five templates rc.5 ships under a name of your own, as long as it isn’t one of the template names:
web: base plus the browser UIheadless: base plus one-shot runssdkandsdk-minimal: JSON-RPC over stdio for the SDKsacp: Agent Client Protocol over stdio for editors
For a script, copy headless under a new name and look at what you got:
dsh ci --from-default-profile headless --dump-config | head -3
cat ~/.dsh/profiles/ci/package.json
The new profile is a directory with an empty patch and a manifest listing the same two bundles the shipped headless profile uses.
{
"name": "dsh-profile-ci",
"private": true,
"dependencies": {},
"dsh": {
"profile": {
"bundles": [
"@deepseek-ai/dsh-base",
"@deepseek-ai/dsh-headless"
]
}
}
}
From then on, dsh ci "task" boots it. Be careful with the flag on a profile you’ve already customised: --from-default-profile deletes the old directory, its installed plugins and its patch before writing the fresh copy. The home patch still applies on top, so the Ollama route from earlier reaches ci without copying it.
Fixing common dsh errors
Every error below came out of this lab. All but the --permission-mode error, which rc.1 no longer throws, and the sandbox refusal were reproduced again on 0.2.2-rc.1. Three of them in one capture, all from names and ids that older guides and other agents’ habits suggest:

Each one has its own fix, and the sections that follow give the exact message first so you can match it against your terminal.
Error: “MISSING_CREDENTIAL: llm-deepseek: no API key for provider route deepseek-official”
dsh fell back to its bundled DeepSeek route because no other route is the default. Either export DEEPSEEK_API_KEY, or add the agent-default-model row from the Ollama section so a local route wins. dsh looks for keys in the environment, then ~/.dsh/.credentials.yaml, then a .env in the invoking directory, then ~/.dsh/.env. The headless tree disables the local credentials row, though, so a key saved from the Web UI Models page may not reach dsh headless; export it or put it in a .env file for scripts.
Error: “PI_AI_ERROR: No API key for provider: ollama”
The route exists but has no key, so dsh stops before it sends anything. Add apiKeyEnv: OLLAMA_API_KEY to the provider and export that variable in the shell that starts dsh. Ollama never checks the value, which is why ollama or any other string works.
Error: ‘MISSING_CREDENTIAL: llm-pi-ai: no credential for provider route “ollama”‘
0.2.2-rc.1 reports this case with its own message, and it means the patch is right but the shell is not. The route names apiKeyEnv: OLLAMA_API_KEY, and that variable is unset where dsh started, which is what a fresh terminal or a cron job gives you. The full message says it resolves OLLAMA_API_KEY, which is not set, so export OLLAMA_API_KEY=ollama, put it in ~/.bashrc or the job’s environment, and run again. Don’t remove apiKeyEnv to silence it, since that takes you back to PI_AI_ERROR.
Error: “unknown option ‘–permission-mode'”
You’re on 0.2.1-rc.5 or older, where the flag doesn’t exist yet; 0.2.2-rc.1 accepts it. The name is Claude Code’s, and muscle memory carries it over (the DeepSeek Harness vs Claude Code comparison covers where the two really differ). Upgrade, or set DSH_PERMISSION_MODE=read-only in front of the command, which works on both builds, or use /permission in the Web UI.
Error: ‘profile “tui” does not exist’
Neither rc.5 nor rc.1 has a terminal UI profile in the box (a fresh rc.1 install creates only headless and web under ~/.dsh/profiles), even though dsh --help uses tui in its examples. The upstream CLI reference adds a terminal UI plugin with dsh plugin --profile tui add github:deepseek-harness/turtle-ui, which needs pnpm. We didn’t install it, so use dsh web or dsh headless unless you want to try it.
Error: “session … does not exist; omit –session-id to start a new Session”
The id has to match a directory under ~/.dsh/sessions/ for the current workspace. Sessions are filed per working directory, so a resume from your home folder looks in the wrong place even when the id is right. Run the resume from the same folder that started the session, or list the workspace directory to copy a valid id.
Error: “TRANSPORT: Connection error.”
0.2.2-rc.1 prints the cause after the old text, TRANSPORT: Connection error.: connect ECONNREFUSED 127.0.0.1:8000, which settles it: nothing answered at the route’s baseURL, so dsh gave up before the model saw a token. Check the server with curl -s http://127.0.0.1:8000/v1/models (swap in your port). A patch pointing at 127.0.0.1 means the machine running dsh, not the GPU box across the room, because every route is resolved from the dsh process.
Error: ‘names shipped profile “headless” and cannot be a custom profile target’
You pointed --from-default-profile at a shipped name, as in dsh headless --from-default-profile headless, which is how we reproduced it on rc.1. Shipped names can’t be reset this way, because dsh rebuilds them from its own templates on first use. Pick a new name such as ci instead. The related unknown default profile "tui" error lists the five valid templates.
Error: “sandbox escalation … requires approval, but no approval channel is available”
A headless run in read-only or workspace-write mode tried something its preset doesn’t allow. That’s working as designed. Rerun with the narrowest mode that fits the task, and reach for danger-full-access only inside a throwaway VM or container.
Keeping dsh current between release candidates
Upgrading is the same global install, and the risk is in your patches, not the binary. Between the release our first DeepSeek Harness guide used and this one, the session file moved from session.jsonl.zstd to session.v4.jsonl.zstd, so any script that globbed the old name now finds nothing. Before each upgrade, run this short routine:
- Save the composed tree:
dsh headless --dump-config > before.yml - Read
npm view @deepseek-ai/dsh dist-tagsand the release notes - Check the Node floor of the build you’ll install with
npm view @deepseek-ai/dsh@latest engines(empty on rc.5,{ node: '>=24.9.0' }on 0.2.2-rc.1, and npm only warns when you miss it) - Upgrade with
sudo npm install -g @deepseek-ai/dsh@latest - Dump again and diff the two files
- Run one read-only headless task before anyone opens the Web UI
The diff is the one check worth keeping. The dump comments name which file supplied each row, so a renamed plugin id shows up there as a row your patch no longer reaches. dsh also reports unmatched patch targets on stderr during a dump, so read that too.
One setting to look at on day one rather than day thirty: the base bundle uploads session logs to DeepSeek by default when you use the official API, and sends OpenTelemetry session data when you leave feedback. For a team that only runs local models, set DSH_TELEMETRY_MODE=DISABLED and turn off the session log upload under Settings, General. The DeepSeek Harness repository documents both, and the other agents we’ve mapped the same way are in the Claude Code cheat sheet, the OpenCode CLI cheat sheet and the rest of our free cheat sheet PDFs.