# DeepSeek Harness: Open-Source Coding Agent Guide

> DeepSeek Harness is DeepSeek's open-source coding agent and runtime. Learn what it does, how to install it, and how to connect OmniaKey step by step.

- Canonical HTML: https://omniakey.com/blog/deepseek-harness-omniakey-setup
- Markdown: https://omniakey.com/blog/deepseek-harness-omniakey-setup.md
- Published: 2026-08-14 (updated 2026-09-18)
- Author: Kiki, COO at OmniaKey
- Language: en
- Category: API setup
- Reading time: 10 min
- All posts: https://omniakey.com/blog/llms.txt

---

DeepSeek Harness is an open-source coding agent and agent runtime from DeepSeek AI. It supplies the loop, tools, workspace access, sessions, permissions, and interface around a model. The model still comes from an API provider. This tutorial first explains what the DeepSeek code harness does, then connects it to OmniaKey through its official custom-provider flow.

> **Fact-checked September 18, 2026.** The install command, default port, provider fields, model-discovery behavior, credential storage, and preview warning were cross-checked against DeepSeek's product page, documentation, GitHub README, and current source. The OmniaKey Base URL and model IDs were checked against the current API documentation and catalog. DeepSeek Harness launched locally and the configuration screen was inspected; no paid model benchmark was run.

## What is DeepSeek Harness?

DeepSeek Harness, abbreviated `dsh`, is not a new language model. It is the software that turns a model into an agent that can understand a workspace, call tools, edit files, run commands, preserve sessions, and ask for approval.

Some launch coverage calls DeepSeek Harness an open-source AI agent framework. The official materials are more specific: an open-source agent harness, a local-first extensible coding agent, and an agent development/runtime environment.

DeepSeek Harness centers on **everything is a plugin**. It is built on the Cordis plugin system, so models, tools, skills, sessions, sandboxes, storage, loops, scheduling, and even the UI can be replaced or recomposed through configuration.

|Capability|What it means in practice|
|-|-|
|Plugin-first runtime|Swap or extend models, tools, storage, sessions, and other agent capabilities|
|Traceable sessions|Inspect prompts, reasoning, tool calls, tool results, context injection, and subagent scheduling in one append-only log|
|Multiple modes|Standard, Code, Minimal, and Creator modes expose different tool and orchestration surfaces|
|Local Web UI|The npm command serves the interface on `http://127.0.0.1:3080` by default|
|Custom providers|Add a company gateway or self-hosted OpenAI-compatible endpoint without changing Harness source|

The DeepSeek Harness traceable event stream is more than a chat transcript. The official docs describe resume, fork, search, and replay as operations over the same session log, which is useful when an agent makes several tool calls before producing an answer.

### What DeepSeek Harness is not

- Harness is not DeepSeek V4 Pro or any other model. A harness and a model are separate layers.
- It is not currently a stable production release. DeepSeek labels it a **developer preview** and warns that compatibility-breaking changes will occur.
- Harness is not a hosted coding service when run with the npm quick start. The Web UI binds to local loopback by default.
- Open source does not make model inference free. The repository uses the MIT license, while API usage is billed by whichever provider key you configure.

## DeepSeek Harness OmniaKey settings

Here is the complete configuration before the detailed steps:

|Field|Value|
|-|-|
|Provider ID|`omniakey`|
|Display name|`OmniaKey`|
|Base URL|`https://api.omniakey.com/v1`|
|API protocol|`openai-completions`|
|API key|A dedicated key from your OmniaKey dashboard|
|Starting model|`deepseek-v4-pro` or `deepseek-v4-flash`|

The `/v1` suffix belongs in the Base URL. Do not use the bare origin, do not duplicate it as `/v1/v1`, and do not paste the full `/chat/completions` request path. DeepSeek Harness appends the operation path itself.

## 1. Install and start DeepSeek Harness

Install Node.js, open a terminal in the project directory you want Harness to inspect, and run the official npm quick start:

```bash
npx @deepseek-ai/dsh web
```

The current command starts the Web UI at:

```text
http://127.0.0.1:3080
```

If port `3080` is already occupied, the Web profile accepts another port:

```bash
npx @deepseek-ai/dsh web --port 3081
```

The directory where you launch `dsh` becomes the filesystem location Harness uses by default, but the composer remains unavailable until you add and select a workspace in the UI. Choose the repository deliberately; the agent can receive file and shell tools according to the active permission policy.

## 2. Create a dedicated OmniaKey API key

