DeepSeek Harness

DeepSeek Harness (dsh) is DeepSeek's open-source agent harness. It runs a local Web UI for agent sessions, tool execution, and repository work, and can also be embedded through its CLI or Python SDK.

DeepSeek Harness is provider-neutral: custom OpenAI-compatible endpoints are supported alongside DeepSeek's own API. Connected to our Swiss-hosted Everyware AI API, your prompts and source code are processed on our Swiss GPU infrastructure.

Key Features

Local Web UI: Agent sessions, file changes, and tool output in a browser interface.
Custom providers: Register OpenAI-compatible endpoints in a Cordis patch file.
Model picker: Configured models appear in the Web UI and become the default for new sessions.
Reasoning control: Declare effort levels per model; the UI shows an Effort menu.
Full data sovereignty: Model requests are routed through our Swiss Everyware AI API.

Developer preview

DeepSeek Harness is published as a developer preview. Configuration keys and behaviour may change between releases — verify the current documentation before rolling it out broadly.

Installation

DeepSeek Harness requires Node.js. Start the Web UI directly with npx:

npx @deepseek-ai/dsh web

The Web UI opens at http://127.0.0.1:3080. Useful flags: --port 8080, --host, --no-open.

From source

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

Configuration

1. Save API Key

Export your virtual API key as an environment variable before starting the harness:

export EW_AI_API_KEY="sk-bf-..."

Alternatively, store the key through the Web UI under Settings → Models; it is kept in $DSH_HOME/.credentials.yaml.

2. Register the Gateway

Create or edit ~/.dsh/profiles/web/cordis.patch.yml:

- id: llm-pi-ai
  config:
    providers:
      ew:
        displayName: Everyware AI API
        apiKeyEnv: EW_AI_API_KEY
        api: openai-completions
        baseURL: https://ai.ewcs.ch/v1
        compat:
          supportsDeveloperRole: false
          maxTokensField: max_tokens
        models:
          - id: ew/flagship
            name: Everyware Flagship
            contextWindow: 1048576
            maxTokens: 131072
            input: [text, image]
            reasoningEfforts:
              low: low
              high: high
          - id: ew/balanced
            name: Everyware Balanced
            contextWindow: 1000000
            maxTokens: 131072
            input: [text, image]
            reasoningEfforts:
              low: low
              high: high
          - id: ew/fast
            name: Everyware Fast
            contextWindow: 262144
            maxTokens: 131072
            input: [text, image]
            reasoningEfforts:
              low: low
              high: high

apiKeyEnv is the name of the environment variable, not the key itself. A literal key is not written into the YAML.

The compat block is the usual first fix for non-OpenAI gateways: supportsDeveloperRole: false avoids the developer role, and maxTokensField: max_tokens avoids max_completion_tokens.

Configuration is replaced, not merged

A Cordis override replaces the complete configuration entry. When editing an existing llm-pi-ai block, keep all other providers and fields in the file.

3. Start and Select a Model

npx @deepseek-ai/dsh web

In the Web UI, select the model from the model picker. Selecting a model also makes it the default for new sessions. If the gateway's /v1/models endpoint returns a standard list, Fetch available models can populate the list automatically; otherwise enter the model IDs manually.

Typical Workflows

Interactive Web UI:
```
npx @deepseek-ai/dsh web
```
Change the port:
```
npx @deepseek-ai/dsh web --port 8080
```

One-shot execution:

npx @deepseek-ai/dsh --profile headless "Explain the architecture of this repository."

Optional terminal UI (external plugin):

npx @deepseek-ai/dsh plugin --profile tui add github:deepseek-harness/turtle-ui
npx @deepseek-ai/dsh --profile tui

Telemetry and session logs

DeepSeek Harness uploads session logs to DeepSeek by default — including sessions that use a configured gateway. For Swiss data sovereignty, disable Settings → General → Upload Session Log (or set telemetry enabled: false) and set DSH_TELEMETRY_MODE=DISABLED for OpenTelemetry uploads.