DeepSeek Harness: Setup, Configuration & Real Coding Tasks

Hand an LLM a bug report and it can usually produce a plausible patch. The harder part is finding the real call chain, editing the right files, running the tests, and using failures to decide what to do next. Our Harness Engineering article covered the software around that loop. This article looks at a concrete implementation: DeepSeek Harness, or dsh. The interesting question is not whether it has a chat interface. It is how to connect it to a repository and turn it into a workflow you can inspect, constrain, and verify.

What Is DeepSeek Harness?

DeepSeek Harness is an MIT-licensed agent harness built around the Cordis plugin system. Model connections, tools, sessions, storage, scheduling, and the interface are organized as replaceable components. That makes it a useful subject for engineers who want to change how an agent works, rather than only change the model behind it. Official overview →

The distinction from a single chat API call is who holds state and performs actions. A model can request a file read or a test run. The harness executes that request and returns the observation to the next model call. Configuring the harness means configuring that working environment, not discovering a magic system prompt.

Also distinguish an agent harness from an evaluation harness. One runs an agent; the other runs cases, grades outcomes, and compares systems. DeepSeek Harness can be the system under test or part of the execution infrastructure. Installing it does not give you a trustworthy definition of a successful PR. That belongs in a separate evaluation layer.

Step One: Launch Before Exploring Every Plugin

Start with the Web UI: it makes the model, workspace, and session state easier to inspect. Use a non-sensitive practice repository and a valid DeepSeek API key. The current repository requires Node.js ^22.19.0 || >=24.0.0; for source development, match the pnpm version declared in packageManager. Runtime requirements →

cd /path/to/your/practice-repo
node --version
npx @deepseek-ai/dsh web

Replace the example path with your repository. The default address is http://127.0.0.1:3080; append --no-open to suppress the browser launch. If you want to modify the harness itself, use the source route instead: Installation instructions →

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

These routes serve different goals: using an agent versus developing its runtime. The source route starts inside the harness repository; select the actual target project in the UI afterward. For team experiments, record the installed release or source commit. Repeating an unpinned npx command is not a reproducibility strategy.

Step Two: Connect a Model and Workspace

1. Open Settings → Models, enter the key in the DeepSeek card, and save. Model configuration changes do not require a server restart.
2. Use Choose workspace to add and select the project directory. A fresh UI does not automatically select it, even when you launched from that directory.
3. Check the model picker and start a session. First ask for the main modules, entry points, and test commands, with file references and no edits.

This follows the official Web UI guide. A read-only first task separates connectivity problems from a wrong directory or a difficult implementation. Concrete file references are more useful evidence than a fluent summary of the supposed technology stack.

UI-managed secrets live in $DSH_HOME/.credentials.yaml; settings retain references, and the page does not return the raw key. Add credentials directly for built-in providers, or choose Add a custom provider for a gateway. Existing active sessions retain their recorded model, so use a fresh session to verify a changed default. Model configuration guide →

Configuration: Settings, Profiles, and Presets

When a change appears to do nothing, first identify which layer you changed. These are not interchangeable names:

Model Settings: Change the Minimum

Open the running instance's configuration file from Settings. Merge these fields into the existing llm-deepseek section in settings.yaml, preserving its credential reference. Do not replace the whole file or introduce duplicate YAML keys.

llm-deepseek:
  reasoningEffort: high
  maxTokens: 16384

reasoningEffort sets this adapter's reasoning level; maxTokens caps output for one request. The value 16384 is an example, not the official default or a total task-spend limit. A multi-turn task can make many requests. The native adapter uses the deepseek-official route and defaults its credential environment reference to DEEPSEEK_API_KEY. Connection and model settings are read again for the next request. Native adapter reference →

Custom Gateways: Match the Wire Protocol

“OpenAI-compatible” is not a complete protocol description. Chat Completions, Responses, and Anthropic Messages are different interfaces. This is a structural example: replace the hostname and model ID with real gateway values, and make GATEWAY_API_KEY available to the process launching dsh.

llm-pi-ai:
  providers:
    team-gateway:
      apiKeyEnv: GATEWAY_API_KEY
      api: openai-completions
      baseURL: https://gateway.example.com/v1
      models:
        - id: your-served-model-id

This configures the llm-pi-ai adapter; do not assume every native DeepSeek setting transfers across. Verify a basic text request and a tool call before adding reasoning options or image input. Otherwise protocol errors, model capabilities, and tool execution failures become difficult to distinguish. Declare actual server limits rather than inflating a context window to silence an error. Provider adapter reference →

Profiles: Process Composition