Open the [OmniaKey API Keys dashboard](https://omniakey.com/dashboard/tokens) and create a key specifically for DeepSeek Harness. A separate key is easier to cap, rotate, revoke, and audit than a credential shared by several tools.

Keep the literal key out of repositories, shell history, screenshots, issue reports, and chat logs. The Web UI treats saved keys as write-only: DeepSeek documents that the secret is stored in `$DSH_HOME/.credentials.yaml`, while settings retain only a credential reference and the page receives a redacted descriptor.

## 3. Add OmniaKey as a custom provider

On a fresh install, accept the **Internal Testing Notice** with **Continue**. The next Harness onboarding dialog asks for an official DeepSeek API key; choose **Configure later** because OmniaKey belongs in a custom provider rather than that built-in official route.

In DeepSeek Harness, open **Settings → Models**, choose **Add a custom provider**, and enter the values below:

1. Set **Provider ID** to `omniakey`. Provider IDs must begin with a lowercase letter.
2. Set **Display name** to `OmniaKey`.
3. Set **Base URL** to `https://api.omniakey.com/v1`.
4. Set **API protocol** to `openai-completions`.
5. Paste the dedicated OmniaKey key into **API key**.

The Provider ID is permanent in the current Harness design because saved sessions, defaults, requests, and credential references use it. The display name, Base URL, protocol, credential, and model list remain editable.

## 4. Fetch and select models

Under **Model catalog**, choose **Fetch available models**. For a custom OpenAI-compatible provider, DeepSeek Harness sends a bearer-authenticated `GET /models` request to the Base URL currently shown in the form. With the value above, that resolves to OmniaKey's `GET /v1/models` endpoint.

Select only the models you intend to use. For a DeepSeek Harness workflow, two practical starting IDs are:

|Model ID|When to start there|
|-|-|
|`deepseek-v4-pro`|Long-context coding and agent work where the flagship DeepSeek route is the priority|
|`deepseek-v4-flash`|Frequent, faster turns where lower input and output rates matter more|

OmniaKey also exposes supported Claude, GPT, Gemini, Grok, and GLM models through the same provider. Copy IDs from the [current model catalog](https://omniakey.com/models); model names are exact identifiers, not aliases.

If model discovery is unavailable, add an exact Model ID manually. DeepSeek Harness requires at least one model before it can create a custom provider.

## 5. Save, choose a workspace, and run a safe test

Save the provider, choose your project with **Choose workspace**, then start a new session and select `OmniaKey / deepseek-v4-pro` or `OmniaKey / deepseek-v4-flash` in the model picker.

Use a narrow read-only prompt first:

```text
Inspect package.json and summarize the available scripts. Do not edit files or run commands.
```

This first Harness test confirms that the workspace, provider, key, exact model ID, and basic response path work before you authorize an edit or shell command. A text response does not prove every tool-call pattern works, so test one reversible tool task before assigning a large refactor.

Model settings take effect on the next request without restarting the server. However, DeepSeek's guide says a session that has already sent a request retains the model recorded in its log. Start a new session after changing provider or model when you want an unambiguous test.

## Optional: configure OmniaKey in settings.yaml

The Web UI is the clearer first-run path. For a controlled local setup, DeepSeek Harness also supports a provider profile in `$DSH_HOME/settings.yaml` that references an environment variable instead of embedding the key:

```bash
export OMNIAKEY_API_KEY="your-omniakey-api-key"
```

```yaml
llm-pi-ai:
  providers:
    omniakey:
      displayName: OmniaKey
      apiKeyEnv: OMNIAKEY_API_KEY
      api: openai-completions
      baseURL: https://api.omniakey.com/v1
      models:
        - id: deepseek-v4-pro
        - id: deepseek-v4-flash
```

The key must be present in the Harness process environment. Do not replace `apiKeyEnv` with a literal secret in `settings.yaml`. The official `dsh-llm-pi-ai` reference explicitly recommends credential references so secrets do not enter the settings document.

## Why use OmniaKey with DeepSeek Harness?

DeepSeek Harness already supports custom gateways; OmniaKey turns that extension point into one reusable provider entry.

- **One configuration for several model families.** Switch the exact model ID in the Harness picker without creating a new gateway profile for every vendor.
- **Built-in model discovery path.** Harness can read OmniaKey's OpenAI-compatible model listing instead of making you type every ID from memory.
- **Separate operational controls.** Give Harness its own API key, quota, rotation lifecycle, and usage trail.
- **Explicit model identity.** OmniaKey's policy is no silent model substitution: the requested provider and model are the ones that run; an unavailable upstream returns a visible failure.
- **Pay for API usage, not another agent subscription.** OmniaKey uses prepaid, per-token billing. Current availability and rates remain visible in the catalog rather than being frozen into this article.

This does not make OmniaKey universally better than a direct DeepSeek key. Use the direct provider when you only need DeepSeek's native account and endpoint. OmniaKey is more useful when the same Harness installation needs a curated set of DeepSeek and other model families behind one key and one Base URL.

## Troubleshooting

### Fetch available models returns 401

The Base URL or API key was rejected. Confirm that the key came from OmniaKey, has no surrounding spaces, remains active, and is paired with exactly `https://api.omniakey.com/v1`. Model discovery uses bearer authentication.

### The provider returns 404

Check the Base URL before changing the model. Common errors are omitting `/v1`, duplicating it, or entering `https://api.omniakey.com/v1/chat/completions` as the Base URL.

### `UNKNOWN_MODEL`

The selected model is not in the custom provider's saved list. Fetch models again or add the exact ID shown in the OmniaKey catalog, then select it in a new session.

### `MISSING_CREDENTIAL`

Store the key through **Settings → Models** or make sure `OMNIAKEY_API_KEY` exists in the shell that launches DeepSeek Harness. Setting the variable in another terminal does not update an already-running process.

### The changed model does not appear to take effect

Start a new session. Existing Harness sessions retain the provider and model recorded in their append-only log after the first request.

### Text works but an agent tool fails

Basic text generation and structured tool use are different checks. Begin with a read-only tool task, inspect the Trajectory view in Harness, and verify the exact failure before increasing limits or permissions. A malformed tool call is not fixed by rotating a valid API key.

## Frequently asked questions

### Is DeepSeek Harness free?

The DeepSeek Harness source is available under the MIT license. Model inference is separate and can incur API charges through DeepSeek, OmniaKey, or another configured provider.

### Can DeepSeek Harness use DeepSeek V4 Pro through OmniaKey?

Yes. Add OmniaKey as an `openai-completions` custom provider and select the current exact ID `deepseek-v4-pro`. `deepseek-v4-flash` is also available as a lower-priced DeepSeek V4 route.

For the August 0813 release, official peak and off-peak rates, and worked token costs, read the [DeepSeek V4 Pro API pricing guide](https://omniakey.com/blog/deepseek-v4-pro-api-pricing).
For the newer Flash route, native vision, benchmark evidence, and the current V4 Pro status, read the [DeepSeek V4.1 Flash review](https://omniakey.com/blog/deepseek-v4-1-flash-review).

### Should I paste an OmniaKey key into the built-in DeepSeek card?

Use **Add a custom provider** instead. The built-in card configures the official DeepSeek route, while the custom-provider form is the documented path for a gateway and exposes the Base URL, protocol, and model list that OmniaKey needs.

### Can the same provider use Claude, GPT, or Gemini?

Yes, when the model is currently supported by OmniaKey's OpenAI-compatible surface. Fetch the live list and add the exact IDs you need. Protocol-specific features can differ, so verify tool behavior with the chosen model rather than assuming every model behaves identically. For Claude Opus 5.5, Claude Sonnet 5.5 and GPT-6.1, follow the [Claude and GPT setup guide](https://omniakey.com/blog/deepseek-harness-claude-gpt-setup): each model needs reasoning levels and a 128K output limit.

### Where does DeepSeek Harness store the API key?

Keys saved through the Models page are write-only and stored in `$DSH_HOME/.credentials.yaml`; settings retain the credential reference. For direct YAML configuration, use `apiKeyEnv` and supply the key to the process environment.

### Is DeepSeek Harness ready for a stable production workflow?

Treat it as an evaluation target today. DeepSeek explicitly calls the current release a developer preview and warns about compatibility-breaking changes. Pin versions, keep configuration backed up without secrets, and recheck the official guide after upgrades.

## Sources checked

- [DeepSeek Harness product page](https://deepseek.com/harness/)
- [DeepSeek Harness GitHub README](https://github.com/deepseek-ai/deepseek-harness)
- [Official Web UI quick start](https://deepseek-harness.github.io/deepseek-harness/en/guide/quickstart)
- [Official model and custom-provider guide](https://deepseek-harness.github.io/deepseek-harness/en/guide/providers)
- [Official dsh-llm-pi-ai provider reference](https://github.com/deepseek-ai/deepseek-harness/blob/master/packages/llm/llm-pi-ai/README.md)
- [OmniaKey OpenAI-compatible API reference](https://docs.omniakey.com/en/api/openai-compatible)
- [OmniaKey live model catalog](https://omniakey.com/models)
