Tutorial

DeepSeek Harness Tutorial

A friendly, practical introduction to the open-source agent harness from DeepSeek AI — what it is, how it is built, and how to run your first task.

1. What an agent harness actually is

A coding harness is the runtime around a language model that makes it a working agent. A raw chat model can only answer questions; a harness gives it real capabilities: tools such as file editing, shell commands and search, sessions that keep context across turns, permission policies that decide which operations need approval, and a log that records every step so a run can be inspected, resumed or replayed.

DeepSeek Harness is exactly that runtime, and its design motto is short: everything is a plugin. Models, tools, skills, sessions, sandboxes, storage, loops, scheduling and even the UI are replaceable plugins on the Cordis framework. That architecture is what makes the project interesting: you adapt it without forking it.

2. The four presets

The project ships four agent presets, each tuned for a different way of working:

You do not have to pick once and forget it — presets are configuration, so you can switch per project or per session.

3. Every run is a record

Each session writes an append-only session log. That log powers a trajectory view where you can inspect exactly what the agent saw and did — prompts, reasoning, tool calls, file changes and results, attributed by source. For long-running agent work, this turns a black box into something you can audit, resume or replay.

Permission policies gate risky operations. When the active policy flags a command or an edit as sensitive, the Web UI asks for approval before the agent proceeds, and sandboxing options let you constrain what the agent can reach.

4. A quick tour of the Web UI

The official command starts a local Web UI:

npx @deepseek-ai/dsh web

Once the server is running you will see a small set of steps to complete in the UI:

1. Configure a model. Open Settings → Models, enter a DeepSeek API key (or pick another provider), and save. The model route becomes usable immediately — no server restart.
2. Choose a workspace. Add the project directory you started dsh in and select it. The session composer stays disabled until a workspace is selected.
3. Run a task. Start a session and send a prompt. The agent can read and edit workspace files, run commands, delegate work and maintain a plan — asking you before anything the permission policy flags.

A good first prompt from the official guide: "Summarize this repository and identify its main packages." It exercises reading, search and structured summarization without touching anything dangerous.

5. Models are a plugin too

You bring your own key. The model adapter is itself a plugin, so switching providers does not require changing the framework source:

• DeepSeek API — one API-key field under Settings → Models.
• Catalog providers such as Anthropic or OpenAI — pick the provider, enter its key; the installed catalog supplies endpoint, protocol and model list.
• Custom OpenAI-compatible endpoints — for company gateways, self-hosted servers or providers absent from the catalog, with a provider ID, base URL, API protocol, credential and at least one model.

Keys are write-only in the UI and stored in $DSH_HOME/.credentials.yaml, never displayed back to you.

6. What to do next

If you want to try it now, follow the step-by-step install guide. For deeper reading, the official documentation covers model providers, the Python SDK, CLI modes and plugin development, and the GitHub repository hosts the source and discussions.

Prefer a one-click desktop app that handles installation, setup and updates for you? That is exactly what we are building — join the waitlist to reserve early access.