DeepSeek Harness is often described as an open-source coding agent.

That description is correct, but incomplete.

The more interesting part is its architecture.

DeepSeek Harness is a configurable runtime for constructing agents from model adapters, tools, session services, execution backends, permission policies, interfaces, and agent loops.

Its central design rule is:

Everything is a plugin

This article examines the main technical ideas behind that design.

System Position

A language model API normally accepts a list of messages and returns generated content.

A tool-using agent needs a larger runtime:

User interface
    ↓
Session management
    ↓
Agent loop
    ↓
Prompt and tool assembly
    ↓
LLM adapter
    ↓
Tool-call interpretation
    ↓
Permission and sandbox layer
    ↓
Filesystem, shell, terminal, subagents

DeepSeek Harness provides these layers as a composed application.

It can be used through:

A Web profile
A headless profile
A Python SDK
Custom profiles and plugins

The current CLI package also includes dependencies for Bash, PowerShell, filesystem tools, subagents, MCP, jobs, goals, workflows, planning, Web access, and session utilities.

Cordis as the Composition Layer

DeepSeek Harness is built on Cordis.

Cordis plugins contribute services, events, and reversible effects to a shared context. In Harness, major subsystems are plugins rather than privileged hard-coded components.

Examples include:

LLM adapters
Tool registries
Session persistence
Prompt assembly
Agent loops
Filesystem providers
Shell executors
Sandbox providers
Approval policies
UI integrations

A minimal plugin looks like this:

import type { Context } from "@deepseek-ai/cordis";

export const name = "example-plugin";

export function apply(ctx: Context) {
  console.log("Plugin loaded");
}

A plugin can declare required services:

import type { Context } from "@deepseek-ai/cordis";

export const name = "tool-plugin";
export const inject = ["tools"];

export function apply(ctx: Context) {
  ctx.tools.register(/* tool definition */);
}

Cordis waits for declared dependencies before loading the plugin.

Registrations made through the context are automatically removed when the plugin unloads. Resources requiring explicit cleanup can use ctx.effect() and return a disposer.

This gives the runtime a controlled plugin lifecycle instead of relying on manual global registration.

Profiles, Bundles, and Patch Layers

A running Harness instance is composed from a plugin tree.

The main concepts are:

Profile

A profile defines the application configuration to boot.

The built-in templates include:

web
headless

A profile holds its bundle list, installed external plugins, and its own cordis.patch.yml.

Bundle

A bundle contains Cordis configuration rows and the code required by those rows.

The base bundle provides core services such as:

Model adapters
Tools
Persistence
Sandbox policy
Approval policy
Settings
Credentials
Telemetry

The Web application bundle adds the browser interface.

The headless bundle adds a one-shot non-server runner.

Patch layers

Configuration is applied in ordered layers:

Empty root
    ↓
Profile bundles, in order
    ↓
Profile cordis.patch.yml
    ↓
Harness home cordis.patch.yml
    ↓
Command-line --patch overlays

A patch can replace an existing configuration row by ID or insert a new row.

The effective tree can be inspected with:

dsh --profile web --dump-config

This architecture allows local customization without directly modifying the shipped bundles.

Agent Turn and Step Model

DeepSeek Harness distinguishes between a turn and a step.

A step contains:

One model request The tool calls generated by that request The corresponding tool results

A turn may contain zero or more steps.

A simplified flow is:

turn/start
    ↓
Claim user input
    ↓
Assemble prompt and tool schemas
    ↓
step/start
    ↓
LLM request
    ↓
Assistant output
    ↓
Tool calls
    ↓
Tool execution pipeline
    ↓
Tool results
    ↓
step/end
    ↓
Continue or stop
    ↓
turn/end

DeepSeek’s architecture documentation defines durable events for turn boundaries, step boundaries, user messages, assistant content, tool calls, and tool results. Live agent events are used to observe or intercept work while it is in progress.

This separation gives extension authors several possible interception points.

A plugin can:

Rewrite model input
Reject a step
Observe requests
Replace an LLM adapter
Intercept tool execution
Stop a turn
Inject additional context
Add persistent session state

Event Domains

The architecture separates events into several domains.

Session events

These are durable facts written to the session log.

Examples:

User messages
Assistant messages
Tool calls
Tool results
Permission changes
Turn boundaries

Use a session event when the information must survive reload or replay.

Agent events

These describe live execution.

Examples include:

Pre-step processing
Agent requests
Validation
Continuation
Stopping behavior

These events can observe or modify work in flight.

Capability events

These attach behavior to a subsystem seam without requiring the agent loop to import that subsystem directly.

Examples include filesystem, tool, and telemetry events.

This event separation reduces direct coupling between the agent loop and optional capabilities.

The Session Log as the Source of Model Context

