Getting Started with DeepSeek Harness

This guide gets you a running DeepSeek Harness agent session in about 10 minutes. It assumes you've read the overview and know the basics: it's an MIT-licensed agent runtime where everything is a plugin.

1. Install

npx @deepseek-ai/dsh web

npx pulls the published package and starts the local web UI at http://127.0.0.1:3080 by default (add --no-open to skip opening a browser). Node 22 or later is required. Alternatives: run headless from the CLI, run the TUI (see below), or build from source per the repository README.

Pin your version. The project is at 0.1.0-rc.5 with no release tag and DeepSeek warns that compatibility-breaking changes are coming. Install with an exact version, e.g. npx @deepseek-ai/dsh@0.1.0-rc.5 web, and re-check the changelog before upgrades.

2. Pick a Preset

On first launch, you'll choose a preset. It sets the model, tools, skills, and configuration that make up the agent:

• Standard — the full coding agent: filesystem tools, shell, file and web search, skills, planning, goals, subagents, workflows
• Minimal — two tools only (bash and str_replace_editor); the configuration DeepSeek used for its own benchmark runs
• Code — generates a TypeScript SDK so the model writes a program instead of chaining tool calls
• Creator — Standard plus runtime inspection and preset-authoring tools for plugin developers

Start with Standard. Switch to Minimal when you want reproducible, benchmark-like behavior, or Code when you want the token-efficiency win of single-call programs.

3. Configure a Model

Harness is model-agnostic. Supported providers include Anthropic, OpenAI, AWS Bedrock, Microsoft Azure, Google's Gemini Enterprise Agent Platform, DeepSeek's endpoint, OpenCode (the opencode-go catalog route), and any custom OpenAI-compatible gateway.

The fastest path, with a DeepSeek API key, is the Models page in the web UI (Settings → Models): enter the key and save. Keys are stored write-only in $DSH_HOME/.credentials.yaml; settings.yaml keeps only the credential reference.

A minimal hand-written route in $DSH_HOME/settings.yaml:

llm-pi-ai:
  providers:
    deepseek:
      apiKeyEnv: DEEPSEEK_API_KEY
      api: openai-completions
      baseURL: https://api.deepseek.com/v1
      models:
        - id: deepseek-v4-pro
        - id: deepseek-v4-flash
agent-default-model:
  provider: deepseek
  model: deepseek-v4-pro

Create a .env file in your project root with DEEPSEEK_API_KEY=... and the harness picks it up. For catalog providers, custom OpenAI-compatible gateways, and OpenCode Zen/Go keys, see the Providers guide.

Subagent providers. Claude Code and Codex can be delegated to as subagents — both are off by default, and each resolves its binary from your PATH. Enable them only if you have those tools installed and logged in.

4. Start a Session

1. Open the web UI (by default at http://127.0.0.1:3080).
2. Open a project directory — the harness reads AGENTS.md and CLAUDE.md files there automatically.
3. Start a session and give it a task, for example: "Explain how authentication works in this repo and add a failing test for the login rate-limit."
4. Watch the Trajectory view: every system prompt, reasoning step, tool call, result, and subagent schedule is recorded in an append-only log. You can resume, fork, search, and replay sessions from this event stream.

Where the transcript lives

Each session is persisted under $DSH_HOME/sessions/ as an append-only event stream — not a clean "you said / I said" transcript. One directory per working-directory (slugged), one subdirectory per session:

~/.dsh/sessions/<slugged-cwd>/session-<uuid>/session.jsonl.zstd

For example, ~/.dsh/sessions/--Users-bruce-projects--/session-bb4aa3fe-4754-4401-9602-aa24a48d28fe/session.jsonl.zstd (mode 0600). The .zstd file is the plain JSONL log compressed with Zstandard — each line is one event {seq, time, type, data}. The meaningful turns are user/message and assistant/message; the …-chunks records (assistant/chunk, reasoning-chunks, text-chunks, tool-call-chunks) are token-level deltas, and the rest (tool/call, tool/result, step/start|end, turn/start|end, sandbox/mode, permission/preset, approval/policy, session/title) are the mechanics. The session record is the header (id, version, createdAt, cwd, agentPreset).

There's no built-in history browser or human-readable export — decompress and query the file:

zstd -dc <session>.jsonl.zstd | jq -r 'select(.type=="user/message" or .type=="assistant/message") | "\(.type): \((.data.message.content // .data.content) | map(.text // empty) | join(" "))"'

zstd is Zstandard (RFC 8878): a fast, lossless compressor (levels -1 to -19, plus --ultra). session.jsonl.zstd decompresses back to session.jsonl.

5. Going Headless

The web UI isn't the only surface. The same runtime drives a headless CLI (useful for scripts and CI) and a Python SDK (useful for embedding the harness in your own tooling). A terminal UI is also available as an installed profile — see the TUI guide. The session log is the same append-only event stream in every mode, so a session started in the web UI can be resumed from the CLI and vice versa.

6. What's Next

• TUI — run the harness from a terminal, installed as a profile plugin.
• Providers & Keys — catalog routes, custom gateways, and OpenCode Zen/Go keys.
• Plugins & Extending — how the Cordis plugin system works and how to build a tool.
• Verify behavior, don't trust the preset. DeepSeek's own benchmark numbers were run on the Minimal preset at max reasoning effort, and independent reruns show a reproduction gap (see the launch analysis). Run your own eval on your own tasks.
• Run it in OpenCode. If you prefer OpenCode as your harness, the OpenCode Integration page covers connecting DeepSeek V4 there, including the thinking-mode provider setup.