Quickstart

DeepSeek Harness is DeepSeek's open-source, production-grade AI Agent execution engine and scaffolding. Rooted in the "Agent = Model + Harness" engineering paradigm, it equips Large Language Models with safe shell execution, precision code diff tooling, stateful context persistence, and an extensible microkernel built on the Cordis framework.

This guide walks you through prerequisite setup, 4 installation methods (npx zero-config, source clone, Python SDK, and desktop client), and LLM Provider API configuration.

System Requirements & Prerequisites#

Before installing and running DeepSeek Harness, verify that your environment satisfies the following minimum requirements:

Verify your environment

node -v
npm -v
git --version

Method 1: Zero-Config Web UI Launch via npx (Recommended)#

For most developers and evaluators, you can spin up the full visual workbench with a single command without manual compilation:

Launch the Web Console

Run the official CLI launcher in your terminal:

npx @deepseek-ai/dsh web

• This command pulls the latest runtime container from npm;
• Once booted, the terminal outputs the local listener address:
  [DeepSeek Harness] Web UI started successfully!
  ➜ Local:   http://localhost:5173/
  ➜ Network: http://192.168.1.10:5173/
  

Access the Dashboard

Open http://localhost:5173/ in your browser to start interacting with the autonomous Agent workbench.

Method 2: GitHub Source Cloning for Development#

If you plan to develop custom Cordis plugins, customize Tool-Contract schemas, debug low-level Fiber lifecycle hooks, or integrate private enterprise proxies, clone the repository directly:

Clone the Repository

git clone https://github.com/deepseek-ai/deepseek-harness.git
cd deepseek-harness

Install Dependencies & Start Dev Server

# Install dependencies using pnpm or npm
npm install

# Start local development server with hot-module reloading
npm run dev

Method 3: Python SDK Programmatic Integration#

For teams building data pipelines, automated benchmark runners, or Python-native agent loops, install the official SDK via PyPI:

# Create and activate a virtual environment
python -m venv .venv
source .venv/bin/activate  # On Windows run: .venv\Scripts\activate

# Install the SDK package
pip install deepseek-harness-sdk

Instantiate the Agent in Python

from deepseek_harness import AgentHarness, AgentConfig

# Instantiate the Harness client
harness = AgentHarness(
    config=AgentConfig(
        model="deepseek-chat",
        api_key="your_deepseek_api_key",
        mode="standard"
    )
)

# Run a multi-turn prompt or code refactor task
response = harness.execute_prompt("Inspect the repository files and generate a dependency diagram.")
print(response.content)

Method 4: Third-Party Desktop Client (Windows & macOS)#

For product managers, prompt engineers, or developers seeking a standalone desktop app without managing Node.js terminal sessions, pre-packaged desktop builds are available:

• Graphical User Interface: Standalone desktop app with tray support and background session management;
• Self-Contained Runtime: Bundled sandboxing and execution runtimes that avoid version conflicts with local node environments;
• Visual Key Management: Easily configure and switch between DeepSeek, OpenAI, Anthropic, and local Ollama endpoints.

Download Desktop Builds

You can download native installers directly from our Download Center:

• Windows Client: Download the .exe setup package and follow the setup wizard;
• macOS Client: Download the .dmg disk image and drag the application to your Applications folder.

Configuring LLM Providers & API Credentials#

Once the Web UI is running, configure your inference model provider and API credentials.

Configure via Web UI

1. Navigate to Settings -> Providers;
2. Select DeepSeek Official API (or OpenAI / Anthropic / Local Ollama endpoints);
3. Enter your API credentials:
   • DeepSeek API Key: sk-xxxxxxxxxxxxxxxxxxxxxxxx
   • Base URL: https://api.deepseek.com (default)
4. Choose default models:
   • DeepSeek-V3 (deepseek-chat): High-throughput code editing and command planning;
   • DeepSeek-R1 (deepseek-reasoner): In-depth multi-step reasoning, mathematical proofing, and architecture audits.

Declarative Configuration via cordis.yml

For containerized or headless setups, inject credentials via .env or cordis.yml:

# cordis.yml configuration example
plugins:
  # Official LLM Adapter Plugin
  '@deepseek-ai/dsh-plugin-llm-adapter':
    provider: 'deepseek'
    apiKey: 'env(DEEPSEEK_API_KEY)'
    defaultModel: 'deepseek-chat'
    temperature: 0.0

  # Terminal Command Execution Tool
  '@deepseek-ai/dsh-plugin-tool-bash':
    timeout: 30000
    allowRoot: false

Switching Preset Execution Modes#

DeepSeek Harness provides 4 preset execution modes tailored for different engineering stages:

# Standard Mode (Default: Full bash, code reading, and diff replacement tools)
npx @deepseek-ai/dsh --mode standard

# PTC Mode (Programmatic Tool Calling: TypeScript Code Mode orchestration)
npx @deepseek-ai/dsh --mode ptc

# Minimal Mode (Zero-noise dual tools for DSBench & LM-Eval benchmarks)
npx @deepseek-ai/dsh --mode minimal

# Creative Mode (In-memory playground for testing Cordis plugin lifecycles)
npx @deepseek-ai/dsh --mode creative

Verifying Installation with Your First Agent Task#

With the setup complete, run your first validation command in the Web UI:

• Prompt: Create a lightweight Node.js CLI tool with automated unit tests;
• Observe the Agent Loop:
  • Reasoning: The model generates a task execution blueprint;
  • Tool Actions: Harness writes files and initializes project structures;
  • Self-Correction: Runs npm test and parses error logs for autonomous self-healing;
  • Trajectory Trace: Click the Trajectory tab to audit all actions, diffs, and Token usage.

FAQ & Troubleshooting#

Q1: What should I do if port 5173 is already occupied?

Answer: By default, Harness Web UI binds to port 5173. You can specify a custom port using --port:

npx @deepseek-ai/dsh web --port 8080

Or check for occupied processes via lsof -i :5173 on macOS/Linux.

Q2: Why wasn't Docker sandbox isolation triggered during shell execution?

Answer: Standard Mode executes within a restricted local host child process by default for lightweight evaluation. To enable containerized Docker isolation, ensure Docker Desktop is running and pass the --sandbox docker CLI flag, or activate the @deepseek-ai/dsh-plugin-sandbox-docker plugin in your cordis.yml.

Q3: How to deploy in offline or private intranet environments?

Answer: Use Method 2 (GitHub source clone). Run npm install in an environment with internet access to download dependencies, then transfer the codebase to your air-gapped server. Start via npm run dev and point the LLM Base URL to an on-premise model gateway or local Ollama instance.

Q4: Why is Token consumption significantly lower in multi-turn refactoring tasks?

Answer: DeepSeek Harness natively aligns with DeepSeek's Prefix Caching mechanisms. Tool schemas and conversation histories are appended strictly in immutable sequence, achieving up to 99.93% prefix cache hits across complex multi-turn sessions and saving 80%+ compute Token costs.