DeepSeek Harness: the agent harness that runs 1017

DeepSeek Harness (dsh) is an agent harness released by DeepSeek AI under the MIT license. It is not the model: it wraps conversation sessions, file access, shell execution, search and plugins so a model can carry a task through. Its everything-is-a-plugin design lets you enable only the parts you need.

It is in developer preview, and compatibility-breaking changes are expected. For work use, pin a version and read the release notes before updating.

You need Node.js 22.19 or later, or 24 and later. Running npx @deepseek-ai/dsh web starts the Web UI at http://127.0.0.1:3080 and opens the browser for a local launch. Add --no-open to run the server alone.

To run from source, clone the repository and run pnpm install, pnpm run build, then pnpm dsh web. Settings and credentials live under $DSH_HOME after the first run, so base backups and deletions on that folder.

Under Settings → Models, enter an API key in the DeepSeek card to use deepseek-flash. The key cannot be read back; it is stored in $DSH_HOME/.credentials.yaml and settings keep only a reference.

Add other providers or an internal gateway² through Custom model API under Add model provider. Supply a provider ID, base URL, one API protocol (OpenAI Chat Completions, OpenAI Responses or Anthropic Messages) and at least one model ID; Fetch available models can list them. The provider ID cannot be renamed later, so choose it carefully.

A local server that exposes an OpenAI-compatible API, such as vLLM or llama.cpp's server, can also be added as a Custom model API. Set the base URL, model ID, context window³ and maximum output tokens⁴ to match the server. If the harness exceeds the real limit while compacting a long conversation or inserting tool output, the request fails.

Tool-calling reliability on a local model varies with the model and runtime⁵. A small model may break the tool schema or repeat a call, so narrow file and shell permissions and start with a short task. Attaching 1017 locally needs a server path such as vLLM; mainline llama.cpp still does not read this architecture.

DeepSeek says 1017 is tuned for dsh 0.2.1-rc.1 or later. Version 0.2.1-rc.2 adds a switch for the Search and Fetch APIs in web search settings. Those tools are free until November 1, 2026, and billed per successful request after that.

Note that a session keeps the model recorded in its own log. A session that has already sent a request does not switch to a new default, so open a new session to compare.

A preview release can change the settings file and plugin API. Back up $DSH_HOME/profiles/web/cordis.patch.yml, record the plugins and model settings you use, then update. Pinning a tag reproduces better than automatic updates.

Do not leave shell and file permissions at their defaults; narrow the working folder and allowed commands. A harness may take broad permissions for convenience, so check the sandbox⁶ and approval flow first on important repositories.