DeepSeek Harness Guide

English | 简体中文 | 繁體中文 | 日本語 | 한국어 | Deutsch | Español | Français | Italiano | Português | Русский | العربية | Bahasa Indonesia | ไทย | Tiếng Việt

DeepSeek Harness Guide — From First Run to Agent Development

A multilingual, developer-oriented guide to understanding, running, extending, and building agents with DeepSeek Harness.

DeepSeek Harness (dsh) is an open-source agent runtime and composition framework from DeepSeek AI. It connects models, prompts, tools, permissions, sandboxes, sessions, subagents, telemetry, and user interfaces into a working agent—and makes those parts replaceable through a shared plugin architecture.

This repository explains that system in practical terms. It is an independent community guide, not an official DeepSeek project.

• What is DeepSeek Harness?
• Architecture
• Quick start
• Install and use a DSH Plugin: OpenPencil example
• Develop an agent with DSH
• Choose the right extension
• Documentation map
• Reusable Agent Skills
• Security and compatibility
• flaq.ai model APIs and affiliate program

A model can generate text or tool calls, but it does not by itself manage a workspace, execute tools safely, preserve a session, request approval, recover from cancellation, coordinate subagents, or expose a user interface. An agent harness supplies that operating layer.

DSH is useful in two related roles:

1. A ready-to-run agent application — start the official Web UI, configure a model, select a workspace, and run agent sessions.
2. A framework for assembling agent products — replace or add model providers, tools, Agent Loops, storage, sandboxes, policies, surfaces, and workflows without maintaining a full runtime fork.

Its defining idea is Everything is a Plugin. Built-in capabilities and third-party extensions use the same composition mechanism, powered by Cordis. This makes DSH closer to a configurable agent runtime than to a single fixed coding assistant.

The official project provides the implementation and reference contracts. This guide adds:

• a stable mental model for the fast-moving source tree;
• multilingual architecture and operating documentation;
• decision paths for Agent, tool, provider, session, and UI development;
• security and lifecycle review checklists;
• reusable Skills that help coding agents explore, scaffold, build, and review DSH extensions.

DSH has two cooperating structures:

• the runtime plugin graph defines which capabilities are available, where they are visible, and who owns their lifecycle;
• the Session event stream preserves the durable facts needed to reconstruct model-visible history and interface state.

The Agent Loop connects them by reading model, prompt, tool, policy, and storage capabilities from the graph, executing work, and writing results back to the Session.

flowchart LR
 C["Profile + Bundles + Patches"] --> L["Cordis Loader"]
 L --> G["Runtime plugin graph"]
 G --> A["Agent Loop"]
 A --> M["Model providers"]
 A --> T["Tools + policy + sandbox"]
 A --> S["Session event stream"]
 S --> A
 S --> H["Host APIs"]
 H --> U["Web / desktop / TUI / other clients"]

A typical turn follows this path:

1. reconstruct model-visible context from durable Session events;
2. assemble the system prompt, tool schemas, model route, and policy state;
3. stream a model response;
4. validate, authorize, approve, and execute requested tools;
5. persist canonical results as Session events;
6. continue until the Agent Loop's completion condition is met;
7. project the same event state to Web or other clients.

For Context, Service, Fiber, Effect, Event, Session, Turn/Step, caching, and security boundaries, read the technical architecture guide.

Install Node.js 22.19 or a 24+ release (and re-check the official development guide before deployment), then run:

npx @deepseek-ai/dsh web

Open http://127.0.0.1:3080, configure a model service in Settings → Models, select a workspace, and begin with a non-destructive task.

Inspect the effective plugin tree before debugging extensions:

dsh --profile web --dump-config

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

Programmatic embedding is also available through the official Python SDK. See the usage handbook for SDK setup, plugin installation, rollback, and troubleshooting.

This walkthrough turns the OpenPencil flow shown in the referenced guide into a reproducible plugin workflow. In DSH, a Plugin provides runtime behavior, a Bundle distributes a configuration layer through dsh.bundle, and a Profile selects ordered Bundles and local configuration for one runnable environment. Installing a package into web therefore changes that Profile; it does not modify every DSH installation.

• Configure a tool-calling model provider in DSH. A configured flaq.ai model can be used, but OpenPencil is a tool plugin rather than a Flaq-only integration.
• Stop the running Web UI before changing its Profile.
• Install OpenPencil from its official repository and confirm that its op executable is visible to the shell with op --version.
• Run all commands from the same project environment so they resolve the same DSH home and web Profile.

The referenced example uses the public OpenPencil plugin package:

npx --yes -p @deepseek-ai/dsh@0.1.0-rc.6 dsh plugin --profile web add @zseven-w/dsh-openpencil@latest

For production or shared development environments, first verify the package publisher, source repository, release notes, requested permissions, install scripts, and compatibility range. Replace @latest with the exact version you tested.

Before starting the UI, confirm that the expected Bundle and plugin rows are present:

npx --yes -p @deepseek-ai/dsh@0.1.0-rc.6 dsh --profile web --dump-config

--dump-config shows the final ordered composition after Bundle patches, the Profile patch, home-level patches, and command-line patches. If the plugin is absent, check the selected Profile and whether every command is resolving the same DSH home.

npx --yes -p @deepseek-ai/dsh@0.1.0-rc.6 dsh web

Open the Web UI, select the configured model and workspace, create a new session, and try a bounded request such as:

Create a simple editable OpenPencil document with a title, a subtitle,
and two feature cards. Save it as harness-guide.op, inspect the document,
and summarize its layers.

A successful run should expose the OpenPencil tools to the model, create an .op document, and return an inspectable or editable result. Review the proposed tool call before approval and start in a disposable workspace.

