DeepSeek Harness

A model answers requests; a harness supplies the execution environment, tools and session workflow around those requests. The official Web guide describes file access, commands and other agent operations. That makes a repository task a useful first trial.

Our recommendation is to begin with a read-only summary of a small project you understand. Avoid making your first check depend on a plugin marketplace, browser integration, external login or deployment. Add those only when the task actually needs them. A plugin being listed or installed does not show that it loaded successfully in your current session.

Choose the connection you actually need

• Official API, current Flash: use deepseek-flash. The October 17 update says this alias now serves V4.1-Flash-1017, with the same calling method and pricing as before the update. It is a moving alias, not a dated snapshot pin. Record the check date when comparing results.
• Existing V4 Pro workflow: deepseek-v4-pro is a separate API model, not another name for Flash. Keep it selected when reproducing an existing Pro result; compare the same task before changing your workflow. The model/pricing table distinguishes the routes and charges.
• Gateway or self-hosted endpoint: use Custom model API and the exact model ID exposed by that server. An upstream release name does not establish the gateway's ID, protocol or deployed weights.

What version does this guide use?

DeepSeek recommends Harness 0.2.1-rc.1 or later for the best experience with 1017; this is not a claim that every earlier version cannot connect. The 0.2.1-rc.2 release explicitly adds 1017 support and is the version used here. Both are prereleases. Pinning rc.2 makes the client setup reproducible; it does not pin the remote model behind deepseek-flash.

The composer may display DeepSeek-V4.1-Flash with a 1017 badge. The label plugin says this is fixed client presentation, not server capability proof; it leaves request IDs unchanged. A missing badge on another route does not by itself prove that the endpoint serves an old model.

Start the reviewed version

Install Node.js first. The official quick start uses npm's npx entry. For the release reviewed here, pin that published package version:

npx @deepseek-ai/[email protected] web

This command may download and run the package; it is provided for the reader and was not executed for this guide. An unversioned npx @deepseek-ai/dsh web follows npm's default release instead. Review the release notes before upgrading an existing setup and preserve its configuration first.

The default URL is http://127.0.0.1:3080. Use the address printed by your process. The README documents --no-open to suppress automatic browser opening; an SSH launch prints the host URL instead of opening a local browser.

Configure the official DeepSeek route

1. Open Settings → Models, enter your DeepSeek API key in the DeepSeek card and save. Changes take effect on the next request without restarting the server.
2. In the composer model picker, select the official DeepSeek Flash entry with API ID deepseek-flash. Do not invent deepseek-v4.1-flash-1017 as a request ID.
3. Start a new session to verify the selection. Selecting a model makes it the default for new sessions, but a session that has already sent a request retains the model recorded in its own log.

The provider guide says saved keys are write-only in the UI and stored in $DSH_HOME/.credentials.yaml; settings retain a reference. Keep this file and backups private. A detected environment variable or saved-key indicator is not a successful connection test. Do not paste a key into a task, screenshot or support report.

Configure a gateway only when needed

In Add model provider → Custom model API, supply a lowercase Provider ID, your endpoint's base URL, credential and at least one model. Match API protocol to the server: OpenAI Chat Completions, OpenAI Responses, or Anthropic Messages. These map to openai-completions, openai-responses, and anthropic-messages. A provider has one protocol; configure separate providers if you need two. The Provider ID becomes part of saved sessions and cannot be renamed in place. Configuration contract.

Use Fetch available models → Add selected, then save. If discovery is unsupported, enter the server's documented IDs manually. A built-in provider's catalog does not prove which models a gateway serves; use a custom provider for gateway discovery. A successful listing still does not test generation or tool calls.

For self-hosting, the 1017 model card states that this release has no Jinja-format chat template. Its reference encoding and deepseek-recipe handle conversation formatting and request/response conversion. Recipe is not a ready-to-run model server: inference, HTTP transport and tool execution must be supplied separately. Connect Harness after your server exposes a supported API; this guide does not deploy that server.

