DeepSeek Harness Not Working? Fix Ollama and API Errors

Learn more：https://treerouter.com

Abstract

Released in August 2026 under the MIT open‑source license, DeepSeek Harness (dsh) is a plugin‑first agent execution framework with more than 250 000 GitHub stars. Its Cordis‑based plugin architecture fully decouples model‑invocation layers, tool execution logic and persistent storage components. Beyond DeepSeek’s official API endpoints, Harness supports arbitrary OpenAI‑compatible inference back‑ends via the Custom‑model‑API provider abstraction. This capability enables seamless integration with local inference stacks including Ollama and vLLM, alongside private‑network or third‑party gateway services that implement OpenAI Chat Completions, OpenAI Responses or Anthropic‑Messages schemas. This article describes the underlying integration mechanics, presents three practical configuration pathways: graphical Web‑UI setup, manual editing of cordis.patch.yml, and compatibility adjustments for reasoning‑mode (thinking‑mode) parameters. It also compiles troubleshooting guidance for common runtime failures. All configuration examples are sourced from official DeepSeek Harness documentation as of October 2026; since the framework remains in developer‑preview status, breaking interface changes may appear in future releases.

1. Core Principles of Local‑Model Integration in DeepSeek Harness

Model access inside Harness is managed by the built‑in dsh‑llm‑pi‑ai plugin. This plugin abstracts each upstream inference service as an independent provider configuration unit. Each provider record contains five mandatory logical fields:

1. Provider ID: Persistent immutable identifier used for request routing and credential references across conversation histories.
2. Base URL: Root endpoint address of the target inference service.
3. API protocol: Select one from three supported values: openai‑completions, openai‑responses, anthropic‑messages.
4. Credential: API key value or reference pointing to an environment variable holding secrets.
5. Models: List of available model identifiers exposed by this specific provider.

Modified provider configurations take effect immediately for subsequent requests; service restarts are not required. Sensitive API credentials are persisted inside $DSH_HOME/.credentials.yaml. Functional provider definitions are stored within profile‑scoped cordis.patch.yml configuration files. When launching Harness through its Web UI, the active profile is named web.

Environment variable DSH_HOME controls the root directory for Harness runtime files. Default paths differ across operating systems: macOS and Linux use ~/.dsh, while Windows uses %APPDATA%\dsh. Operators can override this location by explicitly exporting the DSH_HOME environment variable.

2. Approach One: Graphical Web‑UI Configuration (Recommended for Beginners)

This workflow requires no manual YAML editing. All settings are entered via browser‑based graphical forms.

Step 1: Launch DeepSeek Harness

Run Harness directly from npm without full repository cloning:

npx @deepseek‑ai/dsh web

By default, the service binds to http://127.0.0.1:3080 and automatically opens the browser interface.

Step 2: Create a new custom‑model provider

1. Navigate to Settings → Models within the Web UI.
2. Click Add model provider at the bottom of the configuration page.
3. Switch the configuration card to Custom model API (the default view shows third‑party managed providers).
4. Populate configuration fields, demonstrated with a local Ollama example:

1. Click Fetch available models. Harness sends a discovery request to the /v1/models endpoint and enumerates locally installed model variants. Tick target models in the popup window and select Add selected.
2. Click Save to persist changes. New configurations activate instantly.

> Important operational note: Once saved, Provider ID cannot be modified, as historical session logs reference this identifier. To rename a provider, create a brand‑new provider entry and remove the old definition.

3. Approach Two: Direct Editing of cordis.patch.yml (Recommended for Advanced Users)

Every setting submitted through the Web UI ultimately persists inside $DSH_HOME/profiles/web/cordis.patch.yml. Manual file editing unlocks advanced parameters not exposed in graphical forms, such as compat compatibility rules, reasoningEfforts mappings, custom request headers, timeout values and retry counts. Multiple independent providers can co‑exist within one configuration file.

Example 1: Ollama local‑model configuration

- id: llm‑pi‑ai
  config:
    providers:
      local‑ollama:
        api: openai‑completions
        baseURL: http://127.0.0.1:11434/v1
        models:
          - id: qwen3:8b
          - id: deepseek‑r1:7b
          - id: llama3.3:70b

Example 2: vLLM self‑hosted inference service

First start the vLLM OpenAI‑compatible backend service on your host machine:

vllm serve deepseek‑ai/DeepSeek‑V4.1‑Flash‑1017 \
  --port 8000 \
  --api‑key your‑vllm‑key

Add the corresponding provider definition inside cordis.patch.yml:

- id: llm‑pi‑ai
  config:
    providers:
      local‑vllm:
        api: openai‑completions
        baseURL: http://127.0.0.1:8000/v1
        apiKeyEnv: VLLM_API_KEY
        models:
          - id: deepseek‑ai/DeepSeek‑V4.1‑Flash‑1017

Example 3: Third‑party OpenAI‑compatible gateway

For unified inference gateways that implement OpenAI‑style interfaces, configuration patterns are identical to self‑hosted local services; only the baseURL and credential environment variable require updating. Teams managing dozens of heterogeneous model back‑ends can centralize endpoints via a unified API gateway such as Treerouter. This approach allows switching among dozens of supported model variants with a single API credential, without modifying Harness‑side provider definitions.

