DeepSeek Harness

English | 中文

DeepSeek Harness (dsh) is an open-source agent harness developed by DeepSeek AI.

It uses an architecture where everything is a plugin, and is powered by Cordis, whose design is described in A Programming Paradigm for Spatiotemporal Composability.

Developer preview

DeepSeek Harness is currently in developer preview and is iterating rapidly. THERE WILL BE COMPATIBILITY-BREAKING CHANGES.

Run

Run from npm

Install Node.js, then run:

npx @deepseek-ai/dsh web

The command starts the Web UI, served at http://127.0.0.1:3080 by default. See Web UI guide.

Run from source

To run from a repository checkout:

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

Usage

Prerequisites

• Node.js ^22.19.0 or >=24.0.0
• pnpm 11.7.0
• A DEEPSEEK_API_KEY, provided in the environment or a .env file

export DEEPSEEK_API_KEY="your-api-key"

Run a headless task

Run one task, print the final assistant response, and exit:

pnpm dsh --profile headless "Inspect the current repository"

The headless profile creates a persisted session and does not start an HTTP server.

Run the Web UI

Start the Web UI on the default address or choose another port:

pnpm dsh web
pnpm dsh web --port 8080

Open http://127.0.0.1:3080 or the port printed by the launcher. Use pnpm dsh web --help to list Web options.

Configure permissions and composition

New sessions use workspace-write with approval by default. Use read-only when the agent must not modify files:

DSH_PERMISSION_MODE=read-only pnpm dsh web

Inspect the composed profile or apply a temporary patch:

pnpm dsh web --dump-default-config
pnpm dsh web --patch examples/web-schedule/cordis.yml

Install a plugin

Install a local or Git-hosted plugin into a profile, then run that profile:

pnpm dsh plugin --profile demo add ./my-plugin
pnpm dsh --profile demo

The plugin must provide the Cordis configuration and package metadata expected by the profile loader. See the plugin tutorial and CLI reference for extension details.

Use automation interfaces

The ACP example starts a JSON-RPC automation server for programmatic clients:

pnpm run demo:acp

See the Web UI guide, ACP example, and Python SDK guide for client-specific usage.

Community and support

• Feel free to submit feedback or bug reports through GitHub Discussions.
• Add the dsh-plugin topic to your plugin repository for discoverability.
• Join DeepSeek Harness Discord community.

Contributing

See CONTRIBUTING.md.

Development

Start with the development guide and architecture documentation.

For agents, follow AGENTS.md.

License

MIT

Third-party dependencies and their licenses are disclosed in THIRD_PARTY_NOTICES.md.