Choose a workspace

Use Choose workspace to add and select the project directory. A fresh Web UI has no selected workspace even though the process has an invoking directory; the composer remains unavailable until one is selected. Web UI guide.

Verify the route before increasing access

• Confirm the local page opens and the new session shows the intended provider/model.
• Check the selected workspace path, then run the small read-only prompt below only when you accept the provider's usage charges.
• Inspect the answer against actual files. Record the Harness version, provider, model ID, date and any redacted error.
• If checking tool use, inspect the recorded tool result and file path; text claiming a file was read is insufficient.

A working UI, a configured credential and a successful model request are three different checks. A UI badge alone cannot identify exact remote weights. MIT software licensing does not make hosted inference free. The API pricing page governs token charges; a gateway may bill separately. Search/Fetch configuration and separate fees are covered in our Search/Fetch guide.

Editorial first-task prompt; not an executed test:

Read this workspace without editing files or running shell commands.
Identify its main entry point, package structure and test entry points.
Support each statement with a repository-relative file path.
List anything you could not determine as unknown.
Do not install plugins, open external accounts, commit or deploy.
Stop after returning the repository map.

Check that every cited path exists in the selected workspace. Compare the proposed test entry point with package scripts or project documentation. If the agent asks for access it does not need for this read-only task, resolve that before expanding scope.

For a later code change, hand it one failing behavior and a clear expected result. Require a diff and an actual check result. A completed chat turn, a plan or a claim that a test passed is not a substitute for inspecting the changed files and the test output.

The official safety notice describes access to model-generated commands, files, processes, network resources and third-party plugins. It warns that approval controls and sandboxing do not guarantee isolation. Limit the trial environment and credentials to what the task actually needs.

The project is in developer preview and explicitly warns of breaking changes. Keep a record of the version and selected model when reproducing a problem. Update deliberately, especially before reusing a workflow that previously worked.

Distinguish a route error from a task error

If the configured provider has no registered adapter, the model cannot start through that route. Check the saved provider/model selection and the provider setup before debugging the page or repository task. This guide does not claim that every provider is supported by every profile.

When handing work to another agent, leave the original workspace path, current diff, checks and remaining restrictions. Use one writer for the same files at a time. These are our handoff recommendations, not guarantees supplied by the product.

Troubleshoot the failing layer

The following checks follow the provider troubleshooting guide:

• MISSING_CREDENTIAL: save the intended provider's key or supply its documented environment variable. A detection hint does not validate the key.
• UNKNOWN_MODEL: select a configured ID. For the official Flash API use deepseek-flash; for a gateway use its own catalog.
• Old model still appears: try a new session, because an existing session retains its logged model. If the default provider was deleted, select a replacement when the composer shows Select model.
• CLIENT_UPGRADE_REQUIRED on an account route: follow the version named in the error. This account-service gate is distinct from the general rc.1 recommendation.
• Discovery returns 401 or an unreadable list: check credentials for 401; manually add documented IDs when the endpoint has no supported listing format. An empty list is not a generation test.
• Key and URL work, but requests fail: check the protocol and gateway's documented request shape. Some Chat Completions gateways reject developer messages or require max_tokens instead of max_completion_tokens. Apply compat.supportsDeveloperRole: false or compat.maxTokensField: max_tokens only where that endpoint requires them.
• No Effort menu for a custom model: declare only the reasoning levels and API values supported by that endpoint. DeepSeek's own route already supplies its levels. Do not copy a gateway's reasoning patch onto the official route just to reveal a menu.

Advanced settings live in $DSH_HOME/profiles/web/cordis.patch.yml for the standard Web profile, or the selected profile's corresponding path. Preserve other providers and fields when editing: a Cordis override replaces the complete entry configuration. Save a redacted error and stop after a failed verification; repeated retries can add usage without resolving a protocol mismatch.