- id: llm‑pi‑ai
  config:
    providers:
      treerouter‑gateway:
        api: openai‑completions
        baseURL: https://treerouter.com/v1
        apiKeyEnv: TREEROUTER_API_KEY
        models:
          - id: deepseek‑v4.1‑flash
          - id: deepseek‑v4‑pro
          - id: kimi‑k3

After file edits complete, no application restart is required. The next agent request will consume updated provider rules. You can also configure timeout (unit: milliseconds) and retries fields within each provider block; these parameters are not surfaced in the Web‑UI graphical panels.

4. Approach Three: Fixing Reasoning‑Mode Compatibility Issues

Reasoning‑mode (thinking‑mode) incompatibility represents one of the most frequent failure sources when integrating third‑party or self‑hosted gateways. DeepSeek Harness transmits system prompts using the role: "developer" field and controls output token limits via the max_completion_tokens parameter. Many non‑DeepSeek upstream services lack native support for these two specifications, producing request rejection errors. The compat configuration block solves these mismatches.

Scenario 1: Resolve persistent request‑rejection errors

Add compatibility overrides inside your provider entry:

- id: llm‑pi‑ai
  config:
    providers:
      my‑gateway:
        api: openai‑completions
        baseURL: https://treerouter.com/v1
        apiKeyEnv: GATEWAY_API_KEY
        compat:
          supportsDeveloperRole: false   # Fall back to standard system role for system prompts
          maxTokensField: max_tokens     # Use legacy max_tokens instead of max_completion_tokens
        models:
          - id: my‑model

Scenario 2: Disable thinking‑mode for DeepSeek‑family models behind gateways

Certain gateway deployments keep reasoning mode enabled by default for DeepSeek models. Setting reasoning effort to off will not disable thinking behaviour unless the correct structured payload is sent. Enable thinkingFormat: deepseek to inject thinking: {type: disabled / enabled} structures:

        models:
          - id: deepseek‑v4‑pro
            compat:
              thinkingFormat: deepseek
            reasoningEfforts:
              off:
              high: high
              max: max

Scenario 3: Show reasoning‑effort selector menu for manually‑added models

When model identifiers are entered manually instead of fetched via discovery APIs, Harness cannot automatically detect reasoning‑capable models, and hides the reasoning‑effort UI selector. Declare reasoningEfforts mapping rules to restore this menu:

        models:
          - id: my‑reasoner
            reasoningEfforts:
              off:
              high: high
              max: max

5. Common Troubleshooting and Frequently Asked Questions

Q: Fetch‑available‑models action fails for Ollama integration

Three key inspection points:

1. Confirm Ollama background service is active and models have been downloaded; run ollama list for validation.
2. Verify the Base URL ends with /v1: correct value is http://127.0.0.1:11434/v1.
3. When Harness runs inside Docker containers, 127.0.0.1 points to the container itself. Replace it with host machine IP or special DNS name host.docker.internal.

Manual model‑ID entry still works normally even if automatic model discovery fails.

Q: Can multiple provider definitions co‑exist within one configuration?

Yes. Under config.providers of the llm‑pi‑ai plugin, you may define any number of independent providers. Each maintains isolated base URL, credentials and model catalogues. End‑users select target providers and corresponding models inside the session‑start model‑selection dropdown. Providers operate without mutual interference.

Q: After connecting local models, do Harness agent capabilities (file‑reading, shell execution) keep working?

Agent tool‑calling functions belong to separate plugin layers and remain fully functional, independent of which LLM provider you connect. Full agent loops work correctly as long as the selected local model properly implements function‑call schemas. Models lacking tool‑call support can only perform plain conversational tasks and cannot trigger multi‑step agent workflows.

Q: Where is the DSH_HOME directory located?

• macOS / Linux: ~/.dsh
• Windows: %APPDATA%\dsh

Customise the path by exporting environment variable DSH_HOME. Credential file .credentials.yaml and all profile‑specific configuration are stored under this directory.

Q: Can custom providers configure request timeout and automatic retry logic?

Yes, add top‑level timeout (milliseconds) and retries integer parameters directly under the provider YAML node. These two settings are not exposed in the graphical Web UI; manual YAML editing is mandatory. Changes take effect without service restarts.

6. Conclusion

DeepSeek Harness abstracts local and third‑party model integration into three core configuration primitives: provider identifier, base endpoint URL and API‑protocol selection. Connecting Ollama or vLLM inference back‑ends typically completes within five minutes. Most integration obstacles originate from compatibility gaps of third‑party gateways, and adjusting compat fields for developer role and token‑limit parameters resolves approximately 80 % of request‑rejection failures.

For engineering teams maintaining mixed‑model workloads, defining a single custom provider pointing toward a unified gateway greatly reduces configuration overhead. Operators retain Harness’s native user interface and agent tooling, while all upstream‑model switching, credential management and traffic‑routing logic shifts to the gateway layer.

As DeepSeek Harness stays in developer‑preview status, breaking configuration‑schema adjustments may appear in future releases. Production deployments should review official changelogs before upgrading framework versions.