Stop the Web UI, remove the package from the same Profile, inspect the composition again, and restart:

npx --yes -p @deepseek-ai/dsh@0.1.0-rc.6 dsh plugin --profile web remove @zseven-w/dsh-openpencil
npx --yes -p @deepseek-ai/dsh@0.1.0-rc.6 dsh --profile web --dump-config

If an upgrade fails, restore the previously tested DSH and plugin versions instead of changing both at once.

A focused DSH Tool plugin follows a small lifecycle-aware contract:

import type { Context } from '@deepseek-ai/cordis'
import { defineTool } from '@deepseek-ai/dsh-tools'
export const name = 'example-tool'
export const inject = ['tools']
export function apply(ctx: Context) {
 ctx.tools.register(defineTool({
 name: 'echo_text',
 description: 'Return text for a connectivity test.',
 parameters: {
 text: { type: 'string', required: true, description: 'Text to return.' },
 },
 output: {
 schema: { type: 'string' },
 render: (_args, value) => [{ type: 'text', text: value }],
 },
 async execute({ text }) {
 return text
 },
 }))
}

The important design rules are:

1. declare consumed Services with inject so the plugin mounts only when its dependencies are ready;
2. keep parameters strict and validate all external input;
3. let execute return the canonical result and use output.render to create model-facing content;
4. register timers, listeners, tools, and other resources through the owning Context so unload cleans them up;
5. test locally with a Patch, then package the configuration as a Bundle using dsh.bundle;
6. install into a disposable Profile, inspect --dump-config, and test load, denial, cancellation, unload, remount, removal, and rollback;
7. pin Git/package dependencies and review lifecycle scripts because installation scripts execute outside the Agent sandbox.

Continue with the official first-plugin tutorial, Tool tutorial, plugin packaging guide, and this repository's dsh-plugin-scaffold and dsh-tool-builder Skills.

Building an Agent usually means composing several DSH extension points, not writing one large plugin.

Write down the target user, task boundary, allowed side effects, required data, completion condition, budget, cancellation behavior, and human-approval points. This determines which runtime capabilities are actually needed.

Start from a Profile close to the target host, add versioned Bundles, and keep environment-specific changes in Patches. Use a disposable Profile while developing external plugins.

Choose or implement the model provider, then define prompt assembly, workspace instructions, memory, compaction, and tool visibility. Keep stable prompt and tool-schema prefixes stable where possible so provider-side prefix caching remains useful.

Create narrow providers and consumers:

• tools for model-requested actions;
• Services for reusable runtime capabilities;
• Events for observation and interception;
• model, filesystem, process, sandbox, storage, telemetry, or subagent providers when existing implementations do not fit.

Declare consumed Services through inject, and register resources through lifecycle-aware ctx helpers.

Use the existing loop when only prompts, tools, or policies change. Replace or wrap the Agent Loop only when planning, routing, validation, handoff, retry, or completion semantics genuinely differ. Keep schema validation, authorization, user approval, and OS sandboxing as separate controls.

If a fact is later visible to the model or UI, persist it as a canonical Session event. Treat UI state as a projection, not the source of truth. Test cancellation, partial tool failure, restart, compaction, and replay.

Runtime behavior belongs in the Host. Browser presentation belongs in a Client plugin. Cross-boundary features should use a typed remote API instead of duplicating state in the UI.

Package distributable configuration as a Bundle, install it into a disposable Profile, inspect --dump-config, and test mount, normal use, denial, timeout, unload, remount, restart, removal, and rollback.

Common Agent product modules include workflow and planning, tools and integrations, context and memory, sessions and replay, subagents, model routing, browser and vision, policy and sandboxing, UI surfaces, and operations/telemetry. The usage handbook provides a categorized module map and installation checklist.

Every README, architecture guide, and usage handbook currently has 15 language entry points.

These repository-local Skills guide compatible coding agents through common DSH work. A Skill is an instruction workflow; it is not installed with dsh plugin and does not execute inside the DSH runtime.

• Pin DSH and third-party plugin revisions; preview APIs are not stable contracts.
• Inspect dsh --profile <name> --dump-config to verify the actual composition.
• Review dependency install and prepare scripts before allowing them to run.
• Treat same-process plugins, generated JavaScript, subprocesses, filesystem access, and network access as privileged behavior.
• Do not describe inject as a sandbox. Dependency visibility, policy, approval, and OS isolation are separate boundaries.
• Keep real credentials, private Sessions, screenshots, QR codes, and contact details out of examples and documentation.
• Treat ecosystem inclusion as discovery, not a security endorsement.

• DeepSeek Harness official repository
• Official architecture
• Official first-plugin tutorial
• Official tool tutorial
• Official packaging and installation guide
• Cordis and its spatiotemporal composability paper
• Community ecosystem classification reference

flaq.ai is a third-party AI model aggregation and API platform. Its LLM API exposes a managed Chat Completions route with streaming examples for JavaScript, Python, and cURL. Developers evaluating model providers for a DSH-based Agent can review these DeepSeek V4 endpoints:

Before connecting any third-party endpoint to DSH, verify the current base URL, model identifier, streaming behavior, tool-calling support, pricing, data handling, rate limits, and error contract against both services' latest documentation. Inclusion here is an integration option, not an availability, performance, or compatibility guarantee.

Developers and content creators may also apply to the flaq.ai Affiliate Program. Participation is governed by the current agreement and applicable law; affiliates must make required disclosures, avoid misleading promotion, and should not assume any guaranteed traffic, commission, payout, or earnings.

Corrections, translations, examples, revision-pinned case studies, and Skills are welcome. See CONTRIBUTING.md. This guide is available under the MIT License.