web provides browser interaction, headless runs a one-shot task, and sdk serves SDK clients over stdio. Profiles compose plugin bundles and user patches into a runtime tree. Inspect it with --dump-config before changing unfamiliar plugin configuration. CLI entry modes →

npx @deepseek-ai/dsh --profile web --dump-config
npx @deepseek-ai/dsh --profile headless "Read the repository and report its test commands. Do not edit files or run commands."

Inspect your own composition instead of copying an entire plugin tree from an unrelated version. Treat configuration exports as potentially sensitive and review them before sharing. Also note that “do not run commands” is a task instruction, not an enforced security boundary. Actual restrictions require permissions and an appropriate execution environment.

Presets: Establish a Standard Baseline

The official presets include Standard, Code, Minimal, and Creator. Standard supplies common capabilities; Code exposes operations through a TypeScript SDK; Minimal reduces the tool surface to bash and editing; Creator targets runtime and plugin experiments. Start with Standard, complete a well-scoped task, then vary the tool arrangement. Preset overview →

The Web Minimal preset is not the CLI sdk-minimal profile. The latter currently omits approval and permission-settings services and uses danger-full-access. Fewer tools does not mean less privilege. Reload behavior also differs: adding a bundle requires restarting its profile, unlike ordinary live patch edits. CLI behavior and permission boundaries →

Use It on a Task You Can Actually Accept or Reject

Do not make “refactor the backend” your first experiment. Choose a small defect with an observable failure, such as a pagination boundary. This example does not assume a particular framework or test runner:

Goal: fix inconsistent list-endpoint behavior for page=0.

Investigate first:
1. Find the route, validation, and pagination tests; cite paths.
2. Establish whether the API rejects or normalizes zero.
   Ask me if the contract does not settle that decision.
3. Propose the smallest change; do not refactor nearby modules.

Implementation and acceptance:
- Add a reproducing test before changing the implementation.
- Use the repository's existing test, lint, and build commands.
- Cover zero, a normal page, and existing boundary behavior.
- Preserve uncommitted changes; do not delete or skip tests.
- Ask before adding dependencies, installing over the network,
  or expanding scope.
- Report the diff, commands actually run, results, and gaps.
- Do not commit, push, or deploy.

The key is not prompt length. It is separating a product decision from implementation. Returning 400 for page zero and treating it as page one are both plausible behaviors. Only one may satisfy your contract. Asking the agent to find evidence before writing the test prevents it from confidently implementing a different requirement.

For repeated work, keep stable conventions in project instructions: directory responsibilities, generated files that must not be edited, verification commands, and prohibited actions. Keep them short and testable. An instruction document is useful context, not a substitute for permission enforcement or a reason to inject the entire architecture manual into every turn.

Review the result at three levels: behavior matches the contract, regression coverage catches the bug, and scope stays within the request. Read the diff before trusting the summary. Any check the agent did not run should remain explicitly unverified, rather than quietly becoming a presumed pass.

Read the Trajectory, Not Just the Final Answer

The harness records session activity in an append-only log and exposes a Trajectory view for inspecting execution. Session design → A recorded trajectory is useful evidence, but not a guarantee that a new run will behave identically: model responses, dependencies, and external state can change.

A failed patch can have very different causes. The agent never found the relevant file. It found the file but misunderstood the contract. It made a reasonable edit but the environment lacked a dependency. Or the tests failed and it still declared success. Those call for context improvements, clarification, environment repair, and stronger acceptance checks respectively. “Use a smarter model” skips the diagnosis.

For a team trial, hold a few real tasks fixed and record success rate, elapsed time, human interventions, and actual token usage. Keep the repository commit, task, model, and permission conditions comparable, changing one harness variable at a time. A long final response or a high tool-call count is not a productivity metric. For stopping rules and recovery behavior, continue with Loop Engineering.

Safety and Troubleshooting

The project's safety notice says it has not undergone a security audit and is not production-ready. Approvals and sandboxing reduce risk; they do not guarantee isolation. Prefer a disposable VM, container, or dedicated environment, expose only necessary code, keep backups, and withhold production cloud credentials and SSH private keys. Safety notice →

Local execution also does not mean zero outbound data. A remote model needs relevant context; tools, plugins, and telemetry have additional data paths. Review the current version's data-processing settings and your organization's rules before connecting company code. A localhost address alone tells you very little about that boundary. Data-processing notes →

When Is It Worth Using?

DeepSeek Harness is worth a bounded trial if you want to study agent execution, connect a custom model gateway, or adapt tools and plugins around an engineering workflow. If your priority is a low-maintenance coding assistant, include preview-version configuration and upgrade work in the comparison. Customizability is both a capability and a maintenance responsibility.