AI

DeepSeek Harness Cheat Sheet: dsh Commands, Config, Errors (PDF)

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.

Original content from computingforgeeks.com - post 182292

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

CommandWhat it does
dsh --versionPrint the launcher version (-V also works)
dsh webBoot 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 headlessCreate or reset a custom profile from a shipped template
dsh <profile> --patch ./extra.ymlApply one more overlay after your patches (repeatable)
dsh <profile> --dump-configPrint the composed plugin tree and exit
dsh <profile> --dump-default-configSame tree without your patches
dsh <profile> --dump-config-schemaJSON Schema for profile entries and patches
dsh <profile> --helpThe booted app’s own flags
dsh plugin --profile <name> add <pkg>Install a plugin bundle into a profile (needs pnpm)

Headless runs

CommandWhat it does
dsh headless "run the tests"Answer on stdout, diagnostics on stderr
echo "task" | dsh headlessRead 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

CommandWhat it does
dsh web --no-openServe on 127.0.0.1:3080 without opening a browser
dsh web --port 8080Listen on another port (0 lets the OS pick)
dsh web --host 10.0.1.50Bind one local address (wildcards are rejected)
--public-url https://app.example/ --trusted-host app.exampleRun behind a reverse proxy
--tls-cert chain.pem --tls-key key.pemServe 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

CommandWhat it does
/goalSet or view the goal for a long-running task
/planEnter or leave plan mode (advisory, tools stay callable)
/feedbackRecord feedback about this session
/compactCompact older conversation history
/permissionSwitch the permission preset
/modelSelect the model for this conversation
/exportDownload the session log as a ZIP
@fileReference a file or an earlier session

Files and paths

PathWhat it holds
~/.dsh/cordis.patch.ymlHome patch, read by every profile, wins over profile patches
~/.dsh/profiles/<name>/cordis.patch.ymlPer-profile patch (the Web UI saves its edits here)
~/.dsh/profiles/<name>/package.jsonThe bundle list a profile boots
~/.dsh/sessions/<workspace>/One directory per session, log in session.v4.jsonl.zstd
~/.dsh/.credentials.yamlKeys saved from the Web UI Models page (web profile)
~/.dsh/logs/Startup failure reports
AGENTS.mdWorkspace instructions (CLAUDE.md also loads), 64 KiB budget

Environment variables

VariableEffect
DSH_PERMISSION_MODEread-only, workspace-write (default) or danger-full-access
DSH_HOMEMove the whole ~/.dsh tree
DSH_TELEMETRY_MODE=DISABLEDTurn off OpenTelemetry session upload
DSH_TOOLS_MODEnative or ptc tool presentation
DEEPSEEK_API_KEYKey for the bundled deepseek-official route
OLLAMA_API_KEYWhatever your route’s apiKeyEnv names; any value works for Ollama
OLLAMA_CONTEXT_LENGTH=16384Server side: the context Ollama actually serves

Local model switches

Patch keyWhat it sets
baseURL: http://127.0.0.1:11434/v1Ollama’s OpenAI-compatible endpoint
baseURL: http://127.0.0.1:8080/v1llama-server started with --port 8080
baseURL: http://127.0.0.1:8000/v1vLLM’s default port
api: openai-completionsProtocol for all three servers
apiKeyEnv: OLLAMA_API_KEYEnv var that must be set, or the route has no key
contextWindow: 16384Must match what the server serves
reasoning: "off"Default effort Off for the route
id: agent-default-modelRow 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:

dsh 0.2.2-rc.1 failing with MISSING_CREDENTIAL for deepseek-official, PI_AI_ERROR without apiKeyEnv, then MISSING_CREDENTIAL for the ollama route when OLLAMA_API_KEY is unset

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 ps showing qwen3:1.7b at 16384 context and dsh --dump-config showing the Ollama route patched by cordis.patch.yml

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:

dsh headless answering 15 after 3m11s while its tool calls show an edit that replaced the qty header in parts.csv

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.

dsh headless --session-id with --json printing session, status, text and final events for a resumed session

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 ask
  • workspace-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.

DSH_PERMISSION_MODE=read-only dsh headless run returning the total quantity 15 in 1m01s

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:

DeepSeek Harness model picker Effort menu offering Off and High from reasoningEfforts

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:

DeepSeek Harness Web UI after switching effort to High, qwen3 1.7b answering 15 in 1m32s at 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:

DeepSeek Harness Web UI slash command menu listing Goal, Plan, Feedback, Compact, Permission, Model and Export
  1. 1/plan
  2. 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:

DeepSeek Harness Settings Models page with the Ollama route marked Custom and a red dot on the DeepSeek provider
  1. 1Ollama route from cordis.patch.yml
  2. 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:

dsh --patch overlay switching to llama.cpp, answering a line count of 3 in 2m0s, then a vLLM overlay failing with TRANSPORT Connection error

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 UI
  • headless: base plus one-shot runs
  • sdk and sdk-minimal: JSON-RPC over stdio for the SDKs
  • acp: 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:

dsh 0.2.2-rc.1 errors for a missing tui profile, an unknown session id and a shipped profile used as a custom profile target

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:

  1. Save the composed tree: dsh headless --dump-config > before.yml
  2. Read npm view @deepseek-ai/dsh dist-tags and the release notes
  3. 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)
  4. Upgrade with sudo npm install -g @deepseek-ai/dsh@latest
  5. Dump again and diff the two files
  6. 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.

Keep reading

Ollama Models Cheat Sheet: Best Models by VRAM, Tested (PDF) AI Ollama Models Cheat Sheet: Best Models by VRAM, Tested (PDF) Open Source LLM Comparison Table (2026) AI Open Source LLM Comparison Table (2026) Claude Code Cheat Sheet: Commands, Shortcuts and Flags (PDF) AI Claude Code Cheat Sheet: Commands, Shortcuts and Flags (PDF) Dual GPU LLM Build: PCIe x8/x8 vs x16/x4, PSU and Cooling AI Dual GPU LLM Build: PCIe x8/x8 vs x16/x4, PSU and Cooling MCP vs RAG vs Agent Skills: When to Use Each AI MCP vs RAG vs Agent Skills: When to Use Each Install GitLab CE on Ubuntu 24.04 / Debian 13 with SSL Automation Install GitLab CE on Ubuntu 24.04 / Debian 13 with SSL

Leave a Comment

Press ESC to close