DeepSeek Harness treats the session log as more than an audit file.

It is the source from which model-visible history is derived.

The architecture follows this rule:

Model-visible means logged

Anything that reaches a model request should be reconstructable from the session event stream.

This design supports:

Resume
Fork
Replay
Transcripts
Telemetry
Persistence
Debugging

It also creates a useful invariant for agent evaluation.

An evaluator can inspect:

Input supplied to the model
Tool schemas
Model responses
Tool requests
Tool results
Stop conditions

This makes the session trajectory suitable for reliability testing and regression analysis.

Capability Seams

DeepSeek Harness uses the idea of capability seams.

A complete seam normally contains:

A service definition
A service provider
A consumer

For example, filesystem access may include:

A filesystem interface
A local or remote implementation
Model-facing tools that consume it

The same model-facing tool could continue to work when the provider changes from local execution to a remote sandbox.

The architecture applies this approach to:

Filesystems
Shell execution
Terminals
Sandboxes
Subagents
LLM providers
Persistent jobs

This is useful because the agent loop does not need custom branches for every deployment.

A provider swap can change the execution environment while preserving the higher-level tool interface.

DeepSeek Model Adapter

The official DeepSeek adapter registers the provider route:

deepseek-official

Its default model catalog includes:

deepseek-v4-flash
deepseek-v4-pro

The adapter supports:

Streaming responses
Tool-call translation
Thinking control
Reasoning effort
Retry metadata
Context-window information
Cache-read usage
Structured error mapping
Dynamic settings
Per-request credential resolution

The default advertised context window is one million tokens for the two V4 models.

The adapter re-reads dynamic settings and credentials for each operation. This allows a changed API key or endpoint to take effect on the next request without restarting the whole application.

The credential is resolved through the Harness credential service or an environment variable. Literal keys are not stored directly in the model configuration block.

Tool Execution Pipeline

A model tool call does not execute immediately.

It passes through a guarded tool pipeline:

Model tool call
    ↓
tools/pre-execute
    ↓
Permission and policy handling
    ↓
tools/execute
    ↓
Provider implementation
    ↓
tools/post-execute
    ↓
Durable tool result

The architecture exposes pre-execution and post-execution extension points.

A plugin could use these points to:

Validate tool arguments
Add logging
Reject unsafe requests
Apply company policy
Measure execution time
Redact sensitive output
Add verification
Transform results

This is a more scalable approach than embedding all policy inside each individual tool.

Sandbox and Approval Are Independent

DeepSeek Harness models sandboxing and approval as two separate controls.

The default permission presets include:

workspace-write:
  sandbox: workspace-write
  approval: ask

danger-full-access:
  sandbox: danger-full-access
  approval: never

The preset is a user-facing bundle, but enforcement remains inside the underlying sandbox and approval services.

This distinction is important.

Approval answers:

Must the user confirm this action?

Sandboxing answers:

What resources can the action reach?

An approval dialog is not a filesystem boundary.

A sandbox is not a substitute for user intent.

Production systems should evaluate both.

Web, Headless, and Python Interfaces

The Web UI starts with:

npx @deepseek-ai/dsh web

It normally listens on:

http://127.0.0.1:3080

After startup, the user configures a model, selects a workspace, creates a session, and submits a task.

The headless profile runs a persisted one-shot task:

dsh --profile headless "inspect the repository and run tests"

The CLI also supports plugin management and profile-specific patch layers.

The Python SDK provides a programmatic interface around a bundled runtime:

from deepseek_harness import DeepSeekHarness

with DeepSeekHarness(
    provider="deepseek-official",
    model="deepseek-v4-flash",
    cwd="/path/to/workspace",
    session_root="/path/to/sessions",
    cordis="/path/to/config.yml",
) as harness:
    result = harness.run(
        "Inspect the repository and fix the failing tests.",
        session_id="example-001",
    )

print(result.final_response)

A reused session ID can preserve both conversation state and the session-owned shell process.

Current Limitations

The repository explicitly marks DeepSeek Harness as a developer preview and warns that compatibility-breaking changes will occur.

At the time of writing, the CLI package is still published as a release candidate.

Potential adoption risks include:

Changing configuration formats
Plugin API changes
Incomplete documentation
Provider compatibility differences
Security assumptions that vary by operating system
Limited operational history
Unstable third-party plugin ecosystem

The Python minimal example also warns that its danger-full-access configuration can modify any path available to the runtime process and should be used only inside a disposable checkout or container.

Conclusion

DeepSeek Harness is technically interesting because it treats the agent runtime as a composable system rather than a fixed application.

Learn more about DeepSeek Harness on my website.

Inside DeepSeek Harness: Cordis, Session Events, Tool Pipelines, and Permission